cURL
curl --request POST \
--url https://api.xpaycheckout.com/subscription/create \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 100,
"currency": "USD",
"customerDetails": {
"name": "John Doe",
"email": "john.doe@example.com",
"contactNumber": "+919123456789",
"customerAddress": {
"addressLine1": "123 Main St",
"addressLine2": "Apt 1",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "2424"
}
},
"callbackUrl": "https://example.com/callback",
"interval": "MONTH",
"intervalCount": 2,
"cycleCount": 2,
"receiptId": "order123",
"cancelUrl": "https://example.com/cancel",
"upfrontAmount": 200,
"trialPeriodCount": 7,
"trialPeriodInterval": "DAY",
"metadata": {
"orderId": "12345",
"customerNote": "Deliver after 5 PM"
},
"phoneNumberRequired": false,
"customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
}
'import requests
url = "https://api.xpaycheckout.com/subscription/create"
payload = {
"amount": 100,
"currency": "USD",
"customerDetails": {
"name": "John Doe",
"email": "john.doe@example.com",
"contactNumber": "+919123456789",
"customerAddress": {
"addressLine1": "123 Main St",
"addressLine2": "Apt 1",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "2424"
}
},
"callbackUrl": "https://example.com/callback",
"interval": "MONTH",
"intervalCount": 2,
"cycleCount": 2,
"receiptId": "order123",
"cancelUrl": "https://example.com/cancel",
"upfrontAmount": 200,
"trialPeriodCount": 7,
"trialPeriodInterval": "DAY",
"metadata": {
"orderId": "12345",
"customerNote": "Deliver after 5 PM"
},
"phoneNumberRequired": False,
"customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 100,
currency: 'USD',
customerDetails: {
name: 'John Doe',
email: 'john.doe@example.com',
contactNumber: '+919123456789',
customerAddress: {
addressLine1: '123 Main St',
addressLine2: 'Apt 1',
city: 'New York',
state: 'NY',
country: 'US',
postalCode: '2424'
}
},
callbackUrl: 'https://example.com/callback',
interval: 'MONTH',
intervalCount: 2,
cycleCount: 2,
receiptId: 'order123',
cancelUrl: 'https://example.com/cancel',
upfrontAmount: 200,
trialPeriodCount: 7,
trialPeriodInterval: 'DAY',
metadata: {orderId: '12345', customerNote: 'Deliver after 5 PM'},
phoneNumberRequired: false,
customerId: 'cus_Tfd3Jq1tZxPjYVhRQW2r3'
})
};
fetch('https://api.xpaycheckout.com/subscription/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.xpaycheckout.com/subscription/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 100,
'currency' => 'USD',
'customerDetails' => [
'name' => 'John Doe',
'email' => 'john.doe@example.com',
'contactNumber' => '+919123456789',
'customerAddress' => [
'addressLine1' => '123 Main St',
'addressLine2' => 'Apt 1',
'city' => 'New York',
'state' => 'NY',
'country' => 'US',
'postalCode' => '2424'
]
],
'callbackUrl' => 'https://example.com/callback',
'interval' => 'MONTH',
'intervalCount' => 2,
'cycleCount' => 2,
'receiptId' => 'order123',
'cancelUrl' => 'https://example.com/cancel',
'upfrontAmount' => 200,
'trialPeriodCount' => 7,
'trialPeriodInterval' => 'DAY',
'metadata' => [
'orderId' => '12345',
'customerNote' => 'Deliver after 5 PM'
],
'phoneNumberRequired' => false,
'customerId' => 'cus_Tfd3Jq1tZxPjYVhRQW2r3'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.xpaycheckout.com/subscription/create"
payload := strings.NewReader("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"customerDetails\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"contactNumber\": \"+919123456789\",\n \"customerAddress\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 1\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"postalCode\": \"2424\"\n }\n },\n \"callbackUrl\": \"https://example.com/callback\",\n \"interval\": \"MONTH\",\n \"intervalCount\": 2,\n \"cycleCount\": 2,\n \"receiptId\": \"order123\",\n \"cancelUrl\": \"https://example.com/cancel\",\n \"upfrontAmount\": 200,\n \"trialPeriodCount\": 7,\n \"trialPeriodInterval\": \"DAY\",\n \"metadata\": {\n \"orderId\": \"12345\",\n \"customerNote\": \"Deliver after 5 PM\"\n },\n \"phoneNumberRequired\": false,\n \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.xpaycheckout.com/subscription/create")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"customerDetails\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"contactNumber\": \"+919123456789\",\n \"customerAddress\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 1\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"postalCode\": \"2424\"\n }\n },\n \"callbackUrl\": \"https://example.com/callback\",\n \"interval\": \"MONTH\",\n \"intervalCount\": 2,\n \"cycleCount\": 2,\n \"receiptId\": \"order123\",\n \"cancelUrl\": \"https://example.com/cancel\",\n \"upfrontAmount\": 200,\n \"trialPeriodCount\": 7,\n \"trialPeriodInterval\": \"DAY\",\n \"metadata\": {\n \"orderId\": \"12345\",\n \"customerNote\": \"Deliver after 5 PM\"\n },\n \"phoneNumberRequired\": false,\n \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.xpaycheckout.com/subscription/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"customerDetails\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"contactNumber\": \"+919123456789\",\n \"customerAddress\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 1\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"postalCode\": \"2424\"\n }\n },\n \"callbackUrl\": \"https://example.com/callback\",\n \"interval\": \"MONTH\",\n \"intervalCount\": 2,\n \"cycleCount\": 2,\n \"receiptId\": \"order123\",\n \"cancelUrl\": \"https://example.com/cancel\",\n \"upfrontAmount\": 200,\n \"trialPeriodCount\": 7,\n \"trialPeriodInterval\": \"DAY\",\n \"metadata\": {\n \"orderId\": \"12345\",\n \"customerNote\": \"Deliver after 5 PM\"\n },\n \"phoneNumberRequired\": false,\n \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\"\n}"
response = http.request(request)
puts response.read_body{
"subscriptionId": "sub_fooBOwYsaK50AEfK",
"createdAt": "2024-09-26T10:41:50.472+00:00",
"fwdUrl": "https://pay.xpaycheckout.com/?subscription_id=67f53a6e2097773e4f0112c8"
}{
"errorCode": "bad_request",
"errorDescription": "Failed to read request"
}Subscriptions
Create Subscription
POST
/
subscription
/
create
cURL
curl --request POST \
--url https://api.xpaycheckout.com/subscription/create \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 100,
"currency": "USD",
"customerDetails": {
"name": "John Doe",
"email": "john.doe@example.com",
"contactNumber": "+919123456789",
"customerAddress": {
"addressLine1": "123 Main St",
"addressLine2": "Apt 1",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "2424"
}
},
"callbackUrl": "https://example.com/callback",
"interval": "MONTH",
"intervalCount": 2,
"cycleCount": 2,
"receiptId": "order123",
"cancelUrl": "https://example.com/cancel",
"upfrontAmount": 200,
"trialPeriodCount": 7,
"trialPeriodInterval": "DAY",
"metadata": {
"orderId": "12345",
"customerNote": "Deliver after 5 PM"
},
"phoneNumberRequired": false,
"customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
}
'import requests
url = "https://api.xpaycheckout.com/subscription/create"
payload = {
"amount": 100,
"currency": "USD",
"customerDetails": {
"name": "John Doe",
"email": "john.doe@example.com",
"contactNumber": "+919123456789",
"customerAddress": {
"addressLine1": "123 Main St",
"addressLine2": "Apt 1",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "2424"
}
},
"callbackUrl": "https://example.com/callback",
"interval": "MONTH",
"intervalCount": 2,
"cycleCount": 2,
"receiptId": "order123",
"cancelUrl": "https://example.com/cancel",
"upfrontAmount": 200,
"trialPeriodCount": 7,
"trialPeriodInterval": "DAY",
"metadata": {
"orderId": "12345",
"customerNote": "Deliver after 5 PM"
},
"phoneNumberRequired": False,
"customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 100,
currency: 'USD',
customerDetails: {
name: 'John Doe',
email: 'john.doe@example.com',
contactNumber: '+919123456789',
customerAddress: {
addressLine1: '123 Main St',
addressLine2: 'Apt 1',
city: 'New York',
state: 'NY',
country: 'US',
postalCode: '2424'
}
},
callbackUrl: 'https://example.com/callback',
interval: 'MONTH',
intervalCount: 2,
cycleCount: 2,
receiptId: 'order123',
cancelUrl: 'https://example.com/cancel',
upfrontAmount: 200,
trialPeriodCount: 7,
trialPeriodInterval: 'DAY',
metadata: {orderId: '12345', customerNote: 'Deliver after 5 PM'},
phoneNumberRequired: false,
customerId: 'cus_Tfd3Jq1tZxPjYVhRQW2r3'
})
};
fetch('https://api.xpaycheckout.com/subscription/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.xpaycheckout.com/subscription/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 100,
'currency' => 'USD',
'customerDetails' => [
'name' => 'John Doe',
'email' => 'john.doe@example.com',
'contactNumber' => '+919123456789',
'customerAddress' => [
'addressLine1' => '123 Main St',
'addressLine2' => 'Apt 1',
'city' => 'New York',
'state' => 'NY',
'country' => 'US',
'postalCode' => '2424'
]
],
'callbackUrl' => 'https://example.com/callback',
'interval' => 'MONTH',
'intervalCount' => 2,
'cycleCount' => 2,
'receiptId' => 'order123',
'cancelUrl' => 'https://example.com/cancel',
'upfrontAmount' => 200,
'trialPeriodCount' => 7,
'trialPeriodInterval' => 'DAY',
'metadata' => [
'orderId' => '12345',
'customerNote' => 'Deliver after 5 PM'
],
'phoneNumberRequired' => false,
'customerId' => 'cus_Tfd3Jq1tZxPjYVhRQW2r3'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.xpaycheckout.com/subscription/create"
payload := strings.NewReader("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"customerDetails\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"contactNumber\": \"+919123456789\",\n \"customerAddress\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 1\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"postalCode\": \"2424\"\n }\n },\n \"callbackUrl\": \"https://example.com/callback\",\n \"interval\": \"MONTH\",\n \"intervalCount\": 2,\n \"cycleCount\": 2,\n \"receiptId\": \"order123\",\n \"cancelUrl\": \"https://example.com/cancel\",\n \"upfrontAmount\": 200,\n \"trialPeriodCount\": 7,\n \"trialPeriodInterval\": \"DAY\",\n \"metadata\": {\n \"orderId\": \"12345\",\n \"customerNote\": \"Deliver after 5 PM\"\n },\n \"phoneNumberRequired\": false,\n \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.xpaycheckout.com/subscription/create")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"customerDetails\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"contactNumber\": \"+919123456789\",\n \"customerAddress\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 1\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"postalCode\": \"2424\"\n }\n },\n \"callbackUrl\": \"https://example.com/callback\",\n \"interval\": \"MONTH\",\n \"intervalCount\": 2,\n \"cycleCount\": 2,\n \"receiptId\": \"order123\",\n \"cancelUrl\": \"https://example.com/cancel\",\n \"upfrontAmount\": 200,\n \"trialPeriodCount\": 7,\n \"trialPeriodInterval\": \"DAY\",\n \"metadata\": {\n \"orderId\": \"12345\",\n \"customerNote\": \"Deliver after 5 PM\"\n },\n \"phoneNumberRequired\": false,\n \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.xpaycheckout.com/subscription/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"customerDetails\": {\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"contactNumber\": \"+919123456789\",\n \"customerAddress\": {\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 1\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"country\": \"US\",\n \"postalCode\": \"2424\"\n }\n },\n \"callbackUrl\": \"https://example.com/callback\",\n \"interval\": \"MONTH\",\n \"intervalCount\": 2,\n \"cycleCount\": 2,\n \"receiptId\": \"order123\",\n \"cancelUrl\": \"https://example.com/cancel\",\n \"upfrontAmount\": 200,\n \"trialPeriodCount\": 7,\n \"trialPeriodInterval\": \"DAY\",\n \"metadata\": {\n \"orderId\": \"12345\",\n \"customerNote\": \"Deliver after 5 PM\"\n },\n \"phoneNumberRequired\": false,\n \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\"\n}"
response = http.request(request)
puts response.read_body{
"subscriptionId": "sub_fooBOwYsaK50AEfK",
"createdAt": "2024-09-26T10:41:50.472+00:00",
"fwdUrl": "https://pay.xpaycheckout.com/?subscription_id=67f53a6e2097773e4f0112c8"
}{
"errorCode": "bad_request",
"errorDescription": "Failed to read request"
}Authorizations
Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.
Headers
A unique key for making the request idempotent. Must match pattern: ^[a-zA-Z0-9\-_:\.]+$. See Idempotent Requests for more details.
Maximum string length:
255Pattern:
^[a-zA-Z0-9\-_:\.]+$Body
application/json
Create Subscription
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
Three letter abbreviation of the currency. Refer supported currencies
Example:
"USD"
Billing details for the customer.
Show child attributes
Show child attributes
The URL we will callback to with the order status once it finishes.
Example:
"https://example.com/callback"
The interval group between subscriptions.
Available options:
DAY, WEEK, MONTH, YEAR Example:
"MONTH"
The number of intervals between subscription billings. For example, interval = MONTH and intervalCount = 3 bills every 3 months.
Example:
2
The number of billing cycles for which the subscription will renew before ending. The first cycle is included in this count.
Example:
2
Your identifier of the order
Example:
"order123"
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"
An optional amount that merchants can set to be charged to the customer at the time the subscription is activated. This amount replaces the first billing cycle charge — the regular subscription amount is not added on top of it. Regular billing resumes from the next cycle.
The amount is in the lowest count unit. e.g.: For USD 1, amount is 100 representing 100 cents (minimum amount should be greater than 1 USD).
Validation Rules:
- Not compatible with
trialPeriodCountandtrialPeriodInterval— cannot be provided simultaneously
Required range:
x >= 1Example:
200
The number of trial periods before the first billing cycle. Must be greater than or equal to 0 if provided.
Validation Rules:
- If
trialPeriodCountis provided,trialPeriodIntervalmust also be provided trialPeriodCountis not compatible withupfrontAmount- both cannot be provided simultaneously
Required range:
x >= 0Example:
7
The interval for the trial period.
Validation Rules:
- Required when
trialPeriodCountis provided
Available options:
DAY, WEEK, MONTH, YEAR Example:
"DAY"
A collection of key-value pairs that can be attached to an object for storing additional structured information. This is useful for capturing custom data or context-specific attributes.
Constraints:
- Maximum of 50 key-value pairs allowed.
- Each key must be no longer than 40 characters.
- Each value must be a string and cannot exceed 500 characters.
Show child attributes
Show child attributes
Example:
{
"orderId": "12345",
"customerNote": "Deliver after 5 PM"
}
Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.
Example:
false
The unique identifier for the customer, generated via the create-customer API. This can be used to associate the payment with a specific customer in your system.
Example:
"cus_Tfd3Jq1tZxPjYVhRQW2r3"
Product Page - showcases more about the product on the checkout page
Show child attributes
Show child attributes
Response
Create Subscription response
Unique identifier of the subscription
Example:
"sub_fooBOwYsaK50AEfK"
Timestamp of when the subscription was created
Example:
"2024-09-26T10:41:50.472+00:00"
The URL to redirect the customer to the xPay payment gateway for payment.
Example:
"https://pay.xpaycheckout.com/?subscription_id=67f53a6e2097773e4f0112c8"
Was this page helpful?