Create an authentication session
Start a new 3DS authentication session to authenticate a payer. The session is accepted for asynchronous processing; poll the session resource for the authentication outcome.
POST
https://api.lite.sa
/
threeds
/
authenticate
Create an authentication session
curl --request POST \
--url https://api.lite.sa/threeds/authenticate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"instrument_id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
"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"
},
"return_url": "https://example.com/threeds/callback"
}
'import requests
url = "https://api.lite.sa/threeds/authenticate"
payload = {
"instrument_id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
"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"
},
"return_url": "https://example.com/threeds/callback"
}
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({
instrument_id: 'baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5',
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'
},
return_url: 'https://example.com/threeds/callback'
})
};
fetch('https://api.lite.sa/threeds/authenticate', 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({
instrument_id: 'baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5',
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'
},
return_url: 'https://example.com/threeds/callback'
})
};
fetch('https://api.lite.sa/threeds/authenticate', 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/threeds/authenticate"
payload := strings.NewReader("{\n \"instrument_id\": \"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5\",\n \"customer\": {\n \"id\": \"cust_a1b2c3d4e5f6\",\n \"email\": \"john.doe@email.com\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"phone_country_code\": \"+966\",\n \"phone_number\": \"555123456\"\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 \"return_url\": \"https://example.com/threeds/callback\"\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/threeds/authenticate",
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([
'instrument_id' => 'baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5',
'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'
],
'return_url' => 'https://example.com/threeds/callback'
]),
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;
}{
"threeds": {
"id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
"status": "PENDING"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlation_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": {},
"correlation_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": {},
"correlation_id": "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.
Example:
"550e8400-e29b-41d4-a716-446655440000"
Unique key for idempotent request processing. Duplicate requests with the same key are safely ignored.
Example:
"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5"
Body
application/json
Create a new 3DS authentication session
Instrument ID
Example:
"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5"
Customer details
Show child attributes
Show child attributes
Order details
Show child attributes
Show child attributes
Return URL for 3DS challenge completion
Example:
"https://example.com/threeds/callback"
Device information (required for 3DS and risk assessment)
Show child attributes
Show child attributes
3DS provider. If not provided, the default provider is used.
Available options:
mpgs-threeds Example:
"mpgs-threeds"
Response
Authentication session accepted for processing.
Show child attributes
Show child attributes
⌘I
Create an authentication session
curl --request POST \
--url https://api.lite.sa/threeds/authenticate \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"instrument_id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
"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"
},
"return_url": "https://example.com/threeds/callback"
}
'import requests
url = "https://api.lite.sa/threeds/authenticate"
payload = {
"instrument_id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
"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"
},
"return_url": "https://example.com/threeds/callback"
}
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({
instrument_id: 'baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5',
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'
},
return_url: 'https://example.com/threeds/callback'
})
};
fetch('https://api.lite.sa/threeds/authenticate', 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({
instrument_id: 'baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5',
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'
},
return_url: 'https://example.com/threeds/callback'
})
};
fetch('https://api.lite.sa/threeds/authenticate', 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/threeds/authenticate"
payload := strings.NewReader("{\n \"instrument_id\": \"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5\",\n \"customer\": {\n \"id\": \"cust_a1b2c3d4e5f6\",\n \"email\": \"john.doe@email.com\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"phone_country_code\": \"+966\",\n \"phone_number\": \"555123456\"\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 \"return_url\": \"https://example.com/threeds/callback\"\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/threeds/authenticate",
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([
'instrument_id' => 'baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5',
'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'
],
'return_url' => 'https://example.com/threeds/callback'
]),
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;
}{
"threeds": {
"id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
"status": "PENDING"
}
}{
"error": {
"code": "PAYMENT_DETAILS_MISMATCH",
"message": "The request was invalid or malformed",
"timestamp": "2024-12-16T10:30:00.000Z",
"details": {},
"correlation_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": {},
"correlation_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": {},
"correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}
}