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

payments

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

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"

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/api/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"
  }
}

Payment Acceptance

Tokenization

Account Settlement

Create a new payment

Authorizations

Headers

Body

Response