Update a checkout session
Updates configurable fields on an existing checkout session such as redirect URLs, 3DS requirement, customer details, metadata, and available payment methods.
Note: this operation is served under the /api/v1/checkout-session basepath
(see the operation’s server URL), unlike the session create/read operations.
curl --request PATCH \
--url https://api.lite.sa/api/v1/checkout-session/{session_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"three_ds_required": true,
"processing_type": "REGULAR",
"customer": {
"name": "John Doe",
"email": "john@example.com",
"phone": "+966555123456"
},
"metadata": {
"session_type": "standard"
},
"payment_methods": [
"card"
]
}
'import requests
url = "https://api.lite.sa/api/v1/checkout-session/{session_id}"
payload = {
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"three_ds_required": True,
"processing_type": "REGULAR",
"customer": {
"name": "John Doe",
"email": "john@example.com",
"phone": "+966555123456"
},
"metadata": { "session_type": "standard" },
"payment_methods": ["card"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
three_ds_required: true,
processing_type: 'REGULAR',
customer: {name: 'John Doe', email: 'john@example.com', phone: '+966555123456'},
metadata: {session_type: 'standard'},
payment_methods: ['card']
})
};
fetch('https://api.lite.sa/api/v1/checkout-session/{session_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
three_ds_required: true,
processing_type: 'REGULAR',
customer: {name: 'John Doe', email: 'john@example.com', phone: '+966555123456'},
metadata: {session_type: 'standard'},
payment_methods: ['card']
})
};
fetch('https://api.lite.sa/api/v1/checkout-session/{session_id}', 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-session/{session_id}"
payload := strings.NewReader("{\n \"redirect_urls\": {\n \"success\": \"https://example.com/success\",\n \"failure\": \"https://example.com/failure\"\n },\n \"three_ds_required\": true,\n \"processing_type\": \"REGULAR\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"phone\": \"+966555123456\"\n },\n \"metadata\": {\n \"session_type\": \"standard\"\n },\n \"payment_methods\": [\n \"card\"\n ]\n}")
req, _ := http.NewRequest("PATCH", 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-session/{session_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'redirect_urls' => [
'success' => 'https://example.com/success',
'failure' => 'https://example.com/failure'
],
'three_ds_required' => true,
'processing_type' => 'REGULAR',
'customer' => [
'name' => 'John Doe',
'email' => 'john@example.com',
'phone' => '+966555123456'
],
'metadata' => [
'session_type' => 'standard'
],
'payment_methods' => [
'card'
]
]),
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"
}
}{
"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"
Path Parameters
Unique identifier of the checkout session
"550e8400-e29b-41d4-a716-446655440000"
Body
Update an existing checkout session
Request body for updating a checkout session
Redirect URLs for checkout session
Show child attributes
Show child attributes
Whether 3DS authentication is required
true
Standard one-time payment
"REGULAR""REGULAR"
Customer details to update
Show child attributes
Show child attributes
Additional metadata
{ "session_type": "standard" }
Allowed payment methods
Credit or debit card
"card"Response
Checkout session updated.
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 PATCH \
--url https://api.lite.sa/api/v1/checkout-session/{session_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"three_ds_required": true,
"processing_type": "REGULAR",
"customer": {
"name": "John Doe",
"email": "john@example.com",
"phone": "+966555123456"
},
"metadata": {
"session_type": "standard"
},
"payment_methods": [
"card"
]
}
'import requests
url = "https://api.lite.sa/api/v1/checkout-session/{session_id}"
payload = {
"redirect_urls": {
"success": "https://example.com/success",
"failure": "https://example.com/failure"
},
"three_ds_required": True,
"processing_type": "REGULAR",
"customer": {
"name": "John Doe",
"email": "john@example.com",
"phone": "+966555123456"
},
"metadata": { "session_type": "standard" },
"payment_methods": ["card"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
three_ds_required: true,
processing_type: 'REGULAR',
customer: {name: 'John Doe', email: 'john@example.com', phone: '+966555123456'},
metadata: {session_type: 'standard'},
payment_methods: ['card']
})
};
fetch('https://api.lite.sa/api/v1/checkout-session/{session_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
redirect_urls: {success: 'https://example.com/success', failure: 'https://example.com/failure'},
three_ds_required: true,
processing_type: 'REGULAR',
customer: {name: 'John Doe', email: 'john@example.com', phone: '+966555123456'},
metadata: {session_type: 'standard'},
payment_methods: ['card']
})
};
fetch('https://api.lite.sa/api/v1/checkout-session/{session_id}', 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-session/{session_id}"
payload := strings.NewReader("{\n \"redirect_urls\": {\n \"success\": \"https://example.com/success\",\n \"failure\": \"https://example.com/failure\"\n },\n \"three_ds_required\": true,\n \"processing_type\": \"REGULAR\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"phone\": \"+966555123456\"\n },\n \"metadata\": {\n \"session_type\": \"standard\"\n },\n \"payment_methods\": [\n \"card\"\n ]\n}")
req, _ := http.NewRequest("PATCH", 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-session/{session_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'redirect_urls' => [
'success' => 'https://example.com/success',
'failure' => 'https://example.com/failure'
],
'three_ds_required' => true,
'processing_type' => 'REGULAR',
'customer' => [
'name' => 'John Doe',
'email' => 'john@example.com',
'phone' => '+966555123456'
],
'metadata' => [
'session_type' => 'standard'
],
'payment_methods' => [
'card'
]
]),
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"
}
}{
"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"
}
}