Create a new payment

Initiates a payment request for processing. Returns immediately with an accepted response; the payment is processed asynchronously.

payment_instrument accepts three shapes at the gateway:

{ "id": "<instrument_id>" } — use an existing instrument
{ "payment_method", "pan_data", ... } — gateway tokenizes card data first
{ "payment_method", "data", ... } — gateway tokenizes encrypted payload first

Inline tokenization requires customer.id. The payment service always receives payment_instrument.id after gateway processing.

POST

https://api.lite.sa

payments

curl --request POST \
  --url https://api.lite.sa/payments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 10000,
  "currency": "SAR",
  "device": {
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0"
  },
  "customer": {
    "id": "06463cf8-c156-4ff6-bf02-5d559b738718"
  },
  "payment_instrument": {
    "id": "e835c96f-3ede-47ff-85e3-3515b7ac125f"
  }
}
'

{
  "payment": {
    "id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
    "status": "PENDING",
    "merchant_reference": "ORD-123456"
  },
  "_links": {
    "self": {
      "href": "<string>",
      "method": "POST"
    },
    "capture": {
      "href": "<string>",
      "method": "POST"
    },
    "void": {
      "href": "<string>",
      "method": "POST"
    },
    "refund": {
      "href": "<string>",
      "method": "POST"
    },
    "redirect": {
      "href": "<string>",
      "method": "POST"
    }
  }
}

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The terminal is not active.",
      "retriable": false
    }
  ],
  "request_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"
  }
}

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The terminal was not found.",
      "retriable": false
    }
  ],
  "request_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"
  }
}

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_UNAVAILABLE",
      "message": "The terminal could not be confirmed. Retry the request.",
      "retriable": true
    }
  ],
  "request_id": "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"

x-business-account-id

string<uuid>

The business account to act on, for platform use cases. When sent, that account is the merchant for the request: resources are created under it, reads and 404 checks are scoped to it, and per-merchant uniqueness (such as merchant_reference_id) applies within it. The API key's own account is recorded as the account acting on its behalf. Omit it to act on the API key's own account.

Example:

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

Body

application/json

Create a new payment

Existing instrument
Inline PAN data
Encrypted instrument data

Pay with a previously tokenized instrument. The gateway forwards payment_instrument.id as-is; customer is optional.

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"

device

object

required

Device information (required for 3DS and risk assessment)

Show child attributes

payment_instrument

object

required

Reference an existing tokenized payment instrument by ID.

Show child attributes

processing

object

Processing details

Show child attributes

capture_options

object

Capture options

Show child attributes

order

object

Order details

Show child attributes

customer

object

Customer details

Show child attributes

three_ds

object

3DS settings

Show child attributes

risk

object

Risk assessment data

Show child attributes

return_info

object

Return URLs

Show child attributes

metadata

object

Additional metadata

Example:

{ "custom_field": "value" }

channel_id

string<uuid>

Channel ID for the payment

Example:

"019859f8-3149-7a55-8211-a8179675d269"

terminal_id

string<uuid>

Online terminal to take the payment through; defaults to the business account's default terminal. Business accounts only, and not together with channel_id. Unrelated to device.terminal_id (the POS terminal).

Example:

"0b9d1c3e-6a51-4f6e-9a54-0f4f2b6e7d11"

splits

object[]

Optional transaction-level split allocations in minor units. The full payment lands in the main acceptance account first; each allocation is then transferred to its destination, and the remainder stays in the main account. The allocations must not total more than amount. If sent, it must contain at least one item.

Minimum array length: 1

Show child attributes

Response

Payment accepted for processing.

payment

object

required

Show child attributes

_links

object

Available action links (HATEOAS)

Show child attributes

curl --request POST \
  --url https://api.lite.sa/payments \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 10000,
  "currency": "SAR",
  "device": {
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0"
  },
  "customer": {
    "id": "06463cf8-c156-4ff6-bf02-5d559b738718"
  },
  "payment_instrument": {
    "id": "e835c96f-3ede-47ff-85e3-3515b7ac125f"
  }
}
'

{
  "payment": {
    "id": "baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5",
    "status": "PENDING",
    "merchant_reference": "ORD-123456"
  },
  "_links": {
    "self": {
      "href": "<string>",
      "method": "POST"
    },
    "capture": {
      "href": "<string>",
      "method": "POST"
    },
    "void": {
      "href": "<string>",
      "method": "POST"
    },
    "refund": {
      "href": "<string>",
      "method": "POST"
    },
    "redirect": {
      "href": "<string>",
      "method": "POST"
    }
  }
}

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The terminal is not active.",
      "retriable": false
    }
  ],
  "request_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"
  }
}

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The terminal was not found.",
      "retriable": false
    }
  ],
  "request_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"
  }
}

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_UNAVAILABLE",
      "message": "The terminal could not be confirmed. Retry the request.",
      "retriable": true
    }
  ],
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Payment Acceptance

Tokenization

Account Settlement

Create a new payment

Authorizations

Headers

Body

Response