API
  1. API Reference
API
  • Guides
    • Welcome
    • Interface
  • API Reference
    • Introduction
    • Endpoints
    • Data Types
    • Signing
    • 3-D Secure Verification
    • Subscription
    • Errors
    • Webhooks
    • Items Information
    • Changelog
    • Acquiring
      • Create a direct payment
        POST
      • Create a redirect (iFrame) payment
        POST
      • Query a transaction
        POST
      • Optimise payment methods
        POST
      • Search a refund transaction
        POST
      • Refund a transaction
        POST
      • Update an order
        POST
      • Review a transaction
        POST
      • Cancel a transaction
        POST
      • Capture a transaction
        POST
      • Create a payout
        POST
    • Issuing
      • Cardholder
        • Create cardholder
          POST
        • Delete cardholder
          POST
        • Query cardholder
          POST
      • Group
        • Create group
        • Query group details
        • Cancel group
        • Refund group
        • Update group status
        • Recharge group
      • Card
        • Create a card
        • Query card BIN
        • Recharge card
        • Withdraw from a card
        • Cancel a card
        • Update card status
        • Update card limit
        • Query card details
  • Appendix
    • Test Cards
    • Bank Code
    • Country Code
    • Currency Code
    • Payment Methods
  1. API Reference

Subscription

Subscriptions allow you to charge a customer on a recurring basis.

How subscriptions work#

Manage recurring payments and subscription lifecycles.
With Subscriptions, customers make recurring payments for access to a product. Subscriptions require you to retain more information about your customers than one-time purchases because you need to charge them in the future.

Integration example#

Landing page#

On your frontend, the landing page collects the email address first. Your application might have other customer-specific information you want to collect like a username or address. Clicking the signup button sends the information collected on the landing page to your backend. This process creates a customer and displays the pricing page on your frontend.

Pricing page#

The pricing page displays your subscription options based on the products and prices you create when you first set up your integration, meaning you don't need to create new ones every time customers sign up. Your pricing page displays the prices you created, and your customers choose the option they want.

Payment#

The payment form collects a name and card information. Our hosts this form if you use Checkout. It's one of the key features that allows you to collect payments and remain PCI compliant. Clicking Subscribe:
1.
Creates a new subscription with your customer.
2.
Collects payment details for your initial subscription cycle.
3.
Sets the payment method as the default payment method for the subscription-a requirement for subsequent payments.

Direct Payment Flow#

image.png

Redirect Payment Flow#

image.png

Subscription Object#

Subscription Request
subscription
object 
optional
A container for the type of a subscription contract
contract
string 
required
The type of recurring contract to be used. Possible values:
RECURRING – Payment details can be used without the card security code to initiate card-not-present transactions.
INSTALMENT – for instalment payment plans
contract_name
string 
required
A descriptive name for this contract.
contract_amount
string 
required
Subscription standard price, if there is no disoount program (without any promotional in which this will be the amount ol the subscription transsction)
interval
string 
required
Specifies billing frequency. Either day, week, month or year.
Allowed values:
day
week
month
year
interval_count
string 
required
The number of intervals between contract billings. For example, interval=month and interval_count=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
billing_cycle
integer 
required
The total number of billing cycles of the subscription.
For example, the subscription will last for 1 year if billing_cycles=12, interval_count=1 and interval=MONTH.
The subscription will continue indefinitely if billing_cycles is 0.
promotion_cycle
integer 
optional
The rumber of discount periods must be provided for the promotional program. It will be associsied wth interval, e.g, promotion cycle=3, interval=month means the dscount perod is 3 months
contract_start
string 
required
(if specified) Start of the current period that the subscription has been invoiced for. The format "YYYY-MM-DD". For example, "2024-12-03" .
contract_end
string 
required
(if specified) End of the current period that the subscription has been invoiced for. The format "YYYY-MM-DD". For example, "2024-12-03" .
price_id
string 
optional
The price_id will be used to enable the created subscription plan.
Subscription Response
contract_name
string 
optional
A descriptive name for this contract.
recurring_id
string 
optional
The recurring lD is a unique identifier assigned to each subscription.
recurring_deduction_period
string 
optional
The deduction period refers to which installment or billing cycle the current deductionfalls under for the subscription.
recurring_deduction_time
string 
optional
The deduction time refers to the specific date and time when the payment for thesubscription is processed, The format "YYYY-MMM-DD HH:MM:SS". For example.2024-12-03 14:30.45”.
recurring_status
string 
optional
The status describes the recurring'deduction status to this notification.
0：Creation failed
-1：Pending
1：Creation successful
2：Deduction failed
3：Deduction successful
4：Final deduction failed
encryption_data
string 
optional
Digital signatures information
encryption_data=sha256(merchant_id + account_id +order_no + currency +amount + first_name + last_name + card + expiration_year + expiration_month+ security_code + shopper_email + sign_key);
All encryption parameters need to remove spaces before encryption.

Billing Logic for Promotional Plans#

1.
Billing During the Promotional Period --- Before contract_start + promotion_cycle * interval, e.g., contract_start +3 months:
Create a subscription based on the amount (promotional price) and charge this amount.
During each billing cycle, verify whether the current time falls within the promotional period.
2.
Billing During the Standard Period --- After contract_start + promotion_cycle * interval, e.g., contract_start +3 months:
Update the subscription to the contract_amount (standard price) and charge this amount for each subsequent billing cycle until the contract_end.
Alternatively, generate a new subscription using the current subscription token with the contract_amount (standard price), setting the subscription end date to contract_end.

Illustration example#

image.png
Previous
3-D Secure Verification
Next
Errors