Create Checkout Session
Create Checkout Session
Authorizations
Bearer API Key authentication. Format: Authorization: Bearer {your_api_key}
Headers
The unique identifier of the request
Body
Create checkout session request
Third-party order number
Product pricing array included in this checkout (currently only supports one lineItem)
Subotiz platform customer unique identifier, must be created in Subotiz in advance. One of payer_id, customer_id and email must exist
Customer email
URL to redirect to after customer payment success. The explicitly provided URL is used first; otherwise, the default from the developer settings is applied automatically.
URL to redirect to after customer cancels payment. The explicitly provided URL is used first; otherwise, the default from the developer settings is applied automatically.
Payment mode, used to determine whether to validate product information:
- checkout: Validate product data, default value
- payment: Do not validate product data
Third-party customer ID, if the passed ID does not exist in the Subotiz system, a customer will be automatically created. Each payer_id under each merchant is unique.
Integration mode:
- hosted: Hosted, default mode
- embedded: Embedded integration
Payment amount, required when mode is set to payment mode.
Redirect behavior for embedded UI mode
- always: Automatically redirect to
return_urlafter successful payment - if_required: Only redirect to
return_urlfor payment methods that require redirection
Specify the language for the checkout session. The default language is determined based on the browser language. Optional Values:
- ar-SA:Arabic (Saudi Arabia)
- de-DE:German (Germany)
- en-US:English (United States)
- es-ES:Spanish (Spain)
- fr-FR:French (France)
- id-ID:Indonesian (Indonesia)
- it-IT:Italian (Italy)
- ja-JP:Japanese (Japan)
- ko-KR:Korean (South Korea)
- nl-NL:Dutch (Netherlands)
- pl-PL:Polish (Poland)
- pt-PT:Portuguese (Portugal)
- ru-RU:Russian (Russia)
- th-TH:Thai (Thailand)
- zh-CN:Chinese (Mainland China)
- zh-TW:Chinese (Taiwan, China)
Specifies the settlement currency for the Checkout Session using a platform-supported ISO 4217 currency code, such as USD or CNY. The system uses the store's primary currency as the base currency and converts the order amount into this currency for display and pricing. If merchant_rate is not provided, the system uses the real-time exchange rate of the day by default.
Specifies a custom exchange rate from the store's primary currency to target_currency. The value must be a number greater than 0 and must be provided together with target_currency. This field is used only when the settlement currency differs from the store's primary currency. The exchange rate direction is: "1 unit of the store's primary currency = X units of target_currency". For example, if the store's primary currency is USD and target_currency is CNY, a value of 7.999 means 1 USD = 7.999 CNY, and the system will calculate the order amount using this rate.
A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format.
A subset of parameters to be passed to subscription creation for Checkout Sessions in
A subset of parameters to be passed to trade creation for Checkout Sessions in
First transaction source channel identification, used for transaction attribution statistics, length limit 50
Billing address information
Payment business mode:
onetime_payment: One-time payment mode. Processes a single payment transaction without creating any recurring payment tokens.subscription: Subscription payment mode. Processes the initial payment and generates a payment token for automatic recurring payments. Subsequent renewal charges will be processed using this token based on the subscription plan configuration.
Whether to enable once free trial period for the trial price.
- 1: no trial limit
- 2: once trial
- 3: skip trial period
Fixed-term subscription length (positive integer)
Whether the fixed-term subscription can be converted to a continuous subscription