Create a payment link

Creates a shareable payment link and returns its hostedUrl. Send a customer to that URL and they are redirected to a hosted checkout page for the link’s amount and currency.

Set merchant_reference_id to guard against duplicates: the reference is unique per merchant, so a retried create is rejected with 409 instead of issuing a second link for the same order. This is duplicate prevention, not idempotency — the 409 does not return the originally created link, so a caller that retries should treat it as “already exists” and look the link up via the list endpoint.

POST

https://api.lite.sa/api/v1

payment-links

Create a payment link

curl --request POST \
  --url https://api.lite.sa/api/v1/payment-links \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "mode": "SINGLE_USE",
  "amount": 10000,
  "currency": "SAR"
}
'

import requests

url = "https://api.lite.sa/api/v1/payment-links"

payload = {
    "mode": "SINGLE_USE",
    "amount": 10000,
    "currency": "SAR"
}
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({mode: 'SINGLE_USE', amount: 10000, currency: 'SAR'})
};

fetch('https://api.lite.sa/api/v1/payment-links', 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({mode: 'SINGLE_USE', amount: 10000, currency: 'SAR'})
};

fetch('https://api.lite.sa/api/v1/payment-links', 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/payment-links"

	payload := strings.NewReader("{\n  \"mode\": \"SINGLE_USE\",\n  \"amount\": 10000,\n  \"currency\": \"SAR\"\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/payment-links",
  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([
    'mode' => 'SINGLE_USE',
    'amount' => 10000,
    'currency' => 'SAR'
  ]),
  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",
  "publicToken": "plive_7c9f2a1b8e4d6035",
  "hostedUrl": "https://pay.lite.sa/pay/plive_7c9f2a1b8e4d6035",
  "merchantId": "7f3c8b21-0d4e-4a92-9f65-2b8e1c7a4d30",
  "mode": "SINGLE_USE",
  "status": "ACTIVE",
  "amount": 10000,
  "currency": "SAR",
  "usedCount": 2,
  "paidCount": 2,
  "failedCount": 1,
  "createdAt": "2026-06-01T10:30:00.000Z",
  "updatedAt": "2026-06-04T09:12:44.000Z",
  "merchantReferenceId": "order-2026-0042",
  "redirectUrls": {
    "success": "https://merchant.example.com/success",
    "failure": "https://merchant.example.com/failure"
  },
  "threeDsRequired": true,
  "description": "Invoice",
  "customer": {
    "id": "cus_8f1e2a4b",
    "firstName": "Sara",
    "lastName": "Al-Harbi",
    "email": "sara@example.com",
    "phoneCountryCode": "+966",
    "phoneNumber": "512345678",
    "billingAddress": {
      "line1": "123 High St.",
      "line2": "Apartment 5B",
      "city": "Riyadh",
      "state": "Riyadh Province",
      "postalCode": "11564",
      "country": "SA"
    }
  },
  "metadata": {
    "invoice_id": "INV-4471",
    "sales_rep": "rep_88"
  },
  "channelId": "3d1f9c60-5a72-4e18-b0c4-9a6d2f5e7b13",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "maxUses": 1,
  "lastPaidAt": "2026-06-04T09:12:44.000Z"
}

{
  "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

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"

Body

application/json

Request body for creating a payment link.

mode and max_uses must be coherent: a SINGLE_USE link is paid exactly once, so max_uses must be omitted or sent as exactly 1. Any other value is rejected with 400.

mode

enum<string>

required

How many times the link may be paid.

SINGLE_USE — exactly one successful payment. The link is promoted to PAID as soon as a payment reaches a terminal successful status.

Available options:

SINGLE_USE

Example:

"SINGLE_USE"

amount

integer

required

Amount in the currency's minor units (e.g. 10000 = 100.00 SAR)

Required range: x >= 1

Example:

10000

currency

string

required

ISO 4217 currency code

Example:

"SAR"

merchant_reference_id

string

Merchant-supplied reference, unique per merchant. Guards against duplicate links: a second create with the same value is rejected with 409 rather than issuing a second link for the same order.

Note this is duplicate prevention, not idempotency — a retry does not return the originally created link, and a 409 here is only ever raised when this field is sent.

There is no lookup-by-reference endpoint, so recovering the original link means paging GET /payment-links and matching merchantReferenceId on the returned items yourself; status and mode are the only filters available to narrow the search.

Example:

"order-2026-0042"

redirect_urls

object

Where the customer's browser is sent after the hosted checkout completes. Propagated onto every checkout session spawned by this link.

Both URLs must be https:// — the hosted checkout returns the customer to them after a payment, so plaintext destinations are not accepted.

Show child attributes

three_ds_required

boolean

Force 3DS authentication for payments made through this link

Example:

true

description

string

Free-form description shown to the customer on the hosted checkout page

Example:

"Invoice"

customer

object

Customer details prefilled on the hosted checkout page. Every field is optional — omit the object entirely to have the customer enter their own details at checkout.

Show child attributes

metadata

object

Arbitrary merchant metadata, propagated onto every checkout session spawned by this link

Example:

{
  "invoice_id": "INV-4471",
  "sales_rep": "rep_88"
}

channel_id

string

Channel to attribute the link to

Example:

"3d1f9c60-5a72-4e18-b0c4-9a6d2f5e7b13"

expires_at

string<date-time>

ISO 8601 timestamp after which the link stops being payable. Omit for a link that never expires.

Example:

"2026-12-31T23:59:59Z"

max_uses

integer

Maximum number of successful payments. Optional, and 1 is the only accepted value while SINGLE_USE is the sole mode — omit it unless you want the ceiling stated explicitly.

Required range: x >= 1

Example:

1

Response

Payment link created successfully.

A shareable payment link. Sending a customer to hostedUrl spawns a checkout session and redirects them to the hosted checkout page.

Casing note: this response uses camelCase property names, while the create and update request bodies accept snake_case. This is a known divergence from the rest of the Lite API surface, which is snake_case in both directions. The contract documented here is what the service returns today — integrate against camelCase on the response.

string<uuid>

required

Unique payment link identifier

Example:

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

publicToken

string

required

Opaque token embedded in hostedUrl. Safe to share with customers — it carries no merchant or amount information.

Example:

"plive_7c9f2a1b8e4d6035"

hostedUrl

string<uri>

required

The customer-facing URL. Opening it consumes a slot on the link, creates a checkout session and redirects the browser to the hosted checkout page. Share this URL directly with customers.

Example:

"https://pay.lite.sa/pay/plive_7c9f2a1b8e4d6035"

merchantId

string<uuid>

required

Merchant that owns the link

Example:

"7f3c8b21-0d4e-4a92-9f65-2b8e1c7a4d30"

mode

enum<string>

required

How many times the link may be paid.

SINGLE_USE — exactly one successful payment. The link is promoted to PAID as soon as a payment reaches a terminal successful status.

Available options:

SINGLE_USE

Example:

"SINGLE_USE"

status

enum<string>

required

Lifecycle status of the payment link.

ACTIVE — payable.
DISABLED — deactivated by the merchant. Reversible via the update endpoint.
EXPIRED — expires_at has passed. Applied automatically when the link is read or listed; not settable by the caller.
PAID — the usage ceiling has been reached, i.e. the SINGLE_USE link has been paid. Not settable by the caller.

Only ACTIVE ↔ DISABLED transitions are accepted on the update endpoint.

Available options:

ACTIVE,

DISABLED,

EXPIRED,

PAID

Example:

"ACTIVE"

amount

integer

required

Amount in the currency's minor units (e.g. 10000 = 100.00 SAR)

Required range: x >= 1

Example:

10000

currency

string

required

ISO 4217 currency code

Example:

"SAR"

usedCount

integer

required

Number of successful payments. Mirrors paidCount.

Example:

2

paidCount

integer

required

Number of payments through this link that reached a successful terminal status

Example:

2

failedCount

integer

required

Number of payments through this link that reached a failed terminal status

Example:

1

createdAt

string<date-time>

required

Timestamp when the link was created

Example:

"2026-06-01T10:30:00.000Z"

updatedAt

string<date-time>

required

Timestamp when the link was last updated

Example:

"2026-06-04T09:12:44.000Z"

merchantReferenceId

string | null

Merchant-supplied reference. Unique per merchant — a second create with the same value is rejected with 409, which prevents duplicate links for one order.

Example:

"order-2026-0042"

redirectUrls

object | null

Post-checkout redirect targets, or null if none were configured

Show child attributes

threeDsRequired

boolean | null

Whether 3DS authentication is forced for payments made through this link

Example:

true

description

string | null

Free-form description shown to the customer on the hosted checkout page

Example:

"Invoice"

customer

object | null

Prefilled customer details, or null if none were configured

Show child attributes

metadata

object | null

Arbitrary merchant metadata, propagated onto every checkout session spawned by this link

Example:

{
  "invoice_id": "INV-4471",
  "sales_rep": "rep_88"
}

channelId

string | null

Channel the link is attributed to

Example:

"3d1f9c60-5a72-4e18-b0c4-9a6d2f5e7b13"

expiresAt

string<date-time> | null

When the link stops being payable. Once passed, the link is promoted to EXPIRED on the next read. null means the link never expires.

Example:

"2026-12-31T23:59:59.000Z"

maxUses

integer | null

Ceiling on successful payments. null unless the caller set it explicitly; either way a SINGLE_USE link allows exactly one successful payment.

Example:

1

lastPaidAt

string<date-time> | null

Timestamp of the most recent successful payment, or null if never paid

Example:

"2026-06-04T09:12:44.000Z"

Create a payment link

curl --request POST \
  --url https://api.lite.sa/api/v1/payment-links \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "mode": "SINGLE_USE",
  "amount": 10000,
  "currency": "SAR"
}
'

import requests

url = "https://api.lite.sa/api/v1/payment-links"

payload = {
    "mode": "SINGLE_USE",
    "amount": 10000,
    "currency": "SAR"
}
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({mode: 'SINGLE_USE', amount: 10000, currency: 'SAR'})
};

