Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Get the status of a session

Prev Next
Get
/sessions/{session_id}

Returns the status of the Session and related payment references.

Security
HTTP
Type basic
Path parameters
session_id
stringRequired
Min length27
Max length27
Exampleps-661f87c614802d6c402cd82d
Responses
200

Session Found

getSessionResponseExample
{
  "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

A reference to uniquely identify the Payment Session.

Min length1
Max length64
customer_id
string

Xendit-generated Customer ID

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. AUTHORIZATION: authorize a card payment for a future capture. Only supported SAVE as session type for now.

Valid values[ "\"SAVE\"", "\"PAY\"", "\"AUTHORIZATION\"" ]
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. 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.

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
Example10000
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. COMPONENT: collect the payment details directly from the customer on your own page using Xendit Components. 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.

Valid values[ "\"PAYMENT_LINK\"", "\"COMPONENT\"", "\"CARDS_SESSION_JS\"" ]
channel_properties
object (Payment_Session_ChannelProperties)
cards
object (Payment_Session_ChannelPropertiesCards)
card_on_file_type
string

The type of “credential-on-file” / “card-on-file” / COF for future payments.

If you intend to use the card details for future COF transactions, you must be accurately indicate the card_on_file_type to allow Xendit to optimize the payment setup with the processor, which will help all future transactions using the same card details.

CUSTOMER_UNSCHEDULED: for future payments initiated by the customer that do not follow a schedule. For example, a simple “save card for future checkout” eCommerce flow, where the customer can use the saved card for future purchases any time.

MERCHANT_UNSCHEDULED: for future payments initiated without customer interaction and do not follow a schedule. For example, an auto top-up payment flow, where an application automatically collects payment when customer's balance is low.

RECURRING: for future payments initiated at fixed and regular intervals. For example, a subscription payment flow, where the customer is billed automatically every month.

For MERCHANT_UNSCHEDULED and RECURRING payments you are required to fill in the recurring_expiry and recurring_frequency inside the recurring_configuration. To process MERCHANT_UNSCHEDULED and RECURRING payments, there are some additional configuration required. For Aggregator Merchants, you need to be allowed to perform Recurring Payment you can enable this under https://dashboard.xendit.co/settings/payment-methods/cards-configuration. For Switcher Merchants, please check with your acquiring bank whether your MID allows non 3DS transactions and support recurring transactions by the acquirer.

Valid values[ "\"CUSTOMER_UNSCHEDULED\"", "\"MERCHANT_UNSCHEDULED\"", "\"RECURRING\"" ]
mid_label
string

For Switcher Merchants only. Specify the MID label to route the payment.

allowed_bins
Array of string

Specify the list of BINs that are allowed for the payment.

Example[ "411111", "510510" ]
string
skip_three_ds
boolean

Defaults to false. Specify if 3DS should be skipped for the payment.

recurring_configuration
object
recurring_expiry
string (date)

Specify the end date of the recurring charges or when the you will stop charging the stored payment token of the end user. It should be provided in a date format. For use cases like a lifetime membership, you can set the expiry date as far into the future as possible.

recurring_frequency
number

This parameter defines the interval between each charge date, measured in days. For example, for a monthly recurring charge, it's recommended to set the value to 28 days to cover the shortest month in the year. If a retry mechanism is in place (e.g., retrying the charge the next day), set the frequency to 1. For unscheduled merchant use cases, set the frequency to the nearest interval that matches the expected charge pattern.

statement_descriptor
string

Short descriptor that can be used as an identifier on the end user card statement. Subjected to support by issuers.

Min length5
Max length22
Pattern^[a-zA-Z0-9 ]+$
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
Valid values[ "\"CARDS\"", "\"BRI_DIRECT_DEBIT\"", "\"BCA_ONEKLIK\"", "\"CIMB_DIRECT_DEBIT\"", "\"BNI_AUTOPAY\"", "\"BPI_DIRECT_DEBIT\"", "\"UBP_DIRECT_DEBIT\"", "\"RCBC_DIRECT_DEBIT\"", "\"BDO_DIRECT_DEBIT\"", "\"CHINABANK_DIRECT_DEBIT\"", "\"MANDIRI_DIRECT_DEBIT\"", "\"BBL_DIRECT_DEBIT\"", "\"SCB_DIRECT_DEBIT\"", "\"KTB_DIRECT_DEBIT\"", "\"KRUNGSRI_DIRECT_DEBIT\"", "\"KBANK_MOBILE_BANKING\"", "\"KRUNGSRI_MOBILE_BANKING\"", "\"KTB_MOBILE_BANKING\"", "\"BBL_MOBILE_BANKING\"", "\"SCB_MOBILE_BANKING\"", "\"BDO_EPAY\"", "\"BPI_RECURRING\"", "\"UBP_EADA\"", "\"UBP_DEBIT_PULL\"", "\"AFFIN_FPX\"", "\"AGRO_FPX\"", "\"ALLIANCE_FPX\"", "\"AMBANK_FPX\"", "\"ISLAM_FPX\"", "\"MUAMALAT_FPX\"", "\"BOC_FPX\"", "\"RAKYAT_FPX\"", "\"BSN_FPX\"", "\"CIMB_FPX\"", "\"HLB_FPX\"", "\"HSBC_FPX\"", "\"KFH_FPX\"", "\"MAYB2E_FPX\"", "\"MAYB2U_FPX\"", "\"OCBC_FPX\"", "\"PUBLIC_FPX\"", "\"RHB_FPX\"", "\"SCH_FPX\"", "\"UOB_FPX\"", "\"AFFIN_FPX_BUSINESS\"", "\"AGRO_FPX_BUSINESS\"", "\"ALLIANCE_FPX_BUSINESS\"", "\"AMBANK_FPX_BUSINESS\"", "\"ISLAM_FPX_BUSINESS\"", "\"MUAMALAT_FPX_BUSINESS\"", "\"BNP_FPX_BUSINESS\"", "\"CIMB_FPX_BUSINESS\"", "\"CITIBANK_FPX_BUSINESS\"", "\"DEUTSCHE_FPX_BUSINESS\"", "\"HLB_FPX_BUSINESS\"", "\"HSBC_FPX_BUSINESS\"", "\"RAKYAT_FPX_BUSINESS\"", "\"KFH_FPX_BUSINESS\"", "\"MAYB2E_FPX_BUSINESS\"", "\"OCBC_FPX_BUSINESS\"", "\"PUBLIC_FPX_BUSINESS\"", "\"RHB_FPX_BUSINESS\"", "\"SCH_FPX_BUSINESS\"", "\"UOB_FPX_BUSINESS\"", "\"BCA_KLIKPAY\"", "\"BDO_ONLINE_BANKING\"", "\"BPI_ONLINE_BANKING\"", "\"UNIONBANK_ONLINE_BANKING\"", "\"BOC_ONLINE_BANKING\"", "\"CHINABANK_ONLINE_BANKING\"", "\"INSTAPAY_ONLINE_BANKING\"", "\"LANDBANK_ONLINE_BANKING\"", "\"MAYBANK_ONLINE_BANKING\"", "\"METROBANK_ONLINE_BANKING\"", "\"PNB_ONLINE_BANKING\"", "\"PSBANK_ONLINE_BANKING\"", "\"PESONET_ONLINE_BANKING\"", "\"RCBC_ONLINE_BANKING\"", "\"ROBINSONS_BANK_ONLINE_BANKING\"", "\"SECURITY_BANK_ONLINE_BANKING\"", "\"GRABPAY\"", "\"PAYMAYA\"", "\"GCASH\"", "\"OVO\"", "\"DANA\"", "\"LINKAJA\"", "\"SHOPEEPAY\"", "\"SAKUKU\"", "\"NEXCASH\"", "\"ASTRAPAY\"", "\"JENIUSPAY\"", "\"APPOTA\"", "\"MOMO\"", "\"VNPTWALLET\"", "\"VIETTELPAY\"", "\"ZALOPAY\"", "\"WECHATPAY\"", "\"LINEPAY\"", "\"TRUEMONEY\"", "\"ALIPAY\"", "\"TOUCHNGO\"" ]
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. 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.

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
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_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
400

Bad Request

object
error_code
string
ExampleAPI_VALIDATION_ERROR
message
string
errors
Array
OneOf
string
string
object
object
401

Unauthorized

object
error_code
string
ExampleINVALID_API_KEY
message
string
errors
Array
OneOf
string
string
object
object
403

Forbidden

object
error_code
string
ExampleINELIGIBLE_SESSION_REQUEST
message
string
errors
Array
OneOf
string
string
object
object
404

Not Found

object
error_code
string
ExampleCUSTOMER_NOT_FOUND, SESSION_NOT_FOUND
message
string
errors
Array
OneOf
string
string
object
object
4XX

Client Side Bad Request Error

500

Internal Server Error

object
error_code
string
ExampleSERVER_ERROR
message
string
errors
Array
OneOf
string
string
object
object
5XX

Server Side Error