API Reference
Login to SandboxCreate Account

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.

Body Params

Subscription Request

string
required

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

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
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.

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.

string

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

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.

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.

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.

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.

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

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

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.

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.

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

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.

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.

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.

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.

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

Updated 6 months ago

Language
Credentials
Basic
base64
:
URL
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 6 months ago