For archived content, access the previous documentation here or the previous API reference here.

Create a payment request

Updated on Sep 10, 2026
Published on Jan 9, 2025

Post

/v3/payment_requests

Create payment request. Initiates payment collection from end user. Use type to select the payment flow:

PAY: creates a payment request that can receive single payment.
PAY_AND_SAVE: collects single payment and saves a payment token for future use.
PAY with token: collects single payment from an existing payment_token_id.
REUSABLE_PAYMENT_CODE: creates a payment request that can receive multiple payments.
VERIFY_PAYMENT_METHOD: verifies a payment method without collecting a payment.

The request schema is shared across flows. Fields that are required or unsupported depend on the selected type and whether payment_token_id is provided. See the field descriptions and examples for valid requests.

Security

HTTP

Type basic

Header parameters

api-version

string

Valid values[ "2024-11-11" ]

for-user-id

string

The XenPlatform subaccount user id that will perform this transaction.

with-split-rule

string

The XenPlatform split rule id that will be applied to this transaction.

Body parameters

PAY_Cards_3DS_Auth

{
  "reference_id": "order_123456_3ds",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 100000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "cvn": "123",
      "card_number": "4000000000001091",
      "expiry_year": "2025",
      "expiry_month": "12",
      "cardholder_first_name": "John",
      "cardholder_last_name": "Doe",
      "cardholder_email": "john.doe@example.com",
      "cardholder_phone_number": "+628123456789"
    },
    "skip_three_ds": false,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Payment for Order #123456",
  "metadata": {
    "order_id": "123456",
    "customer_type": "premium"
  }
}

PAY_Cards_No_3DS

{
  "reference_id": "order_123457_no3ds",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 50000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "cvn": "456",
      "card_number": "5200000000001096",
      "expiry_year": "2026",
      "expiry_month": "06",
      "cardholder_first_name": "Jane",
      "cardholder_last_name": "Doe",
      "cardholder_email": "jane.doe@example.com",
      "cardholder_phone_number": "+6312345678901"
    },
    "skip_three_ds": true,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Quick checkout for Order #123457",
  "metadata": {
    "order_id": "123457",
    "checkout_type": "express"
  }
}

PAY_Cards_Manual_Capture

{
  "reference_id": "booking_123458",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 250000,
  "capture_method": "MANUAL",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "cvn": "789",
      "card_number": "4000000000000002",
      "expiry_year": "2027",
      "expiry_month": "03",
      "cardholder_first_name": "John",
      "cardholder_last_name": "Doe",
      "cardholder_email": "john.doe@example.com",
      "cardholder_phone_number": "+6212345678902"
    },
    "skip_three_ds": false,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Hotel booking pre-authorization #123458",
  "metadata": {
    "booking_id": "123458",
    "booking_type": "hotel"
  }
}

PAY_AND_SAVE_Cards

{
  "reference_id": "order_123459_save",
  "customer": {
    "reference_id": "customer_789",
    "type": "INDIVIDUAL",
    "individual_detail": {
      "given_names": "John",
      "surname": "Doe"
    },
    "email": "john.doe@example.com",
    "mobile_number": "+6212345678901"
  },
  "type": "PAY_AND_SAVE",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 500000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "cvn": "654",
      "card_number": "4000000000001109",
      "expiry_year": "2026",
      "expiry_month": "11",
      "cardholder_first_name": "John",
      "cardholder_last_name": "Doe",
      "cardholder_email": "john.doe@example.com",
      "cardholder_phone_number": "+6212345678901"
    },
    "skip_three_ds": false,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Initial subscription payment - Premium Plan",
  "metadata": {
    "order_id": "123459",
    "subscription_plan": "premium_monthly"
  }
}

PAY_WithToken_Cards

{
  "reference_id": "recurring_payment_123460",
  "payment_token_id": "pt-90392f42-d98a-49ef-a7f3-abcezas123",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 500000,
  "capture_method": "AUTOMATIC",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "skip_three_ds": true,
    "card_on_file_type": "RECURRING",
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Monthly subscription - Month 2",
  "metadata": {
    "subscription_id": "sub_789",
    "billing_cycle": "2"
  }
}

PAY_WithToken_TOUCHNGO

{
  "reference_id": "recurring_touchngo_123461",
  "payment_token_id": "pt-tng-90392f42-d98a-49ef-a7f3",
  "type": "PAY",
  "country": "MY",
  "currency": "MYR",
  "request_amount": 150,
  "capture_method": "AUTOMATIC",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Monthly toll payment - Touch n Go",
  "metadata": {
    "account_id": "tng_123461",
    "payment_type": "toll_recurring"
  }
}

PAY_Ewallet_Shopeepay

