Skip to main content

Purchase

POST 
/v1/orders/purchase

Submit an authorization and immediately capture it in a single scheme message. Purchase is the right choice when goods are delivered (or the service is rendered) at the moment of payment.

The transaction can be submitted in three modes via transaction_type:

  • internet — cardholder-initiated e-commerce. A 3DS authentication performed via the /v1/3ds endpoints is required and must be carried in source.auth.
  • moto — mail order / telephone order.
  • merchant — merchant-initiated against a stored agreement. Pass agreement_id and omit source.auth.

If new_agreement is supplied, this call both processes the purchase and creates a stored agreement off of this card that can be used on future merchant-initiated transactions.

Required permission: orders_create. Idempotency field: order_id.

Request​

Body

required

    order_id uuid

    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.

    transaction_id uuid

    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.

    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.

    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.

    description stringrequired

    Possible values: <= 1024 characters

    Free-text description shown in dashboards and reports.

    transaction_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.). Authentication is carried on the linked agreement, not the current transaction.
    • moto: mail-order / telephone-order transaction where card details are collected by the merchant out of band.

    source

    object

    required

    Payment source submitted with a new order. type selects the variant.

    oneOf

    Raw card details. The PAN is tokenised server-side and never returned in responses.

    type stringrequired

    Possible values: [card]

    holder string

    Possible values: <= 255 characters

    Cardholder name as embossed on the card.

    number CardPan (string)required

    Possible values: Value must match regular expression ^\d{13,19}$

    Primary Account Number (PAN) as a continuous digit string, no separators. Sent in request bodies only — PAN is never returned in full in responses; only first_digits and last_digits are echoed.

    month integerrequired

    Possible values: >= 1 and <= 12

    year integerrequired

    Possible values: >= 2000

    Four-digit expiry year.

    security_code CardSecurityCode (string)

    Possible values: Value must match regular expression ^\d{3,4}$

    CVV / CVC / CSC printed on the card. 3 digits for Visa, Mastercard and mada; 4 digits for Amex. Required when opening a new agreement (new_agreement) so the card can be initially validated.

    auth

    object

    3DS authentication values carried alongside a card authorization. Required on transaction_type: internet and when establishing a new_agreement against a card source. Obtain these values by completing a /v1/3ds flow and copying them from the authenticated CardAuth.

    scheme Scheme (string)

    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.

    value stringrequired

    Possible values: <= 256 characters

    CAVV / 3DS server transaction value issued by the ACS.

    status AuthStatus (string)required

    Possible values: [Y, N, U, A, R]

    Transaction status from the 3DS authentication response:

    • Y: Authenticated successfully.
    • N: Not authenticated / denied.
    • U: Authentication could not be performed.
    • A: Attempt performed. Not authenticated but a CAVV was provided.
    • R: Rejected by issuer.
    eci EciIndicator (string)required

    Possible values: [00, 01, 02, 05, 06, 07]

    Electronic Commerce Indicator returned by the directory server / issuer ACS. Identifies the authentication strength and is required when submitting a 3DS-authenticated transaction.

    version ThreeDsVersion (string)required

    Possible values: [2.0.0, 2.1.0, 2.2.0, 2.3.0]

    EMV 3-D Secure protocol version the authentication was performed under.

    ds_transaction_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.

    acs_transaction_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.

    ds_reference_number string

    Possible values: <= 32 characters

    acs_reference_number stringrequired

    Possible values: <= 32 characters

    tds_purchase_date TdsPurchaseDate (string)required

    Possible values: Value must match regular expression ^\d{12}$

    Purchase date in YYYYMMDDHHMM format (UTC). Generated by the 3DS server during authentication. Must be echoed back verbatim when the authorization is submitted, otherwise authentication values are rejected by the scheme.

    device

    object

    End-user device metadata collected at the point the payment was initiated. Used for risk scoring and scheme-specific reporting.

    user_agent string

    Possible values: <= 1024 characters

    ip_address string

    Public IPv4 or IPv6 address of the customer.

    airline

    object

    Airline Addendum data. When present the transaction will be tagged for the scheme's airline data programme, which may affect interchange category.

    reference stringrequired

    Possible values: >= 6 characters and <= 15 characters, Value must match regular expression ^[A-Za-z0-9]+$

    Passenger Name Record (PNR) locator.

    new_agreement

    object

    Creates a stored cardholder agreement in the same request that submits the initial authorization. Once the agreement is established, subsequent merchant-initiated transactions can be submitted by referencing agreement_id instead of new_agreement.

    When new_agreement is sent, source.security_code is required and, for card sources, source.auth must contain the 3DS authentication values for the initial transaction.

    type stringrequired

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

    • unscheduled: Card-on-file, charged when the customer takes an action (e.g. top-up wallets).
    • recurring: Fixed-cadence subscriptions (e.g. monthly).
    • registered: Card stored for future consented purchases.
    • installment: Fixed-count, fixed-amount instalment plan.
    id stringrequired

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[A-Za-z0-9-]+$

    Merchant-chosen identifier for the agreement. Must be unique per merchant. This value is what is passed as agreement_id on subsequent transactions.

    expiry date

    Optional end-of-life date after which the agreement will not accept new transactions.

    max_use integer

    Possible values: >= 1 and <= 999

    Maximum number of transactions the agreement will accept.

    variability string

    Possible values: [fixed, variable]

    Default value: variable

    Whether each transaction amount is fixed (e.g. a locked-in subscription price) or variable (e.g. metered usage).

    agreement_id string

    Possible values: <= 64 characters

    ID of a pre-existing stored agreement to submit this transaction against. Mutually exclusive with new_agreement.

    additional_data

    object

    Scheme-specific indicators carried in the authorization request. Provide only the sub-object for the scheme(s) you are sending; keys for other schemes are ignored.

    visa

    object

    authorization_characteristics_indicator string

    Visa Authorization Characteristics Indicator. Identifies special processing characteristics for this authorization (e.g. Visa Debt Repayment, Deferred Authorization).

    market_specific_indicator string

    Visa Market Specific Data Indicator identifying the originating market segment (e.g. hospitality, car rental, transit).

    mastercard

    object

    transaction_type_indicator string

    Mastercard Transaction Type Indicator.

    promotion_code string

    Mastercard promotion code when the authorization is part of a promo.

    sub_merchant

    object

    Sub-merchant data for payment facilitators ("payfacs") that settle on behalf of multiple retail businesses. When present, scheme reports will attribute the transaction to this sub-merchant rather than the primary merchant of record.

    id stringrequired

    Possible values: non-empty and <= 15 characters, Value must match regular expression ^[A-Za-z0-9-]+$

    Sub-merchant identifier assigned by the payfac.

    registered_name stringrequired

    Possible values: non-empty and <= 100 characters

    trading_name stringrequired

    Possible values: non-empty and <= 100 characters

    email emailrequired

    statement_descriptors

    object

    Narrative text that appears on the cardholder's statement. The English descriptor is mandatory; the Arabic descriptor is rendered on statements for cardholders whose issuers support it.

    english stringrequired

    Possible values: non-empty and <= 22 characters

    arabic string

    Possible values: non-empty and <= 22 characters