fetch('https://api.lite.sa/api/v1/payment-links', 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({mode: 'SINGLE_USE', amount: 10000, currency: 'SAR'})
};

fetch('https://api.lite.sa/api/v1/payment-links', 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/payment-links"

	payload := strings.NewReader("{\n  \"mode\": \"SINGLE_USE\",\n  \"amount\": 10000,\n  \"currency\": \"SAR\"\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/payment-links",
  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([
    'mode' => 'SINGLE_USE',
    'amount' => 10000,
    'currency' => 'SAR'
  ]),
  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",
  "publicToken": "plive_7c9f2a1b8e4d6035",
  "hostedUrl": "https://pay.lite.sa/pay/plive_7c9f2a1b8e4d6035",
  "merchantId": "7f3c8b21-0d4e-4a92-9f65-2b8e1c7a4d30",
  "mode": "SINGLE_USE",
  "status": "ACTIVE",
  "amount": 10000,
  "currency": "SAR",
  "usedCount": 2,
  "paidCount": 2,
  "failedCount": 1,
  "createdAt": "2026-06-01T10:30:00.000Z",
  "updatedAt": "2026-06-04T09:12:44.000Z",
  "merchantReferenceId": "order-2026-0042",
  "redirectUrls": {
    "success": "https://merchant.example.com/success",
    "failure": "https://merchant.example.com/failure"
  },
  "threeDsRequired": true,
  "description": "Invoice",
  "customer": {
    "id": "cus_8f1e2a4b",
    "firstName": "Sara",
    "lastName": "Al-Harbi",
    "email": "sara@example.com",
    "phoneCountryCode": "+966",
    "phoneNumber": "512345678",
    "billingAddress": {
      "line1": "123 High St.",
      "line2": "Apartment 5B",
      "city": "Riyadh",
      "state": "Riyadh Province",
      "postalCode": "11564",
      "country": "SA"
    }
  },
  "metadata": {
    "invoice_id": "INV-4471",
    "sales_rep": "rep_88"
  },
  "channelId": "3d1f9c60-5a72-4e18-b0c4-9a6d2f5e7b13",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "maxUses": 1,
  "lastPaidAt": "2026-06-04T09:12:44.000Z"
}

{
  "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"
  }
}

Payment Acceptance

Tokenization

Account Settlement

Create a payment link

Authorizations

Headers

Body

Response