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 Request or the Payment Token. You get the outcome asynchronously in a Session webhook.
The XenPlatform subaccount user id that will perform this transaction.
{
"reference_id": "order_123456_SAVE",
"customer_id": "cust-e2878b4c-d57e-4a2c-922d-c0313c2800a3",
"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"
}{
"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"
}{
"reference_id": "registration_123456_SAVE",
"session_type": "SAVE",
"mode": "PAYMENT_LINK",
"amount": 0,
"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"
}
},
"capture_method": "AUTOMATIC",
"locale": "en",
"description": "Insurance Plan Registration",
"success_return_url": "https://yourcompany.com/success/save_payment_method",
"cancel_return_url": "https://yourcompany.com/cancel/save_payment_method"
}{
"reference_id": "order_12345_PAY",
"customer_id": "cust-e2878b4c-d57e-4a2c-922d-c0313c2800a3",
"session_type": "PAY",
"currency": "IDR",
"amount": 0,
"mode": "CARDS_SESSION_JS",
"country": "ID",
"channel_properties": {
"card_on_file_type": "CUSTOMER_UNSCHEDULED"
},
"cards_session_js": {
"success_return_url": "https://yourcompany.com/success/example_item=my_item",
"failure_return_url": "https://yourcompany.com/failure/example_item=my_item"
},
"locale": "en",
"description": "Clothes Purchase"
}{
"reference_id": "registration_123456_SAVE",
"customer_id": "cust-e2878b4c-d57e-4a2c-922d-c0313c2800a3",
"session_type": "SAVE",
"currency": "IDR",
"amount": 0,
"mode": "CARDS_SESSION_JS",
"country": "ID",
"channel_properties": {
"card_on_file_type": "RECURRING",
"recurring_configuration": {
"recurring_frequency": 1,
"recurring_expiry": "2029-10-10"
}
},
"cards_session_js": {
"success_return_url": "https://yourcompany.com/success/example_item=my_item",
"failure_return_url": "https://yourcompany.com/failure/example_item=my_item"
},
"locale": "en",
"description": "Insurance Plan Registration"
}{
"reference_id": "order_12345_PAYANDSAVE",
"customer_id": "cust-e2878b4c-d57e-4a2c-922d-c0313c2800a3",
"session_type": "PAY",
"allow_save_payment_method": "FORCED",
"currency": "IDR",
"amount": 0,
"mode": "CARDS_SESSION_JS",
"country": "ID",
"channel_properties": {
"card_on_file_type": "CUSTOMER_UNSCHEDULED"
},
"cards_session_js": {
"success_return_url": "https://yourcompany.com/success/example_item=my_item",
"failure_return_url": "https://yourcompany.com/failure/example_item=my_item"
},
"locale": "en",
"description": "Ride book"
}A reference to uniquely identify the Payment Session.
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
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
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.
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. For CARDS_SESSION_JS mode use case, the value of allow_save_payment_method must be FORCED if the merchant is sending it. This field can be omitted by the merchant, which means the payment method won't be saved.
ISO 4217 three-letter currency code for the payment.
The payment amount to be collected from the customer. For SAVE session_type, the amount must be 0.
The frontend integration mode for Payment Session. PAYMENT_LINK: redirect the customer to the Xendit Hosted Checkout page. CARDS_SESSION_JS: collect payment details from customer with cards-session Javascript library. Only supported PAYMENT_LINK and CARDS_SESSION_JS as mode for now.
The method to capture the payment. AUTOMATIC: capture the payment automatically. MANUAL: capture the payment manually.
ISO 3166-1 alpha-2 two-letter country code for the country of transaction.
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.
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.
ISO 639-1 two-letter language code for Hosted Checkout page.
Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.
A custom description for the Session. This text will be displayed on the Xendit Hosted Checkout page.
Array of objects describing the item/s attached to the session.
Merchant provided identifier for the item
Type of item
Name of item
Net amount to be charged per unit
Number of units of this item in the basket
URL of the item. Must be HTTPS or HTTP
URL of the image of the item. Must be HTTPS or HTTP
Category for item
Sub-category for item
Description of item
Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.
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"
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"
Session Created
{
"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"
}A unique identifier for the Payment Session
A reference to uniquely identify the Payment Session.
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
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.
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. For CARDS_SESSION_JS mode use case, the value of allow_save_payment_method must be FORCED if the merchant is sending it. This field can be omitted by the merchant, which means the payment method won't be saved.
ISO 4217 three-letter currency code for the payment.
The payment amount to be collected from the customer. For SAVE session_type, the amount must be 0.
ISO 3166-1 alpha-2 two-letter country code for the country of transaction.
The frontend integration mode for Payment Session. PAYMENT_LINK: redirect the customer to the Xendit Hosted Checkout page. CARDS_SESSION_JS: collect payment details from customer with cards-session Javascript library. Only supported PAYMENT_LINK and CARDS_SESSION_JS as mode for now.
The method to capture the payment. AUTOMATIC: capture the payment automatically. MANUAL: capture the payment manually.
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.
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.
ISO 639-1 two-letter language code for Hosted Checkout page.
Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.
A custom description for the Session. This text will be displayed on the Xendit Hosted Checkout page.
Array of objects describing the item/s attached to the session.
Merchant provided identifier for the item
Type of item
Name of item
Net amount to be charged per unit
Number of units of this item in the basket
URL of the item. Must be HTTPS or HTTP
URL of the image of the item. Must be HTTPS or HTTP
Category for item
Sub-category for item
Description of item
Key-value entries for your custom data. You can specify up to 50 keys, with key names up to 40 characters and values up to 500 characters. This is for your convenience. Xendit will not use this data for any processing.
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"
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"
The status of the Payment Session.
The URL for Xendit Hosted Checkout page. Redirect your customer to this URL to complete the payment.
Xendit Payment Token ID used to reference the saved payment details from the customer.
Xendit Payment ID used to reference the captured payment details from the customer.
Xendit Payment Request ID used to reference the payment made during this Session.
Bad Request
Unauthorized
Not Found
Client Side Bad Request Error
Internal Server Error
Server Side Error