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.

curl --location --request POST 'https://api.staging.vrtx.sa/cl/v1/reversal' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "original_transaction_id": "da6d857d-0bbf-411d-9902-ec90e0e92963", "external_reference": "REV-1", "notes": "Refund invoice rejected from ZATCA" }'

{ "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" }

Reversal Behavior by Transaction Type

Balance Handling

Request

Responses

Create reversal

Reversal Behavior by Transaction Type#

Balance Handling#

Request

Responses

Reversal Behavior by Transaction Type

Balance Handling