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

Create a session

  • Updated on Mar 6, 2026
  • Published on Dec 4, 2024
Prev Next
Post
/sessions

Initiate the process of collecting payments from your customer. We recommend creating a new Session from your server and redirect the customer to the Session Hosted Checkout page. Once payment has succeeded, Session will contain a reference Payment ID or the Payment Token ID. You get the outcome asynchronously in a Session webhook.

Security
HTTP
Type basic
Header parameters
for-user-id
string

The XenPlatform subaccount user id that will perform this transaction.

Body parameters
PaymentLink_OneTimePaymentExample
{
  "reference_id": "order_12345_PAY",
  "session_type": "PAY",
  "mode": "PAYMENT_LINK",
  "amount": 10000,
  "currency": "PHP",
  "country": "PH",
  "customer": {
    "reference_id": "cust_Lorem_Ipsum",
    "type": "INDIVIDUAL",
    "email": "test@yourdomain.com",
    "mobile_number": "+6212345678",
    "individual_detail": {
      "given_names": "Lorem",
      "surname": "Ipsum"
    }
  },
  "items": [
    {
      "reference_id": "item_001",
      "name": "Clothes",
      "description": "Red clothes",
      "type": "PHYSICAL_PRODUCT",
      "category": "CLOTHES",
      "net_unit_amount": 5000,
      "quantity": 1,
      "currency": "PHP",
      "url": "https://example.com/item"
    },
    {
      "reference_id": "item_002",
      "name": "Pants",
      "description": "Black pants",
      "type": "PHYSICAL_PRODUCT",
      "category": "CLOTHES",
      "net_unit_amount": 5000,
      "quantity": 1,
      "currency": "PHP",
      "url": "https://example.com/item"
    }
  ],
  "capture_method": "AUTOMATIC",
  "locale": "en",
  "description": "Sample one-time payment using Payment Session",
  "success_return_url": "https://yourcompany.com/success/example_item=my_item",
  "cancel_return_url": "https://yourcompany.com/cancel/example_item=my_item"
}
PaymentLink_PayandSaveExample
{
  "reference_id": "order_123456_SAVE",
  "customer": {
    "reference_id": "cust_Lorem_Ipsum",
    "type": "INDIVIDUAL",
    "email": "test@yourdomain.com",
    "mobile_number": "+6212345678",
    "individual_detail": {
      "given_names": "Lorem",
      "surname": "Ipsum"
    }
  },
  "session_type": "PAY",
  "currency": "IDR",
  "amount": 10000,
  "mode": "PAYMENT_LINK",
  "allow_save_payment_method": "OPTIONAL",
  "country": "ID",
  "locale": "en",
  "description": "Insurance Plan Registration",
  "success_return_url": "https://yourcompany.com/success/example_item=my_item",
  "cancel_return_url": "https://yourcompany.com/cancel/example_item=my_item"
}
PaymentLink_SavePaymentMethodExample
{
  "reference_id": "order_123456_SAVE",
  "customer": {
    "reference_id": "cust_Lorem_Ipsum",
    "type": "INDIVIDUAL",
    "email": "test@yourdomain.com",
    "mobile_number": "+6212345678",
    "individual_detail": {
      "given_names": "Lorem",
      "surname": "Ipsum"
    }
  },
  "session_type": "SAVE",
  "currency": "IDR",
  "amount": 0,
  "mode": "PAYMENT_LINK",
  "country": "ID",
  "locale": "en",
  "description": "Insurance Plan Registration",
  "success_return_url": "https://yourcompany.com/success/example_item=my_item",
  "cancel_return_url": "https://yourcompany.com/cancel/example_item=my_item"
}
Expand All
object
reference_id
string Required

Your reference to uniquely identify the Payment Session. This is commonly used to identify your order or transaction.

Min length1
Max length64
customer_id
string

A unique identifier automatically generated by Xendit to represent an end customer. This ID can be used as a consistent reference across multiple transactions or payment activities for the same user. You can create a customer object in advance through the Create Customer API here: https://xendit-docs.document360.io/apidocs/create-customer-request