{
  "reference_id": "order_ph_987654",
  "type": "PAY",
  "country": "PH",
  "currency": "PHP",
  "request_amount": 1250,
  "capture_method": "AUTOMATIC",
  "channel_code": "SHOPEEPAY",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Online purchase - Order #987654",
  "metadata": {
    "order_id": "987654",
    "store_location": "manila_mall"
  }
}

PAY_QR_PromptPay

{
  "reference_id": "qr_th_321654",
  "type": "PAY",
  "country": "TH",
  "currency": "THB",
  "request_amount": 1500,
  "capture_method": "AUTOMATIC",
  "channel_code": "QRPROMPTPAY",
  "channel_properties": {
    "expires_at": "2025-01-15T23:59:59Z",
    "qr_string_type": "DYNAMIC"
  },
  "description": "Restaurant bill - Table 15",
  "metadata": {
    "order_id": "321654",
    "table_number": "15",
    "branch": "bangkok_central",
    "service_type": "dine_in"
  }
}

PAY_DirectDebit_BPI

{
  "reference_id": "dd_ph_456789_with_cust",
  "type": "PAY",
  "country": "PH",
  "currency": "PHP",
  "request_amount": 2500,
  "capture_method": "AUTOMATIC",
  "customer": {
    "type": "INDIVIDUAL",
    "reference_id": "customer_bpi_456789",
    "individual_detail": {
      "given_names": "Juan",
      "surname": "Dela Cruz"
    },
    "email": "juan.delacruz@example.com",
    "mobile_number": "+639123456789"
  },
  "channel_code": "BPI_DIRECT_DEBIT",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "description": "Bill payment - Account #456789",
  "metadata": {
    "bill_id": "456789",
    "customer_account": "ACC456789"
  }
}

REUSABLE_PAYMENT_CODE_VA_VietCapital

{
  "reference_id": "rpc_vn_123456",
  "type": "REUSABLE_PAYMENT_CODE",
  "country": "VN",
  "currency": "VND",
  "request_amount": 10000,
  "channel_code": "VIETCAPITAL_VIRTUAL_ACCOUNT",
  "channel_properties": {
    "display_name": "xenCommerce Shop"
  }
}

Expand All

object

reference_id

string Required

A reference ID from merchants to identify their request. For "CARDS" channel code, reference ID must be unique.

Min length1

Max length255

type

string Required

Payment request flow to execute. Please refer to the description mentioned above.

Valid values[ "PAY", "PAY_AND_SAVE", "REUSABLE_PAYMENT_CODE", "VERIFY_PAYMENT_METHOD" ]

country

string

ISO 3166-1 alpha-2 two-letter country code for the country of transaction.

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY", "HK", "MX" ]

ExampleID

currency

string Required

ISO 4217 three-letter currency code for the payment.

Valid values[ "IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD", "HKD", "AUD", "GBP", "EUR", "JPY", "MXN", "AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "FJD", "FKP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HNL", "HTG", "HUF", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "UYU", "UZS", "VEF", "VES", "VUV", "WST", "XAF", "XCD", "XCG", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWG", "ZWL" ]

ExampleIDR

channel_code

string

Channel code used to select the payment method provider.

Either channel_code or payment_token_id must be provided, but not both. channel_code is required for the standard PAY flow, PAY_AND_SAVE, REUSABLE_PAYMENT_CODE, and VERIFY_PAYMENT_METHOD.

Omit channel_code when payment_token_id is provided for the PAY pay-with-token flow.

channel_properties

object (Payments_API_ChannelProperties)

Data required to initiate transaction with payment method provider. Refer to the Channel Data Finder widget in the channel_code field above for the full list of required properties for each channel.

request_amount

number

The intended payment amount to be collected from the end user.

Minimum0.0

Example10000.0

payment_token_id

string

Identifier of an existing saved payment method.

This field is only supported when type is PAY. Providing this field selects the PAY pay-with-token flow.

When payment_token_id is provided:

channel_code, customer, and customer_id must be omitted;
request_amount is required and must be greater than zero.

Do not provide payment_token_id for PAY_AND_SAVE, REUSABLE_PAYMENT_CODE, or VERIFY_PAYMENT_METHOD.

Examplept-cc3938dc-c2a5-43c4-89d7-7570793348c2

capture_method

string

AUTOMATIC: payment capture will be processed immediately after payment request is created. MANUAL: payment capture requires merchant's trigger via payment capture endpoint before being processed

Valid values[ "AUTOMATIC", "MANUAL" ]

Default"AUTOMATIC"

ExampleAUTOMATIC

description

string

A custom description for the Payment Request.

Min length1

Max length1000

ExamplePayment for your order #123

customer_id

string

Xendit unique Customer ID generated as reference for the end user.

customer_id and customer are mutually exclusive; provide at most one. For PAY with payment_token_id, this field must be omitted. For PAY_AND_SAVE, either customer_id or customer is required, except when channel_code is CARDS.

Max length41

Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48

customer

object

Customer details associated with the payment request.

