Add a Subscription

post

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

Creates a new subscription with a specific start date, subscribing a customer to a recurring plan or a one-off off-plan. Returns a unique subscription_id, which you can use to interact with this subscription through the API.

When the subscription includes a one-time fee, a Payment Gateway sale request is made immediately to bill the customer the one-time fee. The subscription remains active even if the request for the one-time fee fails.

Create an off-plan subscription by excluding plan_code from the request and sending the applicable fields.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Subscription Request

date_start

string

required

Format: Fixed length, 10, YYYY-MM-DD format
Description: Date the subscription will start.

customer_id

string

Format: Variable length, up to 32 AN
Description: Customer ID of the subscriber. Customer ID must be for a valid customer profile stored in Customer Vault. A customer profile can also be created while adding a subscription by using the customer field.
Conditional Requirement: Either customer_id or customer is required.

customer

object

card_id

string

Format: Fixed length, 32 AN
Description: By default, when a subscription is added to a customer, the recurring charges will be billed to the customer's primary payment method. This can be overridden to charge against any of the customer's payment methods by sending any card_id belonging to the customer in this field.

plan_code

string

Format: Variable length, up to 16 AN
Description: Plan code of the recurring plan. Plan should be an active and valid recurring plan.
Conditional Requirement: Required for on-plan subscriptions.

plan_desc

string

Format: Variable length, AN
Description: A short description of the one-off plan. Applicable only to one-off, off-plan subscriptions.

plan_frequency

int32

Format: Fixed length, 1 N
Description: This field identifies the frequency of billing. Applicable only to one-off subscriptions. Use one of the following codes for frequency:

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

Conditional Requirement: Required for one-off subscriptions.

interval

int32

Format: Variable length, up to 2 N
Description: Number of months or weeks in a monthly or weekly subscription cycle, respectively. Applicable only for monthly or weekly plan_frequency.

plan_duration

int32

Format: Variable length, up to 4 N
Description: Number of billing cycles in the recurring subscription. Use -1 if billing cycles are indefinite. Applicable only to one-off subscriptions.
Conditional Requirement: Required for one-off subscriptions.

amt_setup

double

Format: Variable length, up to 12,2 N
Description: One-time fee amount. This fee will be charged immediately when a subscription is added. Applicable only to one-off subscriptions.

amt_setup_ignore

boolean

Description: By default, if a recurring plan has a one-time fee, the customer is charged the one-time fee when the subscription is created. If amt_setup_ignore is set to true, the system does not charge the one-time fee.
Default: false

cancel_on_setup_fail

boolean

Description: If the subscription requires a one-time fee, setting cancel_on_setup_fail to true causes the system to cancel the subscription if the one-time fee cannot be charged successfully.
Default: false

amt_tran

double

Format: Variable length, up to 12,2 N
Description: Plan transaction amount, which is the amount that will be billed each cycle period. Applicable only to one-off subscriptions.
Conditional Requirement: Required for one-off subscription.

profile_id

string

Format: Fixed length, 20 N
Description: Payment Gateway profile ID that will be used when billing transactions. 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. Applicable only to one-off subscriptions.

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. Applicable only to one-off subscriptions.
Default: 840

use_existing_customer

boolean

Description: When set to true, the system will try to use an existing customer_id if one is available. If there is an existing customer with the same customer_first_name and customer_last_name and primary card_number or card_id, then the subscription is added to the matching customer. If a customer is not found, a new customer is generated. The generated customer_id will be returned in the response.
Default: false
Conditional Requirement: If set to true, the customer object is required.

pct_tran_fee

double

Format: Percentage of transaction that will be added as a transaction fee. Transaction fees can be used only if merchant is enabled to use them and if the selected payment supports this particular fee.

pct_fee

double

Format: Variable length, up to 3,2 N
Description: Percentage of the transaction that will be added as a surcharge. A surcharge is a fee added to the cost of a purchase for the privilege of using a credit card instead of another form of payment. Surcharge can be used only if the merchant is enabled to use surcharges and if the selected payment supports a surcharge.

purchase_id

string

Format: Variable length, up to 25 AN
Description: Purchase identifier (also referred to as the invoice number generated by the merchant) included in the recurring transactions. If not provided, the system generates a purchase identifier based on customer data. Applicable only to one-off subscriptions.

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.

custom_fields

array of objects

Custom fields for the subscription.

custom_fields

Responses

200Success

400Request Validation Failed

500Internal Error