Create a checkout session
Creates a new hosted checkout session and returns a payment link and client secret for use in the frontend SDK.
curl --request POST \
--url https://api.lite.sa/api/v1/checkout/sessions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 10000,
"currency": "SAR",
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"order": {
"reference": "ORD-123456",
"items": {
"products": [
{
"id": "prod_123",
"price": 5000,
"quantity": 2,
"name": "T-Shirt",
"metadata": {
"color": "Blue",
"size": "L"
}
}
],
"vat": {
"amount": 750
},
"shipping": {
"amount": 1000
}
},
"shipping_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"billing_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"amount": 10000,
"currency": "SAR",
"description": "Order description"
}
}
'import requests
url = "https://api.lite.sa/api/v1/checkout/sessions"
payload = {
"amount": 10000,
"currency": "SAR",
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"order": {
"reference": "ORD-123456",
"items": {
"products": [
{
"id": "prod_123",
"price": 5000,
"quantity": 2,
"name": "T-Shirt",
"metadata": {
"color": "Blue",
"size": "L"
}
}
],
"vat": { "amount": 750 },
"shipping": { "amount": 1000 }
},
"shipping_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"billing_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"amount": 10000,
"currency": "SAR",
"description": "Order description"
}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 10000,
currency: 'SAR',
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
order: {
reference: 'ORD-123456',
items: {
products: [
{
id: 'prod_123',
price: 5000,
quantity: 2,
name: 'T-Shirt',
metadata: {color: 'Blue', size: 'L'}
}
],
vat: {amount: 750},
shipping: {amount: 1000}
},
shipping_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
billing_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
amount: 10000,
currency: 'SAR',
description: 'Order description'
}
})
};
fetch('https://api.lite.sa/api/v1/checkout/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 10000,
currency: 'SAR',
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
order: {
reference: 'ORD-123456',
items: {
products: [
{
id: 'prod_123',
price: 5000,
quantity: 2,
name: 'T-Shirt',
metadata: {color: 'Blue', size: 'L'}
}
],
vat: {amount: 750},
shipping: {amount: 1000}
},
shipping_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
billing_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
amount: 10000,
currency: 'SAR',
description: 'Order description'
}
})
};
fetch('https://api.lite.sa/api/v1/checkout/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.lite.sa/api/v1/checkout/sessions"
payload := strings.NewReader("{\n \"amount\": 10000,\n \"currency\": \"SAR\",\n \"redirect_urls\": {\n \"success\": \"https://example.com/success\",\n \"failure\": \"https://example.com/failure\"\n },\n \"order\": {\n \"reference\": \"ORD-123456\",\n \"items\": {\n \"products\": [\n {\n \"id\": \"prod_123\",\n \"price\": 5000,\n \"quantity\": 2,\n \"name\": \"T-Shirt\",\n \"metadata\": {\n \"color\": \"Blue\",\n \"size\": \"L\"\n }\n }\n ],\n \"vat\": {\n \"amount\": 750\n },\n \"shipping\": {\n \"amount\": 1000\n }\n },\n \"shipping_address\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"street\": \"123 Main St\",\n \"city\": \"Riyadh\",\n \"state\": \"Riyadh Region\",\n \"zip\": \"12213\",\n \"country\": \"SA\"\n },\n \"billing_address\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"street\": \"123 Main St\",\n \"city\": \"Riyadh\",\n \"state\": \"Riyadh Region\",\n \"zip\": \"12213\",\n \"country\": \"SA\"\n },\n \"amount\": 10000,\n \"currency\": \"SAR\",\n \"description\": \"Order description\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lite.sa/api/v1/checkout/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 10000,
'currency' => 'SAR',
'redirect_urls' => [
'success' => 'https://example.com/success',
'failure' => 'https://example.com/failure'
],
'order' => [
'reference' => 'ORD-123456',
'items' => [
'products' => [
[
'id' => 'prod_123',
'price' => 5000,
'quantity' => 2,
'name' => 'T-Shirt',
'metadata' => [
'color' => 'Blue',
'size' => 'L'
]
]
],
'vat' => [
'amount' => 750
],
'shipping' => [
'amount' => 1000
]
],
'shipping_address' => [
'name' => 'John Doe',
'email' => 'john@example.com',
'street' => '123 Main St',
'city' => 'Riyadh',
'state' => 'Riyadh Region',
'zip' => '12213',
'country' => 'SA'
],
'billing_address' => [
'name' => 'John Doe',
'email' => 'john@example.com',
'street' => '123 Main St',
'city' => 'Riyadh',
'state' => 'Riyadh Region',
'zip' => '12213',
'country' => 'SA'
],
'amount' => 10000,
'currency' => 'SAR',
'description' => 'Order description'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"hosted_url": "https://checkout.lite.sa/ses_a1b2c3d4e5f6",
"client_secret": "cs_a1b2c3d4e5f6",
"status": "Pending",
"expires_on": "2026-05-18T12:00:00.000Z",
"order_id": "ORD-123456",
"amount": 10000,
"currency": "SAR",
"customer": {
"id": "cust_a1b2c3d4e5f6",
"email": "john.doe@email.com",
"first_name": "John",
"last_name": "Doe",
"phone_country_code": "+966",
"phone_number": "555123456"
},
"order": {
"reference": "ORD-123456",
"items": {
"products": [
{
"id": "prod_123",
"price": 5000,
"quantity": 2,
"name": "T-Shirt",
"metadata": {
"color": "Blue",
"size": "L"
}
}
],
"vat": {
"amount": 750
},
"shipping": {
"amount": 1000
}
},
"shipping_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"billing_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"amount": 10000,
"currency": "SAR",
"description": "Order description"
},
"channel_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}Authorizations
API key for service-to-service or merchant authentication.
Headers
Unique identifier for request tracing. Generated by the client or server if not provided.
"550e8400-e29b-41d4-a716-446655440000"
Unique key for idempotent request processing. Duplicate requests with the same key are safely ignored.
"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5"
The unique identifier of the target business account. This is applicable for platform use cases.
"550e8400-e29b-41d4-a716-446655440000"
Body
Create a new hosted checkout session
Request body for creating a new checkout session
Payment amount in minor units (e.g. 10000 for 100.00 SAR)
x >= 110000
Currency code (ISO 4217)
"SAR"
Redirect URLs for checkout session
Show child attributes
Show child attributes
Order details
Show child attributes
Show child attributes
Customer details for checkout session creation. When provided, id is required.
Show child attributes
Show child attributes
Session expiry in seconds (default 3600)
60 <= x <= 864001800
Whether 3DS authentication is required
true
Standard one-time payment
"REGULAR""REGULAR"
Additional metadata
{ "session_type": "standard" }
Channel ID for the session
"550e8400-e29b-41d4-a716-446655440000"
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.
Show child attributes
Show child attributes
Response
Checkout session created successfully.
Response returned after creating or updating a checkout session
Unique checkout session identifier
"550e8400-e29b-41d4-a716-446655440000"
Deprecated alias of id. Use id instead.
"550e8400-e29b-41d4-a716-446655440000"
URL for the hosted checkout page
"https://checkout.lite.sa/ses_a1b2c3d4e5f6"
Client secret for frontend SDK authentication
"cs_a1b2c3d4e5f6"
Session is active and awaiting payment
"Pending""Pending"
Session expiry timestamp
"2026-05-18T12:00:00.000Z"
Order reference
"ORD-123456"
Session amount in minor units
10000
Currency code (ISO 4217)
"SAR"
Customer details
Show child attributes
Show child attributes
Order details
Show child attributes
Show child attributes
Channel ID for the session
"550e8400-e29b-41d4-a716-446655440000"
curl --request POST \
--url https://api.lite.sa/api/v1/checkout/sessions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 10000,
"currency": "SAR",
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"order": {
"reference": "ORD-123456",
"items": {
"products": [
{
"id": "prod_123",
"price": 5000,
"quantity": 2,
"name": "T-Shirt",
"metadata": {
"color": "Blue",
"size": "L"
}
}
],
"vat": {
"amount": 750
},
"shipping": {
"amount": 1000
}
},
"shipping_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"billing_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"amount": 10000,
"currency": "SAR",
"description": "Order description"
}
}
'import requests
url = "https://api.lite.sa/api/v1/checkout/sessions"
payload = {
"amount": 10000,
"currency": "SAR",
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"order": {
"reference": "ORD-123456",
"items": {
"products": [
{
"id": "prod_123",
"price": 5000,
"quantity": 2,
"name": "T-Shirt",
"metadata": {
"color": "Blue",
"size": "L"
}
}
],
"vat": { "amount": 750 },
"shipping": { "amount": 1000 }
},
"shipping_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"billing_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"amount": 10000,
"currency": "SAR",
"description": "Order description"
}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 10000,
currency: 'SAR',
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
order: {
reference: 'ORD-123456',
items: {
products: [
{
id: 'prod_123',
price: 5000,
quantity: 2,
name: 'T-Shirt',
metadata: {color: 'Blue', size: 'L'}
}
],
vat: {amount: 750},
shipping: {amount: 1000}
},
shipping_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
billing_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
amount: 10000,
currency: 'SAR',
description: 'Order description'
}
})
};
fetch('https://api.lite.sa/api/v1/checkout/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 10000,
currency: 'SAR',
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
order: {
reference: 'ORD-123456',
items: {
products: [
{
id: 'prod_123',
price: 5000,
quantity: 2,
name: 'T-Shirt',
metadata: {color: 'Blue', size: 'L'}
}
],
vat: {amount: 750},
shipping: {amount: 1000}
},
shipping_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
billing_address: {
name: 'John Doe',
email: 'john@example.com',
street: '123 Main St',
city: 'Riyadh',
state: 'Riyadh Region',
zip: '12213',
country: 'SA'
},
amount: 10000,
currency: 'SAR',
description: 'Order description'
}
})
};
fetch('https://api.lite.sa/api/v1/checkout/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.lite.sa/api/v1/checkout/sessions"
payload := strings.NewReader("{\n \"amount\": 10000,\n \"currency\": \"SAR\",\n \"redirect_urls\": {\n \"success\": \"https://example.com/success\",\n \"failure\": \"https://example.com/failure\"\n },\n \"order\": {\n \"reference\": \"ORD-123456\",\n \"items\": {\n \"products\": [\n {\n \"id\": \"prod_123\",\n \"price\": 5000,\n \"quantity\": 2,\n \"name\": \"T-Shirt\",\n \"metadata\": {\n \"color\": \"Blue\",\n \"size\": \"L\"\n }\n }\n ],\n \"vat\": {\n \"amount\": 750\n },\n \"shipping\": {\n \"amount\": 1000\n }\n },\n \"shipping_address\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"street\": \"123 Main St\",\n \"city\": \"Riyadh\",\n \"state\": \"Riyadh Region\",\n \"zip\": \"12213\",\n \"country\": \"SA\"\n },\n \"billing_address\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"street\": \"123 Main St\",\n \"city\": \"Riyadh\",\n \"state\": \"Riyadh Region\",\n \"zip\": \"12213\",\n \"country\": \"SA\"\n },\n \"amount\": 10000,\n \"currency\": \"SAR\",\n \"description\": \"Order description\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.lite.sa/api/v1/checkout/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 10000,
'currency' => 'SAR',
'redirect_urls' => [
'success' => 'https://example.com/success',
'failure' => 'https://example.com/failure'
],
'order' => [
'reference' => 'ORD-123456',
'items' => [
'products' => [
[
'id' => 'prod_123',
'price' => 5000,
'quantity' => 2,
'name' => 'T-Shirt',
'metadata' => [
'color' => 'Blue',
'size' => 'L'
]
]
],
'vat' => [
'amount' => 750
],
'shipping' => [
'amount' => 1000
]
],
'shipping_address' => [
'name' => 'John Doe',
'email' => 'john@example.com',
'street' => '123 Main St',
'city' => 'Riyadh',
'state' => 'Riyadh Region',
'zip' => '12213',
'country' => 'SA'
],
'billing_address' => [
'name' => 'John Doe',
'email' => 'john@example.com',
'street' => '123 Main St',
'city' => 'Riyadh',
'state' => 'Riyadh Region',
'zip' => '12213',
'country' => 'SA'
],
'amount' => 10000,
'currency' => 'SAR',
'description' => 'Order description'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"hosted_url": "https://checkout.lite.sa/ses_a1b2c3d4e5f6",
"client_secret": "cs_a1b2c3d4e5f6",
"status": "Pending",
"expires_on": "2026-05-18T12:00:00.000Z",
"order_id": "ORD-123456",
"amount": 10000,
"currency": "SAR",
"customer": {
"id": "cust_a1b2c3d4e5f6",
"email": "john.doe@email.com",
"first_name": "John",
"last_name": "Doe",
"phone_country_code": "+966",
"phone_number": "555123456"
},
"order": {
"reference": "ORD-123456",
"items": {
"products": [
{
"id": "prod_123",
"price": 5000,
"quantity": 2,
"name": "T-Shirt",
"metadata": {
"color": "Blue",
"size": "L"
}
}
],
"vat": {
"amount": 750
},
"shipping": {
"amount": 1000
}
},
"shipping_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"billing_address": {
"name": "John Doe",
"email": "john@example.com",
"street": "123 Main St",
"city": "Riyadh",
"state": "Riyadh Region",
"zip": "12213",
"country": "SA"
},
"amount": 10000,
"currency": "SAR",
"description": "Order description"
},
"channel_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
}