customer and customer_id are mutually exclusive; provide at most one. For PAY with payment_token_id, this field must be omitted. For PAY_AND_SAVE, either customer or customer_id is required, except when channel_code is CARDS.

type

string Required

Type of customer

Valid values[ "INDIVIDUAL" ]

reference_id

string Required

Merchant provided identifier for the customer. Must be unique. Alphanumeric no special characters allowed

Min length1

Max length255

string (email)

E-mail address of customer. Maximum length 50 characters

Min length4

Max length50

mobile_number

string

Mobile number of customer in E.164 format +(country code)(subscriber number)

Min length1

Max length50

individual_detail

object (Payments_API_XenditStandardIndividualDetail) Required

given_names

string Required

Primary or first name/s of customer. Alphanumeric. No special characters is allowed.

Min length1

Max length50

surname

string

Last or family name of customer. Alphanumeric. No special characters is allowed.

Min length1

Max length50

nationality

string

Country code for customer nationality. ISO 3166-1 alpha-2 Country Code

Min length2

Max length2

place_of_birth

string

City or other relevant location for the customer birth place. Alphanumeric. No special characters is allowed.

Min length1

Max length60

date_of_birth

string

Date of birth of the customer. Format: YYYY-MM-DD

Min length10

Max length10

gender

Gender of customer

Valid values[ "MALE", "FEMALE", "OTHER" ]

metadata

object (Payments_API_MerchantMetadata)

Key-value entries for your custom data. Xendit supports up to 50 key-value pairs, with key names up to 40 characters and primitive values of up to 500 characters in length. Xendit will not use this data for any processing.

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }

Responses

201

Payment Request Created

PAY_Cards_3DS_Auth

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "order_123456_3ds",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas123",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 100000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "masked_card_number": "4000****1091",
      "cardholder_first_name": "John",
      "cardholder_last_name": "Doe",
      "cardholder_email": "john.doe@example.com",
      "cardholder_phone_number": "+628123456789",
      "expiry_month": "12",
      "expiry_year": "2025",
      "fingerprint": "62397498595752001b9fdeba",
      "type": "DEBIT",
      "network": "VISA",
      "country": "ID",
      "issuer": "PT BANK MANDIRI"
    },
    "skip_three_ds": false,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [
    {
      "type": "REDIRECT_CUSTOMER",
      "value": "https://redirect.partner.com/3ds-auth-xyz",
      "descriptor": "WEB_URL"
    }
  ],
  "status": "REQUIRES_ACTION",
  "description": "Payment for Order #123456",
  "metadata": {
    "order_id": "123456",
    "customer_type": "premium"
  },
  "created": "2025-01-15T12:30:45Z",
  "updated": "2025-01-15T12:30:45Z"
}

PAY_Cards_No_3DS

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "order_123457_no3ds",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas124",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 50000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "masked_card_number": "5200****1096",
      "cardholder_first_name": "Jane",
      "cardholder_last_name": "Doe",
      "cardholder_email": "jane.doe@example.com",
      "cardholder_phone_number": "+6312345678901",
      "expiry_month": "06",
      "expiry_year": "2026",
      "fingerprint": "62397498595752001b9fdebc",
      "type": "CREDIT",
      "network": "MASTERCARD",
      "country": "ID",
      "issuer": "PT BANK BCA"
    },
    "skip_three_ds": true,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [],
  "status": "SUCCEEDED",
  "description": "Quick checkout for Order #123457",
  "metadata": {
    "order_id": "123457",
    "checkout_type": "express"
  },
  "latest_payment_id": "py-90392f42-d98a-49ef-a7f3-abcezas124",
  "latest_payment": {
    "payment_id": "py-90392f42-d98a-49ef-a7f3-abcezas124",
    "business_id": "5f27a14a9bf05c73dd040bc8",
    "reference_id": "order_123457_no3ds",
    "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas124",
    "type": "PAY",
    "country": "ID",
    "currency": "IDR",
    "request_amount": 50000,
    "capture_method": "AUTOMATIC",
    "channel_code": "CARDS",
    "status": "SUCCEEDED",
    "created": "2025-01-15T12:31:22Z",
    "updated": "2025-01-15T12:31:25Z",
    "captures": [
      {
        "capture_id": "cptr-90392f42-d98a-49ef-a7f3-abcezas124",
        "capture_timestamp": "2025-01-15T12:31:30Z",
        "capture_amount": 50000
      }
    ],
    "payment_details": {
      "authorization_data": {
        "authorization_code": "A1B2C3",
        "cvn_verification_result": "M",
        "address_verification_result": "M",
        "retrieval_reference_number": "akjsdiuh132127y9sacsdjn",
        "network_response_code": "00",
        "network_response_code_descriptor": "testing",
        "network_transaction_id": "dahskjdhiquh341",
        "acquirer_merchant_id": "alskdnuoqh341",
        "reconciliation_id": "oiajsdo1823938yrh2"
      }
    }
  },
  "created": "2025-01-15T12:31:22Z",
  "updated": "2025-01-15T12:31:25Z"
}

