Reversals
How a finished payout or wallet transfer is undone, and how to spot it in your transactions.
What can be reversed
| Payment | When |
|---|---|
| Payout | delivered |
| Wallet transfer you sent | completed |
Collections, settlements and utility purchases cannot be reversed. Neither can a transfer that is itself a reversal.
A failed payout that became refunded is not a reversal. Its money never left, so it just came back. See Payment statuses.
Asking for one
Ask through the API, or have an owner ask in the merchant console. Either way you give a reason. iSmartPay staff can also open one, for example when a provider returns a payout.
POST /v1/transfers/supplier-7731/reversal-requests
Idempotency-Key: 5b0f2c8e-rev-1
Content-Type: application/json
{ "reason": "Paid the wrong supplier." }
{
"reference": "rvr_3f6d2a10-8c4e-4b7a-9d21-5e0f7c3b2a91",
"sourceType": "wallet_transfer",
"sourceReference": "supplier-7731",
"status": "pending_review",
"amount": "25.00",
"currency": "GHS",
"reason": "Paid the wrong supplier.",
"reviewDueAt": "2026-10-08T09:14:02Z",
"createdAt": "2026-10-07T09:14:02Z",
"updatedAt": "2026-10-07T09:14:02Z"
}
A 202 means the request was recorded. Nothing moves yet. Staff review it and approve or decline it. A request nobody reviews by reviewDueAt expires. Only one request can be open on a payment at a time, and you can ask again once one ends as rejected, expired or failed.
For a payout, send the same body to POST /v1/payouts/{reference}/reversal-requests. The response adds recipientAmount and feeAmount, and amount is their total.
Following a request
Nothing is sent to your webhooks when a request changes. Read it again instead:
| Call | Returns | The key needs |
|---|---|---|
GET /v1/payouts/{reference}/reversal-requests |
The latest request for that payout. | disbursements.read |
GET /v1/transfers/{reference}/reversal-requests |
The latest request for that transfer. | wallettransfer.read |
GET /v1/reversal-requests/{reference} |
One request, by its rvr_ reference. |
transactions.read |
The first two answer 404 not_found when no request was made. failureReason says why a request ended without money moving: source_ineligible, compensation_unavailable or unable_to_process. Expect new values.
| Status | Meaning |
|---|---|
pending_review |
Waiting for staff. Nothing has moved. |
approved, executing |
Approved. The money is being sent back. |
blocked |
Approved but stuck. Staff are working on it. Nothing has moved. |
completed |
The money is back in your wallet. |
rejected |
Declined. Nothing moved. |
expired |
Not reviewed in time. Nothing moved. |
failed |
Could not be done. Nothing moved. |
Payouts
A delivered payout’s money sits with the recipient’s provider. iSmartPay has to get it back from the provider before it can credit your wallet, and that can take a few days. The request stays blocked until then.
A completed payout reversal returns everything that left your wallet, fee included. The money shows in your wallet balance, but GET /v1/transactions does not list it or link it to the payout yet. The payout stays delivered with no compensation. To confirm one, read its reversal request and wait for completed.
Wallet transfers
A transfer reversal takes the money back out of the receiving business’s wallet. If that wallet does not hold enough, the reversal stays blocked until staff sort it out.
If you receive transfers, money you were paid can leave your wallet this way. It only happens after iSmartPay staff approve a request from the sender.
In your transactions
A wallet transfer reversal shows up in GET /v1/transactions as a new wallet transfer:
- Its
referencestarts withrvr-. iSmartPay chose it. You cannot use that prefix on your own transfers. - Its
parentpoints to the transfer it undoes. - It moves money the other way. The sender sees it as
in, the business that was paid sees it asout.
The original transfer keeps its completed status. It gains a compensation link to the reversal.
A wallet transfer you sent, and the reversal that undid it:
{
"items": [
{
"id": "txn_51c0e9b7",
"kind": "wallet_transfer",
"direction": "in",
"reference": "rvr-3f6d2a10-8c4e-4b7a-9d21-5e0f7c3b2a91-1",
"amount": "25.00",
"currency": "GHS",
"status": "completed",
"parent": { "type": "wallet_transfer", "reference": "supplier-7731" },
"createdAt": "2026-10-07T09:14:02Z"
},
{
"id": "txn_8d2f4a1c",
"kind": "wallet_transfer",
"direction": "out",
"reference": "supplier-7731",
"amount": "25.00",
"currency": "GHS",
"status": "completed",
"compensation": { "type": "wallet_transfer", "reference": "rvr-3f6d2a10-8c4e-4b7a-9d21-5e0f7c3b2a91-1" },
"createdAt": "2026-10-05T10:00:00Z"
}
]
}
The values above only show the shape. Other fields are left out.
parent and compensation are absent on every payment that has nothing to do with a reversal.
Reconciling
- Do not change your record of the original transfer when a reversal arrives. Record the reversal as its own entry and link it through
parent. - Match on
parent.reference, not on amounts. Two transfers of the same amount can be reversed on the same day. - Ignore
parentandcompensationtypes you do not recognise. More may come later.
No webhook event is specific to reversals. To catch transfer reversals, read GET /v1/transactions and look for parent. To catch payout reversals, read their reversal requests. See Transactions and events.
Permissions
| To | The key needs |
|---|---|
| Ask to reverse a payout | disbursements.write |
| Ask to reverse a transfer | wallettransfer.write |
| Read a request by payout or transfer | disbursements.read or wallettransfer.read |
| Read a request by its reference | transactions.read |
Errors
As well as the common errors:
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_input |
The reason is missing or over 500 characters, the reference is malformed, or Idempotency-Key is missing. Read message. |
| 404 | reversal_source_not_found |
None of your payouts or transfers has that reference. Check it. |
| 409 | reversal_source_ineligible |
It cannot be reversed. Read message: a voucher or payment-request transfer has another way back. |
| 409 | reversal_already_active |
A request is already open or has completed. Read it instead of asking again. |
| 409 | idempotency_key_reused |
You used this key for a different request. Use a new key. |