Skip to main content
POST
Create a checkout session

Authorizations

x-api-key
string
header
required

API key for service-to-service or merchant authentication.

Headers

x-correlation-id
string<uuid>

Unique identifier for request tracing. Generated by the client or server if not provided.

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key
string<uuid>

Unique key for idempotent request processing. Duplicate requests with the same key are safely ignored.

Example:

"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5"

x-business-account-id
string

The unique identifier of the target business account. This is applicable for platform use cases.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

Create a new hosted checkout session

Request body for creating a new checkout session

amount
integer
required

Payment amount in minor units (e.g. 10000 for 100.00 SAR)

Required range: x >= 1
Example:

10000

currency
string
required

Currency code (ISO 4217)

Example:

"SAR"

redirect_urls
object
required

Redirect URLs for checkout session

order
object
required

Order details

customer
object

Customer details for checkout session creation. When provided, id is required.

expiry
integer

Session expiry in seconds (default 3600)

Required range: 60 <= x <= 86400
Example:

1800

three_ds_required
boolean

Whether 3DS authentication is required

Example:

true

processing_type
default:REGULAR

Standard one-time payment

Allowed value: "REGULAR"
Example:

"REGULAR"

metadata
object

Additional metadata

Example:
channel_id
string<uuid>

Channel ID for the session

Example:

"550e8400-e29b-41d4-a716-446655440000"

splits
object[]

Specifies secondary destinations for payment routing. The total payment always lands in the main acceptance account first; the amounts specified in this array are then deducted and transferred to the secondary accounts, with the remainder staying in the main account.

Response

Checkout session created successfully.

Response returned after creating or updating a checkout session

id
string<uuid>
required

Unique checkout session identifier

Example:

"550e8400-e29b-41d4-a716-446655440000"

session_id
string
required
deprecated

Deprecated alias of id. Use id instead.

Example:

"550e8400-e29b-41d4-a716-446655440000"

hosted_url
string<uri>
required

URL for the hosted checkout page

Example:

"https://checkout.lite.sa/ses_a1b2c3d4e5f6"

client_secret
string
required

Client secret for frontend SDK authentication

Example:

"cs_a1b2c3d4e5f6"

status
required

Session is active and awaiting payment

Allowed value: "Pending"
Example:

"Pending"

expires_on
string<date-time>
required

Session expiry timestamp

Example:

"2026-05-18T12:00:00.000Z"

order_id
string
required

Order reference

Example:

"ORD-123456"

amount
integer
required

Session amount in minor units

Example:

10000

currency
string
required

Currency code (ISO 4217)

Example:

"SAR"

customer
object

Customer details

order
object

Order details

channel_id
string

Channel ID for the session

Example:

"550e8400-e29b-41d4-a716-446655440000"