PAY_Cards_Manual_Capture

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "booking_123458",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas125",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 250000,
  "capture_method": "MANUAL",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "masked_card_number": "4000****0002",
      "cardholder_first_name": "John",
      "cardholder_last_name": "Doe",
      "cardholder_email": "john.doe@example.com",
      "cardholder_phone_number": "+6212345678902",
      "expiry_month": "03",
      "expiry_year": "2027",
      "fingerprint": "62397498595752001b9fdebd",
      "type": "CREDIT",
      "network": "VISA",
      "country": "ID",
      "issuer": "PT BANK BNI"
    },
    "skip_three_ds": false,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [],
  "status": "AUTHORIZED",
  "description": "Hotel booking pre-authorization #123458",
  "metadata": {
    "booking_id": "123458",
    "booking_type": "hotel"
  },
  "created": "2025-01-15T12:32:10Z",
  "updated": "2025-01-15T12:32:12Z"
}

PAY_AND_SAVE_Cards

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "order_123459_save",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas126",
  "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas789",
  "type": "PAY_AND_SAVE",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 500000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "card_details": {
      "masked_card_number": "4000****1109",
      "cardholder_first_name": "John",
      "cardholder_last_name": "Doe",
      "cardholder_email": "john.doe@example.com",
      "cardholder_phone_number": "+6212345678901",
      "expiry_month": "11",
      "expiry_year": "2026",
      "fingerprint": "62397498595752001b9fdebe",
      "type": "CREDIT",
      "network": "VISA",
      "country": "ID",
      "issuer": "PT BANK MANDIRI"
    },
    "skip_three_ds": false,
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [
    {
      "type": "REDIRECT_CUSTOMER",
      "value": "https://redirect.partner.com/3ds-auth-abc",
      "descriptor": "WEB_URL"
    }
  ],
  "status": "REQUIRES_ACTION",
  "description": "Initial subscription payment - Premium Plan",
  "metadata": {
    "order_id": "123459",
    "subscription_plan": "premium_monthly"
  },
  "created": "2025-01-15T12:33:15Z",
  "updated": "2025-01-15T12:33:15Z"
}

PAY_WithToken_Cards

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "recurring_payment_123460",
  "payment_token_id": "pt-90392f42-d98a-49ef-a7f3-abcezas123",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas127",
  "type": "PAY",
  "country": "ID",
  "currency": "IDR",
  "request_amount": 500000,
  "capture_method": "AUTOMATIC",
  "channel_code": "CARDS",
  "channel_properties": {
    "mid_label": "CTV_TEST",
    "skip_three_ds": true,
    "card_on_file_type": "RECURRING",
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [],
  "status": "SUCCEEDED",
  "description": "Monthly subscription - Month 2",
  "metadata": {
    "subscription_id": "sub_789",
    "billing_cycle": "2"
  },
  "latest_payment_id": "py-90392f42-d98a-49ef-a7f3-abcezas127",
  "latest_payment": {
    "payment_id": "py-90392f42-d98a-49ef-a7f3-abcezas127",
    "business_id": "5f27a14a9bf05c73dd040bc8",
    "reference_id": "recurring_payment_123460",
    "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas127",
    "type": "PAY",
    "country": "ID",
    "currency": "IDR",
    "request_amount": 500000,
    "capture_method": "AUTOMATIC",
    "channel_code": "CARDS",
    "status": "SUCCEEDED",
    "created": "2025-01-15T12:34:20Z",
    "updated": "2025-01-15T12:34:22Z",
    "captures": [
      {
        "capture_id": "cptr-90392f42-d98a-49ef-a7f3-abcezas127",
        "capture_timestamp": "2025-01-15T12:34:24Z",
        "capture_amount": 500000
      }
    ],
    "payment_details": {
      "authorization_data": {
        "authorization_code": "A1B2C3",
        "cvn_verification_result": "M",
        "address_verification_result": "M",
        "retrieval_reference_number": "akjsdiuh132127y9sacsdjn",
        "network_response_code": "00",
        "network_response_code_descriptor": "testing",
        "network_transaction_id": "dahskjdhiquh341",
        "acquirer_merchant_id": "alskdnuoqh341",
        "reconciliation_id": "oiajsdo1823938yrh2"
      }
    }
  },
  "created": "2025-01-15T12:34:20Z",
  "updated": "2025-01-15T12:34:22Z"
}

