A subscription comprises three parts:

1. Products
2. Plans
3. Subscription

Products#

1. A product needs to be created, against which a plan will be created and later subscribed.
2. To start with, you will need to add these two required fieldsLoading…
3. The id key referring to SKU is optional, but if provided, it will be considered unique for a merchant and can't be added to another product object.

Product Price Update#

1. In the case of updating product prices, the plans and subscriptions associated with the products won't be updated automatically.Loading…

Plans#

A plan is a schedule defining how merchants intend to collect recurring payments.

1. In plans, the merchant will specify interval, every, etc.
2. When a user selects a plan and pays, a subscription is created against that plan.
3. A subscription is always created against a plan, and later recurring payments are collected as per that plan.
4. The Plans API supports adding single or multiple products to one plan.
5. Plans also support a billing_cycle_anchor_config, which lets you specify the exact point when the billing cycle should start.Loading…
6. The Plans API now supports usage-based charging, the merchant will specify is_usage_based: boolean and pricing_models: string[] if wants to create a usage-based plan.
7. Plans also support total_count: Loading…

Interval#

Update the plan#

1. The existing subscriptions won’t be updated by default if the plan updates.
2. To update subscriptions, the merchant needs to use the Update Subscription API with Plan ID to update individual subscriptions.

{
	"plan_id": "xpay_plan_6f51cae83bbb45bd8588fe0c95e4c2b6"
}

Plan pricing#

By default, the price of each product will add up to the plan price. However, XPay supports manually adding amounts and currencies if pricing needs to be changed based on frequency, etc. In this case, the Create Plan API expects the amount: number, and currency: string to be passed.

Subscriptions#

1. A subscription will be created against a plan, and the billing cycle will start from the start date.
2. The start_date, plan_id, timezone, and payment_token need to be mentioned.
3. If a billing_anchor is provided during plan creation, the start_date parameter will be ignored.

Lifecycle#

How does XPay collect recurring payments?#

XPay will create an invoice for every recurring payment.

1. This invoice will have an ID, an associate payment intent ID, a payment date, etc.
2. The latest invoice status will be the subscription status at any given time.Loading…
3. The payment against the invoice will be attempted as per the start_date and plan provided.

How do I create a subscription now and later start the billing cycle?#

This is the use case where

1. A free trial is being offered.
2. The user wants to checkout now and start a subscription later.
3. Requiring authentication and authorization from the cardholder without starting a subscription.

The merchant can do this if the Payment Method token doesn’t exist.

1. Create a PI of the minimum amount allowed by the acquirer.
2. confirmPayment() SDK to authenticate, authorize, and collect payment method tokens.
3. Use that PM in the Create Subscription API. XPay will create a subscription and start collecting recurring payments per the payload.

Payment methods #

1. The payment method token needs to be added in the Create Subscription API.
2. If the merchant already has a payment method, it can be provided while creating a subscription.Loading…
3. If the payment method token doesn't exist, then there are two approaches:Loading…

What happens when a payment fails with collect_advance: true on creating a new subscription?#

1. When collect_advance: true is added to the Create Subscription API, a couple of use cases are to be handled.Loading…

Skip and unskip#

1. The subscription invoice for a specific interval can be skipped, and no amount will be charged for that invoice.Loading…
2. Only scheduled invoices can be skipped.
3. The subscription can be unskipped before the invoice's payment date.

Pause#

1. The subscription can be paused, and no further payments will be attempted.
2. By default, the pause is not allowed on an inactive subscription. However, the merchant can specify in the config to allow and override the default behavior.
3. No new invoice will be created.

Resume#

1. The subscription can be resumed after it has been paused.
2. The new billing cycle will start from the date it is resumed or any start_date specified.
3. The payment attempt will be made, and after a successful attempt, the subscription will be resumed with active status.

Cancel#

1. The subscription can be canceled, and no new invoice or payment will be charged against it.
2. Its status will be cancelled.
3. Once a subscription is canceled, it can't be undone.
4. By default, cancellation is not allowed on an inactive subscription. However, the merchant can specify in the config to override the default behavior.

Update a Subscription’s Schedule / Payment#

