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:

Creates a new subscription with your customer.

Collects payment details for your initial subscription cycle.

Sets the payment method as the default payment method for the subscription-a requirement for subsequent payments.

Direct Payment Flow

Redirect Payment Flow

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

<= 20 characters

contract_name

string

required

A descriptive name for this contract.

<= 200 characters

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)

<= 15 characters

interval

string

optional

Specifies billing frequency. Either day, week, month or year.
Allowed values:
day
week
month

<= 20 characters

interval_count

string

optional

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

optional

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 cydes=3, interval=month means the dscount perod is 3 months

contract_start

string

optional

(if specified) Start of the current period that the subscription has been invoiced for. The format "YYYY-MM-DD HH:MM:SS". For example, "2024-12-03 14:30:45" .

<= 20 characters

contract_end

string

optional

(if specified) End of the current period that the subscription has been invoiced for. The format "YYYY-MM-DD HH:MM:SS". For example, "2024-12-03 14:30:45" .

<= 20 characters

price_id

string

optional

The price_id will be used to enable the created subscription plan.

<= 50 characters

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.

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

Billing During the Promotional Period --- Before contract_start + promotion_cycles * 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.

Billing During the Standard Period --- After contract_start + promotion_cycles * 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.

How subscriptions work#

Integration example#

Landing page#

Pricing page#

Payment#

Direct Payment Flow#

Redirect Payment Flow#

Subscription Object#

Billing Logic for Promotional Plans#

Illustration example#

How subscriptions work

Integration example

Landing page

Pricing page

Payment

Direct Payment Flow

Redirect Payment Flow

Subscription Object

Billing Logic for Promotional Plans

Illustration example