Skip to main content

Void

POST 
/v1/orders/:id/void

Release all or part of the remaining authorization hold. Voids can only be issued against amounts that have not yet been captured.

Business rules:

  • capturable_amount must be > 0.
  • amount defaults to the full remaining capturable amount. If provided, it must be <= capturable_amount.

Required permission: orders_void. Idempotency field: transaction_id.

Request​

Path Parameters

    id uuidrequired

    Order UUID.

Body

required

    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)

    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.

Responses​

Void attempted.

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