CreatePaymentRequest

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

{
  "amount": 10000,
  "currency": "SAR",
  "device": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9",
    "language": "en-US",
    "screen_height": 1080,
    "screen_width": 1920,
    "color_depth": 24,
    "timezone": -180,
    "java_enabled": false,
    "java_script_enabled": true,
    "ip": "192.168.1.100",
    "device_data": {},
    "device_fingerprint": "fp_123",
    "ip_country": "SA",
    "ip_city": "Riyadh",
    "ip_region": "Riyadh Region",
    "ip_postal_code": "12213",
    "ip_latitude": 24.7136,
    "ip_longitude": 46.6753,
    "terminal_id": "1234567890123456"
  },
  "payment_instrument": {
    "id": "e835c96f-3ede-47ff-85e3-3515b7ac125f"
  },
  "processing": {
    "processing_type": "REGULAR",
    "initiator": "CARD_HOLDER"
  },
  "customer": {
    "id": "cust_a1b2c3d4e5f6",
    "email": "john.doe@email.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_country_code": "+966",
    "phone_number": "555123456"
  },
  "three_ds": {
    "force": true
  },
  "risk": {
    "enabled": true,
    "device_session_id": "sess_abc123"
  },
  "return_info": {
    "success": "https://example.com/success",
    "cancel": "https://example.com/cancel",
    "error": "https://example.com/error"
  },
  "metadata": {
    "custom_field": "value"
  },
  "channel_id": "019859f8-3149-7a55-8211-a8179675d269",
  "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