---
title: Reversals
description: How a finished payout or wallet transfer is undone, and how to spot it in your transactions.
---

:::note[In a nutshell]
A reversal undoes a payment that already finished. iSmartPay never edits the original. It records a second movement that sends the money back, and links the two.
:::

## 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](/guides/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.

```http
POST /v1/transfers/supplier-7731/reversal-requests
Idempotency-Key: 5b0f2c8e-rev-1
Content-Type: application/json

{ "reason": "Paid the wrong supplier." }
```

```json
{
  "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 `reference` starts with `rvr-`. iSmartPay chose it. You cannot use that prefix on your own transfers.
- Its `parent` points to the transfer it undoes.
- It moves money the other way. The sender sees it as `in`, the business that was paid sees it as `out`.

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:

```json
{
  "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 `parent` and `compensation` types 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](/guides/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](/guides/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. |