If the merchant wants to modify the plan, payment schedule, and amount, that will be added at the individual subscription level.

1. The updated time and amount will be reflected in upcoming invoices.

Updating Price#

When you update the price during the middle of a customer's billing cycle, you need to consider proration. If you want to charge/credit price changes in the next bill, you will enable proration. If this is not added, the amount will not be charged, and changes will be applied to the next invoice.

Prorations#

Proration can be used to charge or credit a customer if there's a change in the subscription price during the billing cycle. If not enabled, any changes made to a customer’s subscription mid-cycle will go into effect at the beginning of the next cycle.

To apply proration while updating a subscription, you need to add the following payload in the Update Subscription API.

 "proration": {
        "behaviour": "invoice_now"
 }

Here, the prorated amount will be calculated and the invoice for payment and refund will be created and added to the subscription object in the updated_prorated_invoices[] array.

XPay will not automatically charge or refund an amount from the customer. Merchants can use XPay APIs or XAP to verify all the details and then refund or charge the customer.

Refund Prorated Amount#

If the already paid amount exceeds the prorated amount then a refund invoice will be created and the merchant can fetch that invoice, verify the amount and calculations done, and use the Refund Invoice API to refund the amount.

The amount will be refunded from the last subscription payment on that subscription.

Charge Prorated Amount#

Similar to the refund case, an invoice will be generated for an additional amount with all the details and the merchant can use the Pay Invoice API to charge the customer.

How are past days calculated in the prorated amount calculation?#

At the moment, XPay considers past midnight as a day passed. If a customer updates a subscription at 03:00 PM, that day will be considered as a day passed.

However, if the customer again updates on the same day, that will not be considered as a day passed.

Failure use-cases #

Retries#

1. If it's an active subscription and payment fails due to the payment_method token, then the payment will be attempted up to three times at 00:00 in the provided timezone on the next date.Loading…

Subscription Status#

1. The default subscription status after payment failure will be inactive and the invoice will be marked as failed.Loading…

How do I collect a failed recurring payment?#

Payment Link

1. A merchant can generate a payment link and send it to a customer.Loading…

In-app experience

1. If you want to collect payments on your web/mobile app, you will need to use the XPay SDK.Loading…

Invoices#

1. Invoices are individual subscription payment objects.
2. Each subscription recurring payment is charged with one invoice.
3. The subsequent payment schedule will be shared in response to the Create Subscription API and webhook.Loading…

Create an Invoice#

1. You can create an invoice against a subscription, with the optional scheduler.
2. The state of the invoice can be open, draft, and paid.
3. The amount and currency can be overridden by manually adding to the API payload.
4. The default state of the invoice is draft and scheduled_date and enable_scheduler can be added with this state only.

{
	  "subscription_id": "xpay_subs_056bad7d10674555aaef770fdaed39cf",
    "state": "draft", //optional
    "amount": "5", //optional
    "currency": "PKR", //optional
    "scheduled_date": "2024-07-19T18:09:00Z", //optional
    "enable_scheduler": true //optional
}

Update an Invoice#

1. The state of the already existing invoice can be updated as open, draft, and paid.
2. The amount and currency can be overridden by the Update Invoice API.

Pay an Invoice#

1. The Pay an Invoice will trigger payment with the token already saved against the subscription.
2. send_payment_link_on_failure can be set as a boolean.

Subscription Lifecycle#

Webhooks#

XPay will notify merchants via webhooks of all events.

An example of e2e integration#

Ali Enterprises sells chocolates in three flavors and provides subscriptions on a weekly, monthly, quarterly, and yearly basis.

So, this will be their flow.

1. First, AE will add three products to XPay.
2. Create four plans using these payloads.Loading…
3. When the user selects a plan to subscribe, the plan ID to be passed in the Create Subscription API payload.

Subscription API Timeline#

1. Create Subscription API May 24, 2024Loading…
2. Skip Subscription API May 24, 2024
3. Unskip Subscription API May 24, 2024
4. Pause Subscription API May 24, 2024
5. Resume Subscription API May 24, 2024
6. Cancel Subscription API May 24, 2024
7. Get a Subscription API

Dates for TBD will be added soon.

API Docs#