PAY_WithToken_TOUCHNGO

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "recurring_touchngo_123461",
  "payment_token_id": "pt-tng-90392f42-d98a-49ef-a7f3",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas128",
  "type": "PAY",
  "country": "MY",
  "currency": "MYR",
  "request_amount": 150,
  "capture_method": "AUTOMATIC",
  "channel_code": "TOUCHNGO",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [
    {
      "type": "REDIRECT_CUSTOMER",
      "value": "https://redirect.partner.com/touchngo-auth-xyz",
      "descriptor": "WEB_URL"
    }
  ],
  "status": "REQUIRES_ACTION",
  "description": "Monthly toll payment - Touch n Go",
  "metadata": {
    "account_id": "tng_123461",
    "payment_type": "toll_recurring"
  },
  "created": "2025-01-15T12:35:30Z",
  "updated": "2025-01-15T12:35:30Z"
}

PAY_Ewallet_Shopeepay

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "order_ph_987654",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas129",
  "type": "PAY",
  "country": "PH",
  "currency": "PHP",
  "request_amount": 1250,
  "capture_method": "AUTOMATIC",
  "channel_code": "SHOPEEPAY",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [
    {
      "type": "REDIRECT_CUSTOMER",
      "value": "https://redirect.partner.com/shopeepay-auth-xyz",
      "descriptor": "WEB_URL"
    }
  ],
  "status": "REQUIRES_ACTION",
  "description": "Online purchase - Order #987654",
  "metadata": {
    "order_id": "987654",
    "store_location": "manila_mall"
  },
  "created": "2025-01-15T12:36:45Z",
  "updated": "2025-01-15T12:36:45Z"
}

PAY_QR_PromptPay

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "qr_th_321654",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas130",
  "type": "PAY",
  "country": "TH",
  "currency": "THB",
  "request_amount": 1500,
  "capture_method": "AUTOMATIC",
  "channel_code": "QRPROMPTPAY",
  "channel_properties": {
    "expires_at": "2025-01-15T23:59:59Z",
    "qr_string_type": "DYNAMIC"
  },
  "actions": [
    {
      "type": "PRESENT_TO_CUSTOMER",
      "descriptor": "QR_STRING",
      "value": "00020101021153037643011A0000000677010111013202120000000000000000052048405303764540415005802TH5925THAI QR PAYMENT (EXAMPLE)6007Bangkok62070703001"
    }
  ],
  "status": "REQUIRES_ACTION",
  "description": "Restaurant bill - Table 15",
  "metadata": {
    "order_id": "321654",
    "table_number": "15",
    "branch": "bangkok_central",
    "service_type": "dine_in"
  },
  "created": "2025-01-15T12:37:50Z",
  "updated": "2025-01-15T12:37:50Z"
}

PAY_DirectDebit_BPI

{
  "business_id": "5f27a14a9bf05c73dd040bc8",
  "reference_id": "dd_ph_456789_with_cust",
  "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas132",
  "customer_id": "cust-e60078dd-494c-483c-a1e2-4f7bc34ff728",
  "type": "PAY",
  "country": "PH",
  "currency": "PHP",
  "request_amount": 2500,
  "capture_method": "AUTOMATIC",
  "channel_code": "BPI_DIRECT_DEBIT",
  "channel_properties": {
    "failure_return_url": "https://xendit.co/failure",
    "success_return_url": "https://xendit.co/success"
  },
  "actions": [
    {
      "type": "API_POST_REQUEST",
      "descriptor": "VALIDATE_OTP",
      "value": "https://api.xendit.co/v1/direct_debits/authorize"
    }
  ],
  "status": "REQUIRES_ACTION",
  "description": "Bill payment - Account #456789",
  "metadata": {
    "bill_id": "456789",
    "customer_account": "ACC456789"
  },
  "created": "2025-01-15T12:39:10Z",
  "updated": "2025-01-15T12:39:10Z"
}

REUSABLE_PAYMENT_CODE_VA_VietCapital

{
  "created": "2025-10-21T09:14:48.966Z",
  "updated": "2025-10-21T09:14:48.966Z",
  "channel_properties": {
    "display_name": "xenCommerce Shop",
    "expires_at": "2025-10-23T09:14:48.966Z"
  },
  "business_id": "6577c85379425b82e415c673",
  "reference_id": "rpc_vn_123456",
  "payment_request_id": "pr-73762759-0c9b-8178-b48f-0480d694b643",
  "type": "REUSABLE_PAYMENT_CODE",
  "country": "VN",
  "currency": "VND",
  "request_amount": 10000,
  "capture_method": "AUTOMATIC",
  "channel_code": "VIETCAPITAL_VIRTUAL_ACCOUNT",
  "actions": [
    {
      "type": "PRESENT_TO_CUSTOMER",
      "descriptor": "VIRTUAL_ACCOUNT_NUMBER",
      "value": "8881761038089006"
    },
    {
      "type": "PRESENT_TO_CUSTOMER",
      "descriptor": "QR_STRING",
      "value": "00020101021238600010A00000072701300006970454011688817610380890060208QRIBFTTA53037045802VN5405100006304C696"
    }
  ],
  "status": "REQUIRES_ACTION"
}

