Skip to main content
POST
/
payments
/
create-intent
cURL
curl --request POST \
  --url https://api.xpaycheckout.com/payments/create-intent \
  --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",
  "callbackUrl": "https://example.com/callback",
  "cancelUrl": "https://example.com/cancel",
  "paymentMethods": [
    "CARD",
    "GOOGLE_PAY",
    "APPLE_PAY"
  ],
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  },
  "phoneNumberRequired": false,
  "customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3",
  "storeFrontId": "sf_sK8d3Jq1tZxPjYVhRQW2rf",
  "tokenise": false
}'
{
  "amount": 100,
  "currency": "USD",
  "presentmentCurrency": "USD",
  "receiptId": "order123",
  "customerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "contactNumber": "+919123456789",
    "customerAddress": {
      "country": "US",
      "postalCode": "2424"
    }
  },
  "description": "Order for 2 items",
  "callbackUrl": "https://example.com/callback",
  "cancelUrl": "https://example.com/cancel",
  "createdAt": "2024-09-26T10:41:50.472+00:00",
  "status": "CREATED",
  "xIntentId": "in_fooBOwYsaK50AEfK",
  "fwdUrl": "https://pay.xpaycheckout.com/?xpay_intent_id=67f53a6e2097773e4f0112c8",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}

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

Create Intent

ā€‹
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

ā€‹
callbackUrl
string
required

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

Example:

"https://example.com/callback"

ā€‹
receiptId
string

Your identifier of the order

Example:

"order123"

ā€‹
description
string

The description of the order, if any

Example:

"Order for 2 items"

ā€‹
cancelUrl
string

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

Example:

"https://example.com/cancel"

ā€‹
paymentMethods
string[]

List of payment methods to be enabled for the link. supported payment methods

šŸ’” If a selected payment method is unavailable, the system will automatically fallback to card payments to ensure a smooth checkout experience.

Example:
["CARD", "GOOGLE_PAY", "APPLE_PAY"]
ā€‹
metadata
object

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.
Example:
{
  "orderId": "12345",
  "customerNote": "Deliver after 5 PM"
}
ā€‹
phoneNumberRequired
boolean

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

Example:

false

ā€‹
customerId
string

Your unique identifier for the customer. This can be used to associate the payment with a specific customer in your system.

Example:

"cus_Tfd3Jq1tZxPjYVhRQW2r3"

ā€‹
storeFrontId
string

šŸ”µ Beta Feature - The unique identifier for your storefront. This ID is used to associate the payment with a specific storefront in your account. When provided, it will replace the default DBA and logo with the corresponding storefront's branding. This feature is currently in beta testing and may be subject to changes.

To enable this feature, please contact hello@xpaycheckout.com

Example:

"sf_sK8d3Jq1tZxPjYVhRQW2rf"

ā€‹
tokenise
boolean

This boolean tokenises and stores the card to showcase the same card in future. If sending this value, corresponding customerId is also required. You will receive payment_method_token.created webhook every time a new payment method token is created.

Example:

false

Response

Create Intent response

ā€‹
amount
integer

The amount in lowest count unit (e.g., cents for USD)

Example:

100

ā€‹
currency
string

Three-letter currency code

Example:

"USD"

ā€‹
presentmentCurrency
string

The currency that the customer paid in

Example:

"USD"

ā€‹
receiptId
string

Your identifier for the order

Example:

"order123"

ā€‹
customerDetails
object
ā€‹
description
string

Description of the order, if any

Example:

"Order for 2 items"

ā€‹
callbackUrl
string

Callback URL to notify order status

Example:

"https://example.com/callback"

ā€‹
cancelUrl
string

The URL to redirect the customer to when they cancel the payment.

Example:

"https://example.com/cancel"

ā€‹
createdAt
string<date-time>

Timestamp of when the intent was created

Example:

"2024-09-26T10:41:50.472+00:00"

ā€‹
status
string

Current status of the intent.

Example:

"CREATED"

ā€‹
xIntentId
string

Unique identifier of the intent

Example:

"in_fooBOwYsaK50AEfK"

ā€‹
fwdUrl
string

The URL to redirect the customer to the xPay payment gateway for payment.

Example:

"https://pay.xpaycheckout.com/?xpay_intent_id=67f53a6e2097773e4f0112c8"

ā€‹
metadata
object

A collection of key-value pairs that were provided when the object was created. These metadata values are echoed back in the response, allowing you to store and retrieve custom information such as context-specific attributes, references, or tags. This can be useful for correlating records in your system or attaching meaningful context to transactions.

Example:
{
  "orderId": "12345",
  "customerNote": "Deliver after 5 PM"
}
āŒ˜I