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

Usage-based Billing

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, which is discussed in detail here.
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.

   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.
5. Plans also support a billing_cycle_anchor_config, which lets you specify the exact point when the billing cycle should start.
   • If interval is month, pass { day_of_month: <1–31> }
   • If interval is week, pass { day_of_week: <0–6> } (0 = Sunday, 6 = Saturday)
   • If interval is year, pass { month: <1–12>, day_of_month: <1–31> }

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"
}

<aside> ⚠️

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

<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 but at the plan level. If different plans are offered to multiple customers, then merchants will save those plans in their system.

</aside>

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.
   1. The subscription status will be inactive if the first two invoices are paid but the third 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 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.

Usage-based Billing