Refunds and reversals
Two different ways to give a customer their money back. They look the same from outside; the rules and constraints differ significantly.
Reversals and refunds are the two ways to return money to a customer after a successful transaction. They look the same from outside — the customer gets their money back — but the rules, eligibility, and constraints are different.
This page covers when to use which, the API for each, and the typical operational patterns.
For the rules in detail, see Refunds and reversals — business rules.
Reversal vs refund — pick the right one
| Reversal | Refund | |
|---|---|---|
| When | Same-day, before the transaction settles | Any time after settlement (within the issuer's window) |
| Amount | Full only — you cannot reverse part of a transaction | Full or partial — refund any amount up to the original |
| Card types | All — debit, credit, cheque | Credit and cheque only — debit cards cannot be refunded (PASA rules) |
| Customer experience | Looks like the transaction never happened | Two entries: original charge, then a refund credit |
| Settlement impact | Net-zero; nothing settles | Original settles, refund settles separately |
| Use it when | Order cancelled before fulfilment, customer disputed at checkout, your handler returned non-200 | Order shipped then returned, partial returns, post-shipment customer queries |
When in doubt: reverse if you can, refund if you must. Reversals are cleaner — no settlement impact, no bookkeeping entries to reconcile, and they work on all card types.
Reverse a transaction
curl -X DELETE "https://qa.scantopay.io/pluto/purchase/{transactionId}" \
-u "$USERNAME:$PASSWORD"Path parameter:
transactionId— the Scan to Pay transaction ID from the original webhook payload
Reversals are full-amount only. No body required.
Outcome
If the transaction is reversible, the platform schedules a reversal and you'll receive a notification with status: REVERSED.
REVERSEDdoes not mean the reversal succeeded. On the merchant-notification channel, a failed reversal also arrives asstatus: REVERSED— the reason is inbankResponse. Always checkbankResponserather than treatingREVERSEDas confirmation. On the transaction-webhook channel the distinction is visible directly instatus, which reportsEND_REVERSEDorEND_REVERSAL_FAILED.
Reversal eligibility is enforced by the issuing bank, not Scan to Pay. The platform will attempt any reversal you request; whether it succeeds depends on whether the bank has cleared the transaction yet.
Reversal-on-webhook-failure
Reversals also happen automatically if your webhook handler fails to acknowledge a successful payment within 45 seconds. See Webhooks — How it works. You don't need to manually reverse in that case — the platform's safety net does it for you.
Refund a transaction
Two endpoints. Both dispatch the refund to the bank and return before the bank has responded — the difference is only what comes back in the response body.
Neither endpoint returns the refund outcome. The refund is sent to the acquirer asynchronously and is still in flight when the response is returned. Whether the refund actually succeeded reaches you on the notification/webhook, never in the HTTP response. Don't tell a customer their refund succeeded on the strength of a200from either endpoint.
Refund — no response body
curl -X POST "https://qa.scantopay.io/pluto/purchase/refund/{transactionId}" \
-u "$USERNAME:$PASSWORD" \
-H 'Content-Type: application/json' \
-d '{
"amount": 50.00
}'The platform records the refund request and responds 200 with an empty body. The outcome arrives later — see What you'll see in webhooks below.
doRefund — returns the refund transaction ID
curl -X POST "https://qa.scantopay.io/pluto/purchase/doRefund/{transactionId}" \
-u "$USERNAME:$PASSWORD" \
-H 'Content-Type: application/json' \
-d '{
"amount": 50.00
}'{
"transactionId": 6489130,
"originalTransactionId": 6481694
}This endpoint starts the refund immediately and returns the newly created refund transaction's ID — useful if you want to store it against your order record, or poll for the outcome rather than waiting on a webhook. transactionId is null if the refund could not be started.
Use doRefund in preference to refund unless you have a reason not to: without the returned ID you have no handle on the refund until its notification arrives.
Path and body
| Param | Where | Required | Detail |
|---|---|---|---|
transactionId | Path | ✓ | The original transaction's Scan to Pay ID |
amount | Body | ✓ | The amount to refund. Up to the original transaction amount. Partial refunds allowed for credit/cheque cards. |
webhook | Body | optional | Destination URL for this refund's outcome notification. Max 2048 characters. Omit to inherit the original transaction's webhook. |
Sending the outcome somewhere else
Both endpoints accept an optional webhook field that overrides where this refund's outcome notification is delivered:
curl -X POST "https://qa.scantopay.io/pluto/purchase/doRefund/{transactionId}" \
-u "$USERNAME:$PASSWORD" \
-H 'Content-Type: application/json' \
-d '{
"amount": 50.00,
"webhook": "https://mydomain.com/mywallet/refund-webhook"
}'Omit it (or send null) and the refund inherits the original transaction's webhook URL and payload version — the long-standing default. Supply it and it applies to this refund only.
The value is checked for URI syntax and nothing more; a malformed value is rejected with 461 INVALID_REQUEST. There is no scheme or host allow-list, so always supply an HTTPS URL on a host you control. Full detail, including the payload and retry behaviour: Webhooks — Refund webhooks.
Partial refunds
You can refund less than the full amount, and you can refund multiple times against the same original transaction until you've returned the full amount.
# First partial — R50 off an R150 original
POST /pluto/purchase/refund/{transactionId} with {"amount": 50.00}
# Later — another R25
POST /pluto/purchase/refund/{transactionId} with {"amount": 25.00}
# Now you've refunded R75 of R150. R75 remaining can still be refunded.What you'll see in webhooks
Both reversals and refunds notify you when they complete. Which payload you get depends on which delivery channel your integration is on — the two are mutually exclusive, and they use different status vocabularies. See Webhooks — Two delivery channels if you're not sure which applies to you.
If you're on merchant notifications (encrypted payload, Portal-configured URL):
status | Meaning |
|---|---|
REVERSED | Reversal completed |
REFUNDED | Refund succeeded (full or partial) |
referenceTransactionId points back to the original transaction so you can reconcile.
If you're on transaction webhooks (plain JSON, per-transaction URL):
status | Meaning |
|---|---|
END_REFUNDED | Refund succeeded |
END_REFUND_FAILED | The bank declined the refund — check bankResponse for the ISO code |
END_BANK_ERROR | The bank returned an invalid or unreadable response |
END_BANK_OFFLINE | The bank could not be reached — transient, safe to retry |
END_SYSTEM_ERROR | Internal error before the refund reached the bank |
Here the outcome is reported in more detail than the rolled-up status above, so failures are distinguishable from one another. originalTransactionId — not referenceTransactionId — points back to the original transaction.
On both channels, amount is the amount refunded on this call, not the cumulative refunded total, and the bankResponse / authCode / RRN describe the refund, not the original purchase.
For the full payload structure, see Webhooks.
Errors
| Status / code | Meaning |
|---|---|
444 NOTHING_TO_REVERSE | The transaction can't be reversed (already reversed, already refunded, or outside the bank's window) |
514 UNABLE_TO_REVERSE | The reversal was attempted but failed at the bank |
515 UNABLE_TO_REFUND | The refund was attempted but failed (different card type, already fully refunded, outside acquirer window) |
445 INVALID_CLIENT_CARD | Attempting to refund a debit card — not allowed per PASA |
432 INVALID_AMOUNT | Refund amount exceeds the remaining refundable balance, or is zero/negative |
436 INVALID_TRANSACTION_REF | The transactionId doesn't match any known transaction |
Full error reference: Errors.
What's next
- Detailed business rules and constraints → Refunds and reversals — business rules
- Receive the refund/reversal notification → Webhooks
- Bank decline codes if a refund fails at the issuer → ISO response codes
- Query transaction state to confirm → Querying transactions
- Handle cardholder disputes that need a refund → Customer disputes
Updated 16 days ago
