Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-26336777.7 KB

Create a new setup method for storing payment methods server to server

post/setup-method/s2s/create

Headers

Idempotency-Keystring

A unique key for making the request idempotent. Must match pattern: ^[a-zA-Z0-9\-_:\.]+$. See Idempotent Requests for more details.

Request body

currencystring required

Three letter abbreviation of the currency. Refer supported currencies

customerIdstring

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.

customerReferenceIdstring

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

storeFrontIdstring

The unique identifier for your storefront

callbackUrlstring required

The URL we will callback to once the setup is complete

phoneNumberRequiredboolean

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

amountinteger

The amount to charge immediately while setting up the payment method token. The amount in lowest count unit e.g.: For USD 1, amount is 100 representing 100 cents. Should be greater than 0.

receiptIdstring

Your identifier of the order. This will be persisted in the intent created while setting up the payment method token.

metadataobject

A collection of key-value pairs that can be attached to an object for storing additional structured information.

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 request

{
  "currency": "USD",
  "customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3",
  "customerReferenceId": "eTfd3Jq1tZxPjYVhRQW2r3",
  "billingDetails": {
    "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"
    }
  },
  "storeFrontId": "sf_sK8d3Jq1tZxPjYVhRQW2rf",
  "callbackUrl": "https://example.com/callback",
  "cardDetails": {
    "cardHolderName": "John Doe",
    "cardNumber": "4000002500000003",
    "expiryMonth": 1,
    "expiryYear": 28,
    "cvv": "123",
    "country": "US",
    "postalCode": "2424"
  },
  "amount": 100,
  "receiptId": "order123",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Setup for recurring payments"
  }
}

Response

Setup Method created successfully

setupMethodIdstring

Unique identifier of the setup method

fwdUrlstring

The URL to redirect the customer to complete the setup

Example response

{
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "fwdUrl": "https://pay.xpaycheckout.com/setup-method?id=sm_sK8d3Jq1tZxPjYVhRQW2rf&secret=4b5PyxKSOuunnnFruohoiF"
}