Expand All

object

Payment request object

business_id

string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8

reference_id

string

A reference ID from merchants to identify their request. For "CARDS" channel code, reference ID must be unique.

Min length1

Max length255

payment_request_id

string

Xendit unique Payment Request ID generated as reference after creation of payment request.

Examplepr-1102feb0-bb79-47ae-9d1e-e69394d3949c

payment_token_id

string

Xendit unique Payment Token ID generated as a reference for saved payment token of an end user.

Examplept-cc3938dc-c2a5-43c4-89d7-7570793348c2

customer_id

string

Xendit unique Customer ID generated as reference for the end user

Max length41

Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48

latest_payment_id

string

Latest Payment ID linked to the payment request.

Examplepy-1402feb0-bb79-47ae-9d1e-e69394d3949c

latest_payment

object

Latest payment information provided by the payment method provider. Fields returned are dependent on what is made available by the provider. Currently only available for "CARDS" channel code and only shown once the transaction reaches a terminal state (e.g. non 3DS transaction or MIT transaction).

payment_id

string

Xendit unique Payment ID generated as reference for a payment.

Examplepy-1402feb0-bb79-47ae-9d1e-e69394d3949c

business_id

string

Xendit-generated identifier for the business that owns the transaction

Example5f27a14a9bf05c73dd040bc8

reference_id

string

A Reference ID from merchants to identify their request.

Min length1

Max length255

payment_request_id

string

Xendit unique Payment Request ID generated as reference after creation of payment request.

Examplepr-1102feb0-bb79-47ae-9d1e-e69394d3949c

payment_token_id

string

Xendit unique Payment Token ID generated as a reference for saved payment token of an end user.

Examplept-cc3938dc-c2a5-43c4-89d7-7570793348c2

customer_id

string

Xendit unique Customer ID generated as reference for the end user

Max length41

Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48

type

string

The payment collection intent type for the payment request.

PAY: Create a payment request that is able to receive one payment.

PAY_AND_SAVE: Create a payment request that is able to receive one payment. If the payment is successful, a reusable payment token will be returned for subsequent payment requests.

REUSABLE_PAYMENT_CODE: Create a payment request that is able to receive multiple payments. This is only used for repeat use payment method like a static QR, a predefined OTC payment code or a predefined Virtual Account number.

Valid values[ "PAY", "PAY_AND_SAVE", "REUSABLE_PAYMENT_CODE" ]

country

string

ISO 3166-1 alpha-2 two-letter country code for the country of transaction.

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY", "HK", "MX" ]

ExampleID

currency

string

ISO 4217 three-letter currency code for the payment.

ExampleIDR

request_amount

number

The intended payment amount to be collected from the end user.

Minimum0.0

Example10000.0

capture_method

string

AUTOMATIC: payment capture will be processed immediately after payment request is created. MANUAL: payment capture requires merchant's trigger via payment capture endpoint before being processed

Valid values[ "AUTOMATIC", "MANUAL" ]

Default"AUTOMATIC"

ExampleAUTOMATIC

channel_code

string

Channel code used to select the payment method provider.

captures

Array of object (Payments_API_Capture)

object

Capture object contains information about the capture that was performed

capture_timestamp

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

capture_id

string

Xendit unique Capture ID generated as reference for a single capture.

Examplecap-1502feb0-bb79-47ae-9d1e-e69394d3949c

capture_amount

number

The payment amount captured for this payment. Maximum capture amount can only be equal or lesser than the authorized amount value.

Minimum0.0

Example10000.0

status

string

Status of the payment.

Valid values[ "AUTHORIZED", "CANCELED", "SUCCEEDED", "FAILED", "EXPIRED", "PENDING" ]

ExampleSUCCEEDED

payment_details

object (Payments_API_PaymentDetails)

Payment information provided by the payment method provider. Fields returned are dependent on what is made available by the provider.

authorization_data

object (Payments_API_AuthorizationData)

Specific to cards transaction only. Details about the card authorization processing.

authorization_code

string

Authorization approval code from the scheme. 6 alphanumeric characters.

cvn_verification_result

string

Whether CVN input matches with the issuer's data.

Valid values[ "M", "N" ]

address_verification_result

string

Whether the end user's address input matches with the issuer's data.

Valid values[ "M", "N" ]

retrieval_reference_number

string

Receipt reference number communicated to the end user by their card issuer for this specific payment. This a commonly used reference number for the end users to raise tickets.

network_response_code

string

The response code returned by the scheme (Visa, Mastercard, JCB, China Unionpay or Amex).

network_response_code_descriptor

string

Description of the response code.

network_transaction_id

string

Transaction ID received from the card scheme. Only available for merchants on switcher model.

acquirer_merchant_id

string

