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/v1

payments

curl --request POST \
  --url https://api.lite.sa/v1/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"
    }
  }
}

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

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

threeds

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"

Response

Payment accepted for processing.

payment

object

required

Show child attributes

_links

object

Available action links (HATEOAS)

Show child attributes

Get payment by IDReturns payment details. Use query parameter `include=instrument,operations` to expand instrument and/or operations in the response.

curl --request POST \
  --url https://api.lite.sa/v1/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"
    }
  }
}

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