Skip to main content
POST
Create Checkout Session

Authorizations

Authorization
string
header
required

Bearer API Key authentication. Format: Authorization: Bearer {your_api_key}

Headers

Request-Id
string
default:008e3967-a1b5-48bb-be14-d5bff5092e61
required

The unique identifier of the request

Body

application/json

Create checkout session request

order_id
string
required

Third-party order number

line_items
object[]
required

Product pricing array included in this checkout (currently only supports one lineItem)

customer_id
string

Subotiz platform customer unique identifier, must be created in Subotiz in advance. One of payer_id, customer_id and email must exist

email
string

Customer email

return_url
string

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.

cancel_url
string

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.

mode
string

Payment mode, used to determine whether to validate product information:

  • checkout: Validate product data, default value
  • payment: Do not validate product data
payer_id
string

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_method
string

Integration mode:

  • hosted: Hosted, default mode
  • embedded: Embedded integration
total_amount
string

Payment amount, required when mode is set to payment mode.

redirect_on_completion
string

Redirect behavior for embedded UI mode

  • always: Automatically redirect to return_url after successful payment
  • if_required: Only redirect to return_url for payment methods that require redirection
locale
string

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)
target_currency
string

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.

merchant_rate
string

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.

metadata
object

A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format.

subscription_data
object

A subset of parameters to be passed to subscription creation for Checkout Sessions in

trade_data
object

A subset of parameters to be passed to trade creation for Checkout Sessions in

source_channel
string

First transaction source channel identification, used for transaction attribution statistics, length limit 50

billing_address_data
object

Billing address information

payment_mode
string

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.
once_trial
integer<int32>

Whether to enable once free trial period for the trial price.

  • 1: no trial limit
  • 2: once trial
  • 3: skip trial period
fixed_term
integer<int32>

Fixed-term subscription length (positive integer)

is_renewable
boolean

Whether the fixed-term subscription can be converted to a continuous subscription

Response

200 - application/json

OK

code
string

error code

message
string

error message

data
object