List Orders

GET 
/v1/orders

List orders visible to the authenticated principal. Results are paginated using countless pagination; sort by any allowed field via the sort[field] / sort[dir] parameters.

Filters are combinable — every filter is applied with AND semantics. Ranged filters (amount, created_at, updated_at) accept [gte] and [lte] bounds.

Required permission: orders_read.

Request

Query Parameters

items integer

Possible values: >= 1 and <= 100

Items per page (default set by the server, usually 25).

id uuid

Filter by order UUID.

sub_merchant_id string

Filter by sub-merchant identifier.

terminal_id string

Filter by acquirer terminal ID used to process the authorization.

forwarder_id string
issuer_id string

Filter by BIN-resolved issuer ID.

device_ip string

Filter by the customer IP recorded on the order.

agreement_id string

Filter to orders submitted under the given stored agreement.

description string
currency Currency

Possible values: Value must match regular expression ^[A-Z]{3}$

source_type string

Possible values: [card, apple_pay, google_pay, samsung_pay]

Filter by card (card) or wallet (apple_pay, google_pay, samsung_pay).

retrieval_reference RetrievalReferenceNumber
stan Stan
auth_code AuthorizationCode
response_code ResponseCode
first_digits string

BIN (first six digits of the PAN).

last_digits string

Last four digits of the PAN.

scheme Scheme

Possible values: [visa, mastercard, mada, amex]

country Country

Possible values: Value must match regular expression ^[A-Z]{2}$

card_type string

Filter by card product type (CREDIT, DEBIT, etc.).

issuer string

Issuing bank name (as returned in source.issuer).

amount[gte] integer

Minimum order amount (inclusive, minor units).

amount[lte] integer

Maximum order amount (inclusive, minor units).

created_at[gte] date-time

Return orders created at or after this timestamp.

created_at[lte] date-time
updated_at[gte] date-time
updated_at[lte] date-time
sort[field] string

Possible values: [merchant_id, amount, captured_amount, refunded_amount, currency, created_at, updated_at]

Default value: created_at

Field to sort by.

sort[dir] string

Possible values: [asc, desc]

Default value: desc

Responses

200

Paginated list of orders.

application/json

Schema

Schema

orders

object[]

required

Array [

id uuidrequired

A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

merchant

object

required

Brief representation of the merchant that owns the resource.

id uuidrequired

A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

name stringrequired

Merchant display name (English).

merchant_id stringrequired

Stable, human-readable merchant identifier assigned by the acquirer. Often used as the merchant's principal reference in scheme reports.

arabic_name string

Merchant display name in Arabic, when configured.

currency Currency (string)required

Possible values: Value must match regular expression ^[A-Z]{3}$

ISO 4217 three-letter currency code in uppercase.

The currency must match the currency configured for the merchant's scheme-level terminals. Once an order is created, its currency is immutable: every subsequent capture, void, refund and extension is denominated in the same currency.

amount Amount (integer)required

Possible values: <= 100000000

A non-negative integer representing a monetary value in the smallest currency unit for the associated currency (minor units).

Examples:

• 1.00 SAR is sent as 100
• 1.00 KWD is sent as 1000
• 1 JPY is sent as 1

For most order-creating endpoints the minimum is 100 (one full major unit). Endpoints that support zero-value operations (such as /v1/orders/verify and /v1/orders/:id/extend) allow 0.

captured_amount integerrequired

refunded_amount integerrequired

voided_amount integerrequired

description string

created_at date-timerequired

ISO 8601 UTC timestamp with time zone designator.

updated_at date-timerequired

ISO 8601 UTC timestamp with time zone designator.

source

object

required

Polymorphic payment source. The type discriminator resolves to either a Card or a DevicePayToken (Apple / Google / Samsung Pay).

oneOf

Card

Card payment source. Sensitive fields (full PAN, CVV) are never returned; responses expose only BIN (first_digits) and PAN last-four, plus network metadata resolved from the BIN tables.

type stringrequired

Possible values: [card]

issuer stringnullable

Human-readable issuing bank name, resolved from the BIN.

card_type stringnullable

Card product type — CREDIT, DEBIT, CHARGE, etc.

category stringnullable

Issuer product tier (e.g. PLATINUM, SIGNATURE, INFINITE). Free-text, sourced from the BIN table.

country_alpha2 Country (string)

Possible values: Value must match regular expression ^[A-Z]{2}$

ISO 3166-1 alpha-2 country code in uppercase.

scheme Scheme (string)required

Possible values: [visa, mastercard, mada, amex]

The card scheme (network) associated with the card. mada is detected from the issuing BIN and takes precedence over Visa / Mastercard co-branding for Saudi-issued cards.

card_auth_scheme stringnullable

Scheme that performed 3DS authentication for this card. May differ from scheme for co-branded cards (e.g. mada card authenticated via Visa as the parent scheme).

first_digits stringrequired

First six digits of the PAN (the BIN).

last_digits stringrequired

Last four digits of the PAN.

month integerrequired

Possible values: >= 1 and <= 12

year integerrequired

Possible values: >= 2000

DevicePayToken

Apple Pay, Google Pay or Samsung Pay tokenised payment source. The shape is identical to Card; the type discriminator indicates which wallet produced the token and first_digits / last_digits represent the DPAN (device PAN), not the underlying funding PAN.

type stringrequired

Possible values: [apple_pay, google_pay, samsung_pay]

issuer stringnullable

card_type stringnullable

category stringnullable

country_alpha2 Country (string)

Possible values: Value must match regular expression ^[A-Z]{2}$

ISO 3166-1 alpha-2 country code in uppercase.

scheme Scheme (string)required

Possible values: [visa, mastercard, mada, amex]

The card scheme (network) associated with the card. mada is detected from the issuing BIN and takes precedence over Visa / Mastercard co-branding for Saudi-issued cards.

first_digits stringrequired

last_digits stringrequired

month integerrequired

Possible values: >= 1 and <= 12

year integerrequired

]

meta

object

required

Cursor-style pagination metadata. next_page and prev_page are null at the boundaries. Total counts are intentionally omitted for performance on large result sets (countless pagination).

current_page integerrequired

Possible values: >= 1

next_page integernullablerequired

prev_page integernullablerequired

Example (from schema)

{
  "orders": [
    {
      "id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
      "merchant": {
        "id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
        "name": "Example Store",
        "merchant_id": "MERCHANT001",
        "arabic_name": "متجر الأمثلة"
      },
      "currency": "SAR",
      "amount": 10000,
      "captured_amount": 0,
      "refunded_amount": 0,
      "voided_amount": 0,
      "description": "string",
      "created_at": "2025-01-15T14:30:00Z",
      "updated_at": "2025-01-15T14:30:00Z",
      "source": {}
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null
  }
}

401

Authentication failed.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Missing authentication information"
}

403

The authenticated principal lacks the required permission.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Unauthorized"
}

Loading...