POST
/
payments
/
create-intent
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": 9123456789,
    "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"
  ],
  "customerReferenceId": "customer123",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  },
  "storeFrontId": "sf_sK8d3Jq1tZxPjYVhRQW2rf"
}'
{
  "amount": 100,
  "currency": "USD",
  "presentmentCurrency": "USD",
  "receiptId": "order123",
  "mode": "TEST",
  "customerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "contactNumber": "9123456789",
    "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": "66f53a6e2097773e4f0112c8",
  "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

Example:
["CARD", "GOOGLE_PAY", "APPLE_PAY"]
customerReferenceId
string

The customerReferenceId is used to enable the saved payment method feature. When a new, unique customerReferenceId is provided, a new customer profile is created. To retrieve and display a customer's previously saved payment methods, use the same customerReferenceId in subsequent transactions.

⚠️Warning : Ensure the customerReferenceId is unique for each customer. Using a duplicate ID may result in payment methods being unintentionally shared across different customers, compromising security and privacy

Example:

"customer123"

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

Response

200
application/json
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"

mode
string

The mode in which the transaction was made (e.g., TEST or LIVE)

Example:

"TEST"

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

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:

"66f53a6e2097773e4f0112c8"

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