Responses​

Purchase processed. Inspect transactions[0].status to determine the outcome.

Schema

    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 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.

    airline

    object

    Airline Addendum data. When present the transaction will be tagged for the scheme's airline data programme, which may affect interchange category.

    reference stringrequired

    Possible values: >= 6 characters and <= 15 characters, Value must match regular expression ^[A-Za-z0-9]+$

    Passenger Name Record (PNR) locator.

    sub_merchant

    object

    Sub-merchant data for payment facilitators ("payfacs") that settle on behalf of multiple retail businesses. When present, scheme reports will attribute the transaction to this sub-merchant rather than the primary merchant of record.

    id stringrequired

    Possible values: non-empty and <= 15 characters, Value must match regular expression ^[A-Za-z0-9-]+$

    Sub-merchant identifier assigned by the payfac.

    registered_name stringrequired

    Possible values: non-empty and <= 100 characters

    trading_name stringrequired

    Possible values: non-empty and <= 100 characters

    email emailrequired

    statement_descriptors

    object

    Narrative text that appears on the cardholder's statement. The English descriptor is mandatory; the Arabic descriptor is rendered on statements for cardholders whose issuers support it.

    english stringrequired

    Possible values: non-empty and <= 22 characters

    arabic string

    Possible values: non-empty and <= 22 characters

    agreement

    object

    A stored cardholder agreement referenced on merchant-initiated transactions.

    id stringrequired

    Merchant-chosen agreement identifier (the id supplied in new_agreement.id at creation). Use this value as agreement_id on follow-up transactions.

    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, ordered by created_at ascending.

  • 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.

    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.). Authentication is carried on the linked agreement, not the current transaction.
    • 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. See the scheme / issuer response code table for the full list.

    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

    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.

    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...