Acquirer's record of the MID that was used to process this transaction. Only available for merchants on switcher model.

reconciliation_id

string

Acquirer's transaction record of the payment on their settlement statement. Only available for merchants on switcher model.

authentication_data

object (Payments_API_AuthenticationData)

Specific to cards transaction only. Details about the card authentication.

flow

string

Indicates the flow that was used for the 3DS authentication.

Valid values[ "FULL_AUTH", "FRICTIONLESS" ]

a_res

object

Details about the card authentication response from the 3DS server.

eci

string

Payment system-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.

message_version

string

The 3DS protocol version which has been used to perform 3DS.

authentication_value

string

The result value from the 3DS transaction received from the ACS. This value is no longer present on responses after 45 days have passed after the authentication. Note that Mastercard and Visa use a different underlying format.

ds_trans_id

string

Universally unique transaction identifier assigned by the DS to identify a single transaction.

digital_wallet

string

Name of the digital wallet used by the end user.

issuer_name

string

Name of the payment method provider used by the end user.

payer_account_number

string

Account number of the end user making the payment from the payment method provider's records.

payer_name

string

Name of the end user making the payment from the payment method provider's records.

receipt_id

string

Receipt reference number communicated to the end user by their payment method provider for this specific payment. This a commonly used reference number for the end users to raise tickets.

remark

string

Remarks about this specific payment from the payment method provider's records.

network

string

Payment network which the payment was processed over.

fund_source

string

Information about what was used by the end user to complete the payment. e.g. balance, installment, credit.

failure_code

string

Failure codes for payments.

Valid values[ "ACCOUNT_ACCESS_BLOCKED", "INVALID_MERCHANT_SETTINGS", "INVALID_ACCOUNT_DETAILS", "PAYMENT_ATTEMPT_COUNTS_EXCEEDED", "USER_DEVICE_UNREACHABLE", "CHANNEL_UNAVAILABLE", "INSUFFICIENT_BALANCE", "ACCOUNT_NOT_ACTIVATED", "INVALID_TOKEN", "SERVER_ERROR", "PARTNER_TIMEOUT_ERROR", "TIMEOUT_ERROR", "USER_DECLINED_PAYMENT", "USER_DID_NOT_AUTHORIZE", "PAYMENT_REQUEST_EXPIRED", "FAILURE_DETAILS_UNAVAILABLE", "EXPIRED_OTP", "INVALID_OTP", "PAYMENT_AMOUNT_LIMITS_EXCEEDED", "OTP_ATTEMPT_COUNTS_EXCEEDED", "CARD_DECLINED", "DECLINED_BY_ISSUER", "ISSUER_UNAVAILABLE", "INVALID_CVV", "DECLINED_BY_PROCESSOR", "CAPTURE_AMOUNT_EXCEEDED ", "AUTHENTICATION_FAILED", "PROCESSOR_ERROR", "EXPIRED_CARD", "STOLEN_CARD", "INACTIVE_OR_UNAUTHORIZED_CARD", "INVALID_MERCHANT_CREDENTIALS", "SUSPECTED_FRAUDULENT" ]

ExampleCARD_DECLINED

metadata

object (Payments_API_MerchantMetadata)

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }

created

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

updated

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

type

string

The payment collection intent type for the payment request.

PAY: Create a payment request that is able to receive one payment.

PAY_AND_SAVE: Create a payment request that is able to receive one payment. If the payment is successful, a reusable payment token will be returned for subsequent payment requests.

Valid values[ "PAY", "PAY_AND_SAVE", "REUSABLE_PAYMENT_CODE" ]

country

string

ISO 3166-1 alpha-2 two-letter country code for the country of transaction.

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY", "HK", "MX" ]

ExampleID

currency

string

ISO 4217 three-letter currency code for the payment.

ExampleIDR

request_amount

number

The intended payment amount to be collected from the end user.

Minimum0.0

Example10000.0

capture_method

string

AUTOMATIC: payment capture will be processed immediately after payment request is created. MANUAL: payment capture requires merchant's trigger via payment capture endpoint before being processed

Valid values[ "AUTOMATIC", "MANUAL" ]

Default"AUTOMATIC"

ExampleAUTOMATIC

channel_code

string

Channel code used to select the payment method provider.

channel_properties

object (Payments_API_ChannelProperties)

Data required to initiate transaction with payment method provider. Refer to the Channel Data Finder widget in the channel_code field above for the full list of required properties for each channel.

actions

Array of object (Payments_API_Actions)

object

Actions object contains possible next steps merchants can take to proceed with payment collection from end user

type

The type of action that merchant system will need to handle to complete payment.

Valid values[ "PRESENT_TO_CUSTOMER", "REDIRECT_CUSTOMER", "API_POST_REQUEST" ]

descriptor

The type of action that merchant system will need to handle to complete payment.

