Create reversal

Creates a reversal transaction that negates the financial effect of a previously posted transaction.
This endpoint is used when an original transaction (for example: refund, fund, or payout) must be cancelled
or undone due to rejection, failure, or post-processing validation.

The reversal does not delete the original transaction. Instead, it creates a new transaction of type REVERSAL
that mirrors the original transaction’s amount and currency, while inverting the debit and credit legs
according to the original transaction type.

Each reversal can optionally reference the original transaction (by ID or external reference) to ensure full
auditability, ledger traceability, and regulatory compliance.

Provide either original_transaction_id or original_transaction_external_reference (not both).

Reversal Behavior by Transaction Type

Original Transaction Type	Reversal Effect
Refund	Debits the refunded amount back from the recipient
Fund	Credits the amount back to the source (business) wallet
Payout	Credits the business and debits the wallet
Transfer	Credits the sender and debits the receiver
Withdrawal	Credits the wallet/business and debits the "World" or Clearing wallet
Any supported type	Debit and credit legs are inverted

Balance Handling

If canOverdraft = true, the reversal may cause the wallet balance to go negative.

If canOverdraft = false and the wallet lacks sufficient balance, the reversal is rejected with INSUFFICIENT_BALANCE.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

ReversalCreatePayloadReversalCreatePayloadByExternalReference

{
    "original_transaction_id": "da6d857d-0bbf-411d-9902-ec90e0e92963",
    "external_reference": "REV-1",
    "notes": "Refund invoice rejected from ZATCA"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200

application/json

Reversal created

Body

Example

{
    "id": "4e0f5b1f-c449-4083-a408-bfe1355a3b6b",
    "total_reversed_amount": "10.00",
    "currency": "SAR",
    "original_transaction_id": "b6327558-741e-411c-866b-0eec8ea26005",
    "original_transaction_amount": "10.00",
    "original_transaction_reference": "PO-0013579",
    "sender_account_number": "054200002027",
    "receiver_account_number": "054200001011",
    "external_reference": "REV-1",
    "notes": "Refund invoice rejected from ZATCA",
    "status": "SUCCESS",
    "created_at": "2025-10-25T14:35:46.011Z"
}

🟠400

🟠401

🟠403

🟠404

🟠422

Reversal Behavior by Transaction Type#

Balance Handling#

Request

Request Code Samples

Responses

Reversal Behavior by Transaction Type

Balance Handling