Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

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

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.

Was this page helpful?