Skip to main content

Retrieve Order

GET 
/v1/orders/:id

Retrieve a single order by its UUID. The response includes the full list of transactions (authorize, capture, void, refund, extension) recorded against the order.

Orders that belong to another acquirer return HTTP 404.

Required permission: orders_read.

Request​

Path Parameters

    id uuidrequired

    Order UUID.

Responses​

The order.

Schema

    id uuidrequired

    A 36-character UUIDv7 identifier.

    merchant

    object

    required

    Brief representation of the merchant that owns the resource.

    id uuidrequired

    A 36-character UUIDv7 identifier.

    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.

    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
    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 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}$

    Country where the card was issued (from BIN).

    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

    reauthorized_order_id uuidnullable

    If this order was created via reauthorization, the original order ID.

    agreement

    object

    A stored cardholder agreement referenced on merchant-initiated transactions.

    id stringrequired

    Merchant-chosen agreement identifier supplied when the agreement was established.

    type stringrequired

    Possible values: [unscheduled, recurring, registered, installment]

    first_order_id uuid

    ID of the order that established this agreement.

    max_use integernullable
    variability stringrequired

    Possible values: [fixed, variable]

    expiry datenullable
    active booleanrequired

    false once the agreement has been disabled via PUT /v1/agreements/:id/disable. Disabled agreements reject new transactions.

    created_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    updated_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    transactions

    object[]

    required

    All transactions against this order.

  • Array [

    • id uuidrequired

    A 36-character UUIDv7 identifier.

    status stringrequired

    Possible values: [initiated, approved, failed, timeout, system_error]

    • initiated: in-flight; no response received yet.
    • approved: scheme / issuer approved.
    • failed: declined by scheme or issuer.
    • timeout: gateway did not receive a response in time.
    • system_error: internal processing error.
    type stringrequired

    Possible values: [verify, purchase, authorize, capture, void, refund, extension, reversal]

    source_type TransactionType (string)

    Possible values: [internet, merchant, moto]

    How the transaction was initiated:

    • internet: customer-facing e-commerce transaction (card not present, authenticated by 3DS).
    • merchant: merchant-initiated transaction on a stored agreement (unscheduled, recurring, installment, etc.).
    • moto: mail-order / telephone-order transaction where card details are collected by the merchant out of band.
    reverse_reason stringnullable

    Possible values: [request_timeout, gateway_timeout, response_error, delivery_error, null]

    Populated on reversal transactions only.

    justification stringnullable

    Possible values: [reauthorization, delayed_charges, resubmission, no_show, null]

    reversed_transaction_id uuidnullable

    If type = reversal, the transaction this reversal nullified.

    message string

    Human-readable gateway response message.

    response_code ResponseCode (string)

    Two-digit ISO 8583 response code returned by the issuer. 00 indicates approval; non-00 codes are declines.

    original_message stringnullable

    On a reversal, the message from the transaction being reversed.

    original_response_code stringnullable
    retrieval_reference RetrievalReferenceNumber (string)

    Twelve-digit Retrieval Reference Number (RRN) assigned by the acquirer and forwarded to the issuer. Useful for reconciling an entry on the cardholder's statement. Not unique across schemes.

    stan Stan (string)

    System Trace Audit Number (STAN). A six-digit acquirer-local counter that is unique per terminal per business day.

    auth_code AuthorizationCode (string)

    Six-character authorization code returned by the issuer on approval.

    issuer_response_code stringnullable
    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
    refunded_amount integer

    Cumulative refunds allocated against this specific transaction.

    scheme_trace_id stringnullable
    terminal_id stringnullable
    created_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

  • ]

Loading...
Last updated on