Valid values[ "CAPTURE_PAYMENT", "PAYMENT_CODE", "QR_STRING", "VIRTUAL_ACCOUNT_NUMBER", "WEB_URL", "DEEPLINK_URL", "VALIDATE_OTP", "RESEND_OTP" ]

value

string

The specific value that will be used by merchant to complete the action

status

string

Status of the payment request.

Valid values[ "ACCEPTING_PAYMENTS", "REQUIRES_ACTION", "AUTHORIZED", "CANCELED", "EXPIRED", "SUCCEEDED", "FAILED" ]

ExampleSUCCEEDED

failure_code

string

Failure codes for payments.

ExampleCARD_DECLINED

description

string

A custom description for the Payment Request.

Min length1

Max length1000

ExamplePayment for your order #123

metadata

object (Payments_API_MerchantMetadata)

Example{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }

created

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

updated

string (date-time)

ISO 8601 date-time format.

Example2021-12-31T23:59:59Z

400

Bad request

OneOf

Payments_API_Http400InvalidValueError

object (Payments_API_Http400InvalidValueError)

error_code

string

Valid values[ "INVALID_VALUE_ERROR" ]

message

string

Values in the payment request is not within expected range or expected configurations. Check the specific error message for debugging.

Payments_API_Http400ApiValidationError

object (Payments_API_Http400ApiValidationError)

error_code

string

Valid values[ "API_VALIDATION_ERROR" ]

message

string

Fields or values in the payment request does not comply with our API specification. Check the specific error message for debugging.

Payments_API_Http400CardExpired

object (Payments_API_Http400CardExpired)

error_code

string

Valid values[ "CARD_EXPIRED" ]

message

string

Card expiry specified in the request should not be earlier than current month.

Payments_API_Http400InvalidPaymentDetails

object (Payments_API_Http400InvalidPaymentDetails)

error_code

string

Valid values[ "INVALID_PAYMENT_DETAILS" ]

message

string

The payment details entered by the end user is invalid. Check the specific error message for debugging.

Payments_API_Http400PaymentRequestRateLimited

object (Payments_API_Http400PaymentRequestRateLimited)

error_code

string

Valid values[ "PAYMENT_REQUEST_RATE_LIMITED" ]

message

string

Maximum number of requests to this payment channel has been exceeded in a given time frame.

Payments_API_Http400InvalidToken

object (Payments_API_Http400InvalidToken)

error_code

string

Valid values[ "INVALID_TOKEN" ]

message

string

Payment token ID specified in the payment request has expired or has been cancelled. Please reinitiate linking before retrying.

403

Forbidden

OneOf

Payments_API_Http403Skip3dsForbidden

object (Payments_API_Http403Skip3dsForbidden)

error_code

string

Valid values[ "SKIP_3DS_FORBIDDEN" ]

message

string

Non 3DS payment request for cards is not allowed. Please activate the feature on Xendit dashboard before proceeding.

Payments_API_Http403InvalidMerchantSettings

object (Payments_API_Http403InvalidMerchantSettings)

error_code

string

Valid values[ "INVALID_MERCHANT_SETTINGS" ]

message

string

Merchant credentials met with an error with the provider. Please contact Xendit customer support to resolve this issue.

Payments_API_Http403AccountAccessBlocked

object (Payments_API_Http403AccountAccessBlocked)

error_code

string

Valid values[ "ACCOUNT_ACCESS_BLOCKED" ]

message

string

Payment token ID specified in the request was denied access by the payment method provider.

409

Conflict

OneOf

Payments_API_Http409DuplicateError

object (Payments_API_Http409DuplicateError)

error_code

string

Valid values[ "DATA_NOT_FOUND" ]

message

string

Duplication is not allowed. Check specific error message for debugging.

Payments_API_Http409AccountAlreadyLinked

object (Payments_API_Http409AccountAlreadyLinked)

error_code

string

Valid values[ "ACCOUNT_ALREADY_LINKED" ]

message

string

The end user has already linked their account previously.

500

Internal server error

OneOf

Payments_API_Http500ServerError

object (Payments_API_Http500ServerError)

error_code

string

Valid values[ "SERVER_ERROR" ]

message

string

An unexpected error occured, our team has been notified and will troubleshoot the issue

503

Service unavailable

OneOf

Payments_API_Http503ChannelUnavailable

object (Payments_API_Http503ChannelUnavailable)

error_code

string

Valid values[ "CHANNEL_UNAVAILABLE" ]

message

string

The channel requested is currently experiencing unexpected issues. The provider will be notified to resolve this issue.

Payments_API_Http503IssuerUnavailable

object (Payments_API_Http503IssuerUnavailable)

error_code

string

Valid values[ "ISSUER_UNAVAILABLE" ]

message

string

The end user's payment method provider is currently experiencing unexpected issues. The provider will be notified to resolve this issue.

Was this article helpful?