1. Developer Docs
2. Products
3. Plans
   1. Plan Modifications
4. Subscriptions
   1. Lifecycle
   2. How does XPay collect recurring payments?
   3. How do I create a subscription now and later start the billing cycle?
   4. Payment methods
   5. Skip and unskip
   6. Pause
   7. Resume
   8. Cancel
   9. Update a Subscription’s Schedule / Payment
      1. Modifying individual invoice
   10. Failure use-cases
       1. Retries
       2. Subscription Status
       3. How do I collect a failed recurring payment?
          1. Payment Link
          2. In-app experience
5. Invoices
6. Webhooks

E2E Integration Example

API Docs

Developer Docs

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 fields
   1. product name
   2. price
      1. The price of the products will be summed to calculate the total amount of a plan and used to create subscriptions against that plan.
      2. The pricing can be changed at the plan level and is discussed in detail here.
3. The id field referring to SKU is an optional field, but if provided, it will be considered unique for a merchant and can't be added to another product object.
4. The products will be shown in the invoice sent to the customer via XPay.

Product Price Update

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

   1. The Update Subscription API will need to be called to update the price of each product for a subscription.

   {
   	"payment": {
   		"latest_product_price": true
   	},
   	"product": [
       {
           "name": "Ali",
           "product_id": "xpay_product_90e8c92b774641adad16325722fe8c20",
           "quantity": 1
       },
       {
           "name": " Raza",
           "product_id": "xpay_product_e302a0a0ec984e18aadd09e296323c8c",
           "quantity": 1
       }
     ],
   }
   

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.

Interval

Update the plan

1. If the plan updates, the existing subscriptions won’t be updated by default.
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"
}

If plan_id is added, it will update the latest billing cycle, products, and payment from the plan ID and override any such value being added in the payload.

<aside> 💡 To update a subscription's pricing, billing cycle, etc., kindly refer to Update a Subscription’s Schedule / Payment.

</aside>

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.

<aside> ⚠️ The subscription is not created at the customer level but at the plan level. If different plans are offered to different customers, then merchants will save those plans in their system.

</aside>

Lifecycle

How does XPay collect recurring payments?

For every recurring payment, XPay will create an invoice.

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.
   1. The subscription status will be inactive if the first two invoices are paid but the third one fails.
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 at a later date.
3. or any other case 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 and collect_advance: false to be set. XPay will create a subscription and start collecting recurring payments as per the schedule.

Payment methods

1. The payment method token needs to be provided before creating a subscription.