Min length41
Max length41
Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48
customer
object (Payment_Session_CustomerDetails)
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
email
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 (Payment_Session_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" ]
session_type
string Required

The use case for Payment Session. SAVE: save the payment details from a customer for future payments. PAY: collects a one-time payment from a customer.

Valid values[ "SAVE", "PAY" ]
allow_save_payment_method
string

The option to save the payment details from a customer for the PAY session_type. Saved payment details can be used for future payments. DISABLED: does not save the payment details. OPTIONAL: allows the customer to opt-in to save the payment details. FORCED: always save the payment details.

Valid values[ "DISABLED", "OPTIONAL", "FORCED" ]
currency
string Required

ISO 4217 three-letter currency code for the payment.

Valid values[ "IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD" ]
ExampleIDR
amount
number Required

The payment amount to be collected from the customer. For SAVE session_type, the amount must be 0.

Minimum0.0
Example10000.0
mode
string Required

The frontend integration mode for Payment Session. PAYMENT_LINK: redirect the customer to the Xendit Hosted Checkout page. COMPONENTS: collect payment details from customer with Xendit Component SDK.

Valid values[ "PAYMENT_LINK", "COMPONENTS" ]
capture_method
string

The method to capture the payment. AUTOMATIC: capture the payment automatically. MANUAL: capture the payment manually using Payment Capture API

Valid values[ "AUTOMATIC", "MANUAL" ]
country
string Required

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

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY" ]
ExampleID
channel_properties
object (Payment_Session_ChannelProperties)

Optional channel specific properties to be sent to specific payment channel provider.

allowed_payment_channels
Array of string

Specify the list of payment channels for your customer to select from the Xendit Hosted Checkout page. By default all payment channels will be available if you leave this field empty.

Example[ "CARDS", "BRI_DIRECT_DEBIT", "DANA" ]
string
expires_at
string (date-time)

ISO 8601 date-time format. By default the Session will expire 30 minutes after creation. We recommend you to keep Sessions short-lived and create a new Session again only when the customer is ready to make payment.

Example2021-12-31T23:59:59Z
locale
string

ISO 639-1 two-letter language code for Hosted Checkout page.

Default"en"
Exampleen
metadata
object (Payment_Session_MerchantMetadata) | null

Key-value entries for your custom data/information. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is commonly used for your internal reference or reconciliation purposes. Xendit will not use this data for any processing.

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

A custom description for the Session. This text will be displayed on the Xendit Hosted Checkout page.

Min length1
Max length1000
ExamplePayment for your order #123
items
Array of object (Payment_Session_XenditStandardItem) | null

Array of objects describing the item/s attached to the session.

object
reference_id
string Required

Merchant provided identifier for the item

Min length1
Max length255
type

Type of item

Valid values[ "DIGITAL_PRODUCT", "PHYSICAL_PRODUCT", "DIGITAL_SERVICE", "PHYSICAL_SERVICE", "FEE" ]
name
string Required

Name of item

Min length1
Max length255
net_unit_amount
number Required

Net amount to be charged per unit

quantity
integer Required

Number of units of this item in the basket

Minimum1.0
url
string

URL of the item. Must be HTTPS or HTTP

image_url
string

URL of the image of the item. Must be HTTPS or HTTP

category
string Required

Category for item

Max length255
subcategory
string

Sub-category for item

Max length255
description
string

Description of item

Max length255
metadata
object (Payment_Session_MerchantMetadata) | null

Key-value entries for your custom data/information. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is commonly used for your internal reference or reconciliation purposes. Xendit will not use this data for any processing.

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

Specify the URL to redirect the customer after the session is completed or expired, or if the customer decide to stop the payment process. Must be HTTPS. For example: "https://yourcompany.com/example_item=my_example_item"

Examplehttps://yourcompany.com/example_item
cancel_return_url
string

Specify the URL to redirect the customer after the session is completed or expired, or if the customer decide to stop the payment process. Must be HTTPS. For example: "https://yourcompany.com/example_item=my_example_item"

Examplehttps://yourcompany.com/example_item
Responses
201

Session Created

createSessionResponseExample
{
  "payment_session_id": "ps-661f87c614802d6c402cd82d",
  "created": "2021-12-31T23:59:59Z",
  "updated": "2021-12-31T23:59:59Z",
  "reference_id": "Alice",
  "customer_id": "cust-e2878b4c-d57e-4a2c-922d-c0313c2800a3",
  "session_type": "SAVE",
  "currency": "IDR",
  "amount": 0,
  "country": "ID",
  "mode": "PAYMENT_LINK",
  "channel_properties": {},
  "allowed_payment_channels": [
    "OVO",
    "DANA"
  ],
  "expires_at": "2021-12-31T23:59:59Z",
  "locale": "en",
  "description": "Insurance Plan Registration",
  "success_return_url": "https://yourcompany.com/success/example_item=my_item",
  "cancel_return_url": "https://yourcompany.com/cancel/example_item=my_item",
  "items": null,
  "metadata": null,
  "status": "ACTIVE",
  "payment_link_url": "https://xen.to/kGxPCi60",
  "payment_token_id": null,
  "payment_request_id": null,
  "business_id": "661f87c614802d6c402cd82d"
}
Expand All
object
payment_session_id
string

A unique identifier for the Payment Session

Min length27
Max length27
Exampleps-661f87c614802d6c402cd82d
created
string (date-time)
Example2021-12-31T23:59:59Z
updated
string (date-time)
Example2021-12-31T23:59:59Z
reference_id
string

Your reference to uniquely identify the Payment Session. This is commonly used to identify your order or transaction.

Min length1
Max length64
customer_id
string

A unique identifier automatically generated by Xendit to represent an end customer. This ID can be used as a consistent reference across multiple transactions or payment activities for the same user. You can create a customer object in advance through the Create Customer API here: https://xendit-docs.document360.io/apidocs/create-customer-request

Min length41
Max length41
Examplecust-b98d6f63-d240-44ec-9bd5-aa42954c4f48
session_type
string

The use case for Payment Session. SAVE: save the payment details from a customer for future payments. PAY: collects a one-time payment from a customer.

Valid values[ "SAVE", "PAY" ]
allow_save_payment_method
string

The option to save the payment details from a customer for the PAY session_type. Saved payment details can be used for future payments. DISABLED: does not save the payment details. OPTIONAL: allows the customer to opt-in to save the payment details. FORCED: always save the payment details.

Valid values[ "DISABLED", "OPTIONAL", "FORCED" ]
currency
string

ISO 4217 three-letter currency code for the payment.

Valid values[ "IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD" ]
ExampleIDR
amount
number

The payment amount to be collected from the customer. For SAVE session_type, the amount must be 0.

Minimum0.0
Example10000.0
country
string

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

Valid values[ "ID", "PH", "VN", "TH", "SG", "MY" ]
ExampleID
mode
string

The frontend integration mode for Payment Session. PAYMENT_LINK: redirect the customer to the Xendit Hosted Checkout page. COMPONENTS: collect payment details from customer with Xendit Component SDK.

Valid values[ "PAYMENT_LINK", "COMPONENTS" ]
capture_method
string

The method to capture the payment. AUTOMATIC: capture the payment automatically. MANUAL: capture the payment manually using Payment Capture API

Valid values[ "AUTOMATIC", "MANUAL" ]
channel_properties
object (Payment_Session_ChannelProperties)

Optional channel specific properties to be sent to specific payment channel provider.

allowed_payment_channels
Array of string

Specify the list of payment channels for your customer to select from the Xendit Hosted Checkout page. By default all payment channels will be available if you leave this field empty.

Example[ "CARDS", "BRI_DIRECT_DEBIT", "DANA" ]
string
expires_at
string (date-time)

ISO 8601 date-time format. By default the Session will expire 30 minutes after creation. We recommend you to keep Sessions short-lived and create a new Session again only when the customer is ready to make payment.

Example2021-12-31T23:59:59Z
locale
string

ISO 639-1 two-letter language code for Hosted Checkout page.

Default"en"
Exampleen
metadata
object (Payment_Session_MerchantMetadata) | null

Key-value entries for your custom data/information. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is commonly used for your internal reference or reconciliation purposes. Xendit will not use this data for any processing.

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

A custom description for the Session. This text will be displayed on the Xendit Hosted Checkout page.

Min length1
Max length1000
ExamplePayment for your order #123
items
Array of object (Payment_Session_XenditStandardItem) | null

Array of objects describing the item/s attached to the session.

object
reference_id
string

Merchant provided identifier for the item

Min length1
Max length255
type

Type of item

Valid values[ "DIGITAL_PRODUCT", "PHYSICAL_PRODUCT", "DIGITAL_SERVICE", "PHYSICAL_SERVICE", "FEE" ]
name
string

Name of item

Min length1
Max length255
net_unit_amount
number

Net amount to be charged per unit

quantity
integer

Number of units of this item in the basket

Minimum1.0
url
string

URL of the item. Must be HTTPS or HTTP

image_url
string

URL of the image of the item. Must be HTTPS or HTTP

category
string

Category for item

Max length255
subcategory
string

Sub-category for item

Max length255
description
string

Description of item

Max length255
metadata
object (Payment_Session_MerchantMetadata) | null

Key-value entries for your custom data/information. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is commonly used for your internal reference or reconciliation purposes. Xendit will not use this data for any processing.

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

Specify the URL to redirect the customer after the session is completed or expired, or if the customer decide to stop the payment process. Must be HTTPS. For example: "https://yourcompany.com/example_item=my_example_item"

Examplehttps://yourcompany.com/example_item
cancel_return_url
string

Specify the URL to redirect the customer after the session is completed or expired, or if the customer decide to stop the payment process. Must be HTTPS. For example: "https://yourcompany.com/example_item=my_example_item"

Examplehttps://yourcompany.com/example_item
status
string

The status of the Payment Session.

Valid values[ "ACTIVE", "COMPLETED", "EXPIRED", "CANCELED" ]
payment_link_url
string | null

The URL for Xendit Hosted Checkout page. Redirect your customer to this URL to complete the payment.

Examplehttps://checkout.xendit.co/sessions/ps-661f87c614802d6c402cd82d0 or https://xen.to/kGxPCi60. For test mode, https://checkout-staging.xendit.co/sessions/ps-661f87c614802d6c402cd82d0 or https://dev.xen.to/kGxPCi76
payment_token_id
string | null

Xendit Payment Token ID used to reference the saved payment details from the customer.

Exampleptkn-cc3938dc-c2a5-43c4-89d7-7570793348c2
payment_id
string | null

Xendit Payment ID used to reference the captured payment details from the customer.

Examplepy-ac1fcd3e-21c5-4c70-bb06-fa3c34e19e0c
payment_request_id
string | null

Xendit Payment Request ID used to reference the payment made during this Session.

Examplepr-0800fe40-bb79-47ae-9d1e-e69394d3949c
business_id
string
4XX

Error response for POST /sessions. Possible HTTP status codes: 400, 401, 404, 409.

apiValidationError

400 - Missing required field

{
  "error_code": "API_VALIDATION_ERROR",
  "message": "request/body must have required property 'session_type'",
  "errors": [
    {
      "message": "must have required property 'session_type'",
      "path": "/body/session_type"
    }
  ]
}
invalidAmount

400 - Amount must be greater than zero

{
  "error_code": "INVALID_AMOUNT",
  "message": "Amount must be greater than zero"
}
invalidPaymentChannel

400 - Payment channel not available

{
  "error_code": "INVALID_PAYMENT_CHANNEL",
  "message": "Channel(s) INVALID_CHANNEL are not available. Please ensure that you have activated the necessary channels"
}
invalidPrimaryPaymentChannel

400 - Primary channel not in allowed channels

{
  "error_code": "INVALID_PRIMARY_PAYMENT_CHANNEL",
  "message": "Primary channel BPI_DIRECT_DEBIT is not included in the requested channels"
}
invalidMetadata

400 - Metadata value exceeds limit

{
  "error_code": "INVALID_METADATA",
  "message": "Metadata value must have at most 80 characters"
}
invalidItemMetadata

400 - Item metadata value exceeds limit

{
  "error_code": "INVALID_ITEM_METADATA",
  "message": "Metadata value must have at most 80 characters"
}
invalidCustomerId

400 - Customer ID format invalid

{
  "error_code": "INVALID_CUSTOMER_ID",
  "message": "Customer ID must start with \"cust-\""
}
invalidUrl

400 - Invalid URL format

{
  "error_code": "INVALID_URL",
  "message": "Please provide a valid HTTPS URL"
}
missingCustomer

400 - Customer required but not provided

{
  "error_code": "MISSING_CUSTOMER",
  "message": "Customer object or customer_id is required"
}
disallowedCaptureMethod

400 - Capture method not allowed for session type

{
  "error_code": "DISALLOWED_CAPTURE_METHOD",
  "message": "Capture method is not supported for session type SAVE"
}
invalidExpiryDate

400 - Expiry date is invalid

{
  "error_code": "INVALID_EXPIRY_DATE",
  "message": "expires_at must be at least 10 minutes in the future"
}
itemsNotSupported

400 - Items not allowed for session type

{
  "error_code": "ITEMS_NOT_SUPPORTED",
  "message": "Items are allowed for session type PAY only"
}
sessionTypeNotSupported

400 - Session type not supported

{
  "error_code": "SESSION_TYPE_NOT_SUPPORTED",
  "message": "session_type AUTHORIZATION is not supported for now"
}
modeNotSupported

400 - Mode not supported

{
  "error_code": "MODE_NOT_SUPPORTED",
  "message": "mode INVALID_MODE is not supported for now"
}
invalidApiKey

401 - Invalid API key

{
  "error_code": "INVALID_API_KEY",
  "message": "API key is not authorized for this API"
}
dataNotFound

404 - Customer ID does not exist

{
  "error_code": "DATA_NOT_FOUND",
  "message": "The customer ID provided in the request does not exist"
}
duplicateError

409 - Duplicate customer reference_id

{
  "error_code": "DUPLICATE_ERROR",
  "message": "customer: The reference_id entered has been used before. Please enter a unique reference_id"
}
object
error_code
string

400 error codes:

  • API_VALIDATION_ERROR - Generic request validation failure such as missing required fields, invalid enum values, invalid field formats, or constraint violations (e.g. missing session_type, invalid allow_save_payment_method value, missing cards_session_js properties, invalid components_configuration.origins, missing subscription.schedule fields, card_details not allowed on channel_properties.cards, recurring_configuration required when card_on_file_type is RECURRING or MERCHANT_UNSCHEDULED, internal_metadata not allowed).
  • INVALID_AMOUNT - Amount validation failed. For PAY/SUBSCRIPTION session types, amount must be greater than zero. For SAVE session type, amount must be zero. Amount must also respect the decimal places allowed for the given currency.
  • INVALID_PAYMENT_CHANNEL - One or more requested payment channels are not recognized, not activated for your account, not supported for the requested session configuration, or no channels are available for the given capture_method, allow_save_payment_method, or country/currency combination.
  • INVALID_PRIMARY_PAYMENT_CHANNEL - A channel specified in payment_link_configuration.primary_payment_channels is not included in allowed_payment_channels.
  • INVALID_METADATA - Session-level metadata validation failed. Metadata supports a maximum of 20 keys, each key up to 40 characters, each value must be a string of up to 80 characters.
  • INVALID_ITEM_METADATA - Item-level metadata validation failed. Same constraints as session-level metadata.
  • INVALID_COUNTRY - The provided country is not supported.
  • INVALID_CURRENCY - The provided currency is not supported.`
  • INVALID_CUSTOMER_ID - The provided customer_id does not start with the required cust- prefix.
  • INVALID_URL - A URL field (e.g. success_return_url, cancel_return_url) is not a valid HTTPS URL.
  • MISSING_CUSTOMER - A customer object or customer_id is required but was not provided. Required when session_type is SAVE, when mode is CARDS_SESSION_JS, or when allow_save_payment_method is FORCED or OPTIONAL.
  • DISALLOWED_CAPTURE_METHOD - capture_method was provided for a session type that does not support it (e.g. SAVE or SUBSCRIPTION).
  • INVALID_EXPIRY_DATE - The provided expires_at value is invalid. It must be at least 10 minutes in the future and must not exceed the maximum allowed expiry duration.
  • ITEMS_NOT_SUPPORTED - items were provided for a session type other than PAY.
  • SESSION_TYPE_NOT_SUPPORTED - The provided session_type is not supported (e.g. AUTHORIZATION).
  • MODE_NOT_SUPPORTED - The provided mode is not supported.

401 error codes:

  • INVALID_API_KEY - The API key provided is invalid or missing.

404 error codes:

  • DATA_NOT_FOUND - The customer_id provided in the request does not exist.

409 error codes:

  • DUPLICATE_ERROR - A customer with the same reference_id already exists for a different business.
Valid values[ "API_VALIDATION_ERROR", "INVALID_AMOUNT", "INVALID_PAYMENT_CHANNEL", "INVALID_PRIMARY_PAYMENT_CHANNEL", "INVALID_METADATA", "INVALID_ITEM_METADATA", "INVALID_CURRENCY", "INVALID_COUNTRY", "INVALID_CUSTOMER_ID", "INVALID_URL", "MISSING_CUSTOMER", "DISALLOWED_CAPTURE_METHOD", "INVALID_EXPIRY_DATE", "ITEMS_NOT_SUPPORTED", "SESSION_TYPE_NOT_SUPPORTED", "MODE_NOT_SUPPORTED", "INVALID_API_KEY", "DATA_NOT_FOUND", "DUPLICATE_ERROR" ]
message
string

Human-readable description of the error.

errors
Array
OneOf
string
string
object
object
5XX

Internal Server Error

serverError

500 - Internal server error

{
  "error_code": "SERVER_ERROR",
  "message": "Something unexpected happened. We are investigating this issue. Please try again later."
}
object
error_code
string
  • SERVER_ERROR - Something unexpected happened. Please try again later.
Valid values[ "SERVER_ERROR" ]
message
string

Human-readable description of the error.

errors
Array
OneOf
string
string
object
object