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

ReversalRefund
WhenSame-day, before the transaction settlesAny time after settlement (within the issuer's window)
AmountFull only — you cannot reverse part of a transactionFull or partial — refund any amount up to the original
Card typesAll — debit, credit, chequeCredit and cheque only — debit cards cannot be refunded (PASA rules)
Customer experienceLooks like the transaction never happenedTwo entries: original charge, then a refund credit
Settlement impactNet-zero; nothing settlesOriginal settles, refund settles separately
Use it whenOrder cancelled before fulfilment, customer disputed at checkout, your handler returned non-200Order 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.

⚠️

REVERSED does not mean the reversal succeeded. On the merchant-notification channel, a failed reversal also arrives as status: REVERSED — the reason is in bankResponse. Always check bankResponse rather than treating REVERSED as confirmation. On the transaction-webhook channel the distinction is visible directly in status, which reports END_REVERSED or END_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 a 200 from 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

ParamWhereRequiredDetail
transactionIdPath✓The original transaction's Scan to Pay ID
amountBody✓The amount to refund. Up to the original transaction amount. Partial refunds allowed for credit/cheque cards.
webhookBodyoptionalDestination 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):

statusMeaning
REVERSEDReversal completed
REFUNDEDRefund 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):

statusMeaning
END_REFUNDEDRefund succeeded
END_REFUND_FAILEDThe bank declined the refund — check bankResponse for the ISO code
END_BANK_ERRORThe bank returned an invalid or unreadable response
END_BANK_OFFLINEThe bank could not be reached — transient, safe to retry
END_SYSTEM_ERRORInternal 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 / codeMeaning
444 NOTHING_TO_REVERSEThe transaction can't be reversed (already reversed, already refunded, or outside the bank's window)
514 UNABLE_TO_REVERSEThe reversal was attempted but failed at the bank
515 UNABLE_TO_REFUNDThe refund was attempted but failed (different card type, already fully refunded, outside acquirer window)
445 INVALID_CLIENT_CARDAttempting to refund a debit card — not allowed per PASA
432 INVALID_AMOUNTRefund amount exceeds the remaining refundable balance, or is zero/negative
436 INVALID_TRANSACTION_REFThe transactionId doesn't match any known transaction

Full error reference: Errors.


What's next


Did this page help you?