Skip to main content

Reverse

POST 
/v1/transactions/:id/reverse

Issue a scheme-level reversal to cancel the effects of a transaction whose outcome is uncertain. A new reversal transaction is created and linked back to the source via reversed_transaction_id.

Reversals are designed for post-timeout recovery and for cases where scheme / downstream integrity cannot be trusted. Use void (for authorizations) or refund (for captures) when the original transaction's outcome is known.

Required permission: transactions_reverse. Idempotency field: transaction_id.

Request​

Path Parameters

    id uuidrequired

    UUID of the transaction to reverse.

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.

    reason stringrequired

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

    Rationale for the reversal. Recorded on the reversal transaction as reverse_reason for later reconciliation.

Responses​

Reversal submitted.

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.

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

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