Skip to main content
POST
/
subscription
/
link
/
merchant
/
generate-link
cURL
curl --request POST \
  --url https://api.xpaycheckout.com/subscription/link/merchant/generate-link \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100,
  "currency": "USD",
  "receiptId": "order123",
  "customerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "contactNumber": "+919123456789",
    "customerAddress": {
      "country": "US",
      "postalCode": "2424"
    }
  },
  "description": "Order for 2 items",
  "expiryDate": 32526868154000,
  "callbackUrl": "https://example.com/callback",
  "cancelUrl": "https://example.com/cancel",
  "interval": "MONTH",
  "intervalCount": 2,
  "cycleCount": 2,
  "upfrontAmount": 200,
  "trialPeriodCount": 7,
  "trialPeriodInterval": "DAY",
  "multiUseLimit": 5,
  "productPage": {
    "name": "Premium Subscription",
    "description": "Access to premium features and content"
  },
  "phoneNumberRequired": false
}'
{
  "shortUrl": "https://api.xpaycheckout.com/subscription/link/pcTrro7D",
  "disclaimer": "GBP is not supported on Klarna. The payment will default to USD."
}

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

Generate Subscription Link

​
amount
integer
required

The amount in lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (The minimum amount should be greater than 1 USD)

Example:

100

​
currency
string
required

Three letter abbreviation of the currency. Refer supported currencies

Example:

"USD"

​
customerDetails
object
required

Details about the customer

​
expiryDate
integer
required

Timestamp in epoch milliseconds, indicating the expiration time of the link

Example:

32526868154000

​
interval
enum<string>
required

The interval group between subscriptions.

Available options:
DAY,
WEEK,
MONTH,
YEAR
Example:

"MONTH"

​
intervalCount
integer
required

The number of intervals between subscription billings. For example, interval = MONTH and intervalCount = 3 bills every 3 months.

Example:

2

​
cycleCount
integer
required

The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.

Example:

2

​
receiptId
string

Your identifier of the order

Example:

"order123"

​
description
string

The description of the order, if any

Example:

"Order for 2 items"

​
callbackUrl
string

The URL we will callback to with the subscriptionId once it finishes.

Example:

"https://example.com/callback"

​
cancelUrl
string

The URL to redirect the customer to when they cancel the subscription. If not provided, the callbackUrl will be used as fallback.

Example:

"https://example.com/cancel"

​
upfrontAmount
integer

The amount to be charged at the start of the subscription. The upfront amount replaces the first subscription cycle amount. Regular amount apply from the next cycle.

Note: Not compatible with trial periods - cannot be used when trialPeriodCount is provided.

Example:

200

​
trialPeriodCount
integer

The number of trial periods before the first billing cycle. Must be greater than or equal to 0 if provided.

Validation Rules:

  • If trialPeriodCount is provided, trialPeriodInterval must also be provided
  • trialPeriodCount is not compatible with upfrontAmount - both cannot be provided simultaneously
Required range: x >= 0
Example:

7

​
trialPeriodInterval
enum<string>

The interval for the trial period.

Validation Rules:

  • Required when trialPeriodCount is provided
Available options:
DAY,
WEEK,
MONTH,
YEAR
Example:

"DAY"

​
multiUseLimit
integer

The maximum number of times this subscription link can be used. If null, the link can be used only once. Must be greater than 0 if provided.

Required range: x >= 1
Example:

5

​
productPage
object

Product Page - showcases more about the product in the payment links

​
phoneNumberRequired
boolean

Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.

Example:

false

Response

Generate Subscription Link

​
shortUrl
string

The shortened URL generated by the xPay API. This link can be shared with customers for completing payments.

Example:

"https://api.xpaycheckout.com/subscription/link/pcTrro7D"

​
disclaimer
string

A message highlighting unsupported currency and payment method pairs. You may use this information to communicate these limitations to your users and set expectations.

Example:

"GBP is not supported on Klarna. The payment will default to USD."

⌘I