Add a Recurring Plan

post

https://api-test.qualpay.com/platform/plan

Creates a new recurring plan. Generates a unique plan_id, which you can use to interact with or delete the plan.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Recurring plan object to be added

amt_tran

double

required

Format: Variable length, up to 12,2 N
Description: The plan transaction amount, which is the amount that will be billed each cycle.

plan_code

string

required

Format: Variable length, up to 16 AN
Description: A unique alphanumeric code provided by the merchant to identify the plan.

plan_desc

string

required

Format: Variable length AN
Description: A short description of the plan.

plan_duration

int32

required

Format: Variable length, up to 4 N
Description: Number of billing cycles in the recurring transaction. For example, if plan_frequency is 3 (monthly) and plan_duration is 6, the customer will be billed every month for 6 months. -1 indicates bill until canceled.

plan_frequency

integer

required

Format: Fixed length, 1 N
Description: The billing frequency. Use one of the following codes:

0 - Weekly
1 - Bi-weekly
3 - Monthly
4 - Quarterly
5 - Bi-annually
6 - Annually
7 - Daily

plan_name

string

required

Format: Variable length, up to 64 AN
Description: A unique name assigned to the plan.

interval

int32

Format: Variable length, up to 2 N
Description: Number of months or weeks in a subscription cycle. For example, if plan_frequency is 3 (monthly) and interval is 2, a customer on this plan will be billed every 2 months until the subscription is complete or canceled. Applicable only for monthly or weekly plan_frequency.
Default: 1

trial_duration

int32

Format: Variable length, up to 2 N
Description: Number of billing cycles in a trial period.

amt_trial

double

Format: Variable length, up to 12,2 N
Description: Amount to be billed during the trial period.

amt_setup

double

Format: Variable length, up to 12,2 N
Description: One-time fee amount. When adding a subscription with this plan, a payment gateway sale transaction will be initiated to charge the customer the one-time fee.

tran_currency

string

Format: Fixed length, 3 AN
Description: The ISO numeric currency code. This must be a currency code associated with one of your payment profiles; contact Qualpay to add currencies. If profile_id is provided, the currency is determined from the profile. Refer to Currency Codes for a list of currency codes.
Default: 840

profile_id

string

Format: Fixed length, 20 N
Description: The Payment Gateway profile ID that will be used for subscriptions on this plan. If profile_id is not provided, tran_currency will be used. If neither profile_id nor tran_currency is provided, the default USD profile is used.

bill_specific_day

boolean

Description: If set to true, the customer will be billed on a specific start date.
Default: false

day_of_week

int32

Format: Fixed length, 1 N
Description: This field represents the day of the week on which the system will bill for weekly or biweekly plans.

1 - Sunday
2 - Monday
3 - Tuesday
4 - Wednesday
5 - Thursday
6 - Friday
7 - Saturday

Conditional Requirement: Applicable only when bill_specific_day is set to true (i.e., billing is on a specific day).

day_of_month

int32

Format: Variable length, up to 2 N
Description: Day of the month on which the system will bill for monthly or annual plans. Use 1-31 to specify the day of month when the customer will be billed. Use 32 if billing should be on the last day of month.
Conditional Requirement: Applicable only when bill_specific_day is set to true (i.e., billing is on a specific day).

month

int32

Format: Variable length, up to 2 N
Description: Month in which the system will bill for monthly or annual plans. Use one of the following codes:

1 - January
2 - February
3 - March
4 - April
5 - May
6 - June
7 - July
8 - August
9 - September
10 - October
11 - November
12 - December

Conditional Requirement: Applicable only when bill_specific_day is set to true (i.e., when billing on a specific day).

prorate_first_pmt

boolean

Description: Set to true if the first payment should be prorated.
Conditional Requirement: Applicable only when bill_specific_day flag is set to true (i.e., when billing is on a specific day).

amt_prorate

double

Format: Variable length, up to 12,2 N
Description: The fixed prorated amount for the first payment. If set to 0 or undefined, the system will calculate the prorated amount based on the number of days remaining in the first cycle.
Conditional Requirement: This field is applicable only if prorate_first_pmt is set to true.

dba_suffix

string

Format: Fixed length, 9 AN
Description: For use by merchants using negative-option marketing. This field will be used in the first transaction at the conclusion of the free or reduced trial. This suffix will be appended to the end of your DBA, and the result will appear on the cardholder statement. (If your DBA and suffix contain more that 25 characters, your DBA will be truncated.) Possible values:

END DSCNT
END OFFER
END PROMO
END TRIAL

merchant_id

int64

Format: Variable length, up to 16 AN
Description: Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.
Conditional Requirement: Required if this request is on behalf of another merchant.

Responses

200Success

400Request Validation Failed

500Internal Error