CreateCheckoutSessionRequest

Request body for creating a new checkout session

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"

redirect_urls

object

required

Redirect URLs for checkout session

Show child attributes

order

object

required

Order details

Show child attributes

customer

object

Customer details for checkout session creation. When provided, id is required.

Show child attributes

expiry

integer

Session expiry in seconds (default 3600)

Required range: 60 <= x <= 86400

Example:

1800

three_ds_required

boolean

deprecated

Deprecated and ignored. 3D Secure is enforced per channel; turn it on under Settings, Acceptance, Payment methods in the dashboard. Sending this field still succeeds and has no effect.

Example:

false

processing_type

default:REGULAR

Standard one-time payment

Allowed value: "REGULAR"

Example:

"REGULAR"

capture_mode

default:INSTANT

Capture the payment immediately upon authorization

Allowed value: "INSTANT"

Example:

"INSTANT"

metadata

object

Additional metadata

Example:

{ "session_type": "standard" }

channel_id

string<uuid>

Channel ID for the session

Example:

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

terminal_id

string<uuid>

Online terminal the session's payment is taken through. Defaults to the business account's default terminal at the time the session is created; later changes to the default do not move it. Business accounts only, and not together with channel_id.

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. Payment sessions only; rejected on a tokenization session.

Minimum array length: 1

Show child attributes

{
  "amount": 10000,
  "currency": "SAR",
  "redirect_urls": {
    "success": "https://example.com/success",
    "failure": "https://example.com/failure"
  },
  "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"
  },
  "expiry": 1800,
  "three_ds_required": false,
  "processing_type": "REGULAR",
  "capture_mode": "INSTANT",
  "metadata": {
    "session_type": "standard"
  },
  "channel_id": "550e8400-e29b-41d4-a716-446655440000",
  "terminal_id": "0b9d1c3e-6a51-4f6e-9a54-0f4f2b6e7d11",
  "splits": [
    {
      "amount": 9000,
      "business_account_id": "019859f8-3149-7a55-8211-a8179675d269",
      "account_reference": "main"
    }
  ]
}

Account Settlement

Payment Acceptance

Tokenization