Webhooks
How Scan to Pay notifies your backend when a transaction reaches a terminal state — payload, acknowledgement, retries, and recovery.
A webhook is the server-to-server notification that Scan to Pay sends to your backend when a transaction reaches a terminal state — SUCCESS, CLIENT_CANCEL, BANK_REJECTED, REVERSED, and so on. Webhooks are the primary way you learn about payments. If you don't configure one, you'll have to poll instead — and the two methods are mutually exclusive.
This page covers everything you need to receive, acknowledge, and recover webhooks. For signature decryption code samples, see Signing and verifying webhooks.
Two delivery channels — know which one you're on
The platform has two independent server-to-server delivery channels, and integrators routinely confuse them because both are called "webhooks". They carry different payloads, use different acknowledgement rules, and go to different endpoints. A single transaction can trigger both.
| Merchant notifications | Transaction webhooks | |
|---|---|---|
| Most of this page describes | ✅ | see Refund webhooks |
| URL is configured | On the Portal, per merchant profile | Per transaction — on the Remote API /generateTransactionId or /purchaseTx call, at wallet registration, or on the refund request |
| Payload | Base64-encoded and encrypted | Plain JSON, wrapped in a { type, typeValue, message } envelope |
status values | Rolled-up — SUCCESS, REFUNDED, BANK_REJECTED … | More granular — END_REFUNDED, END_REFUND_FAILED … |
| You must reply | HTTP 200 within 45 seconds | HTTP 200 — any other code is a failure |
| If you don't | The transaction is reversed | Retried up to 9 times, then abandoned |
| Delivery timeouts | 45 s | 2 s connect / 3 s read |
How the two channels interact on one transaction.If the merchant has an HTTP notification method configured on the Portal, the encrypted merchant notification is delivered first. A transaction webhook registered on the same transaction (for example by a wallet on the Remote API) is sent only after the merchant notification succeeds. If the merchant notification fails for a successful payment, the payment is reversed and the transaction webhook is not sent at that point.
Only the merchant notification can cause a reversal. A transaction webhook that is not acknowledged is retried and then abandoned; it never reverses the payment.
If you're unsure which one you're on: if you were given a notification decryption key, you're on merchant notifications. If your payloads arrive as readable JSON, you're on transaction webhooks.
How it works
- You register a notification URL on the Scan to Pay Portal against your merchant profile, and generate a notification key.
- A customer completes a payment.
- Scan to Pay schedules an automatic reversal job for the transaction before notifying you. This is the safety net — if you don't acknowledge, the transaction is reversed.
- Scan to Pay HTTP-POSTs the encrypted payload to your notification URL.
- Your handler decrypts the payload, processes it, and returns
HTTP 200within the acknowledgement window. - The reversal job is cancelled. The transaction settles normally.
- If your handler returns any non-200 status, times out, or never receives the request, the reversal job fires and the transaction is reversed.
The model is fail-safe: the platform reverses unless you explicitly confirm receipt.
You cannot use webhooks AND polling.Setting a notification URL disables
queryReffor the merchant — it returnsHTTP 406 Not Acceptable. Pick one. For production, webhooks are recommended; polling is a fallback for integrators that can't expose a public HTTPS endpoint.
Register your endpoint
In the Scan to Pay Portal — sandbox or production:
- Log in as the merchant administrator.
- Open the email dropdown (top right) → Notifications.
- Add your HTTP notification URL. It must be HTTPS-capable and reachable from the public internet.
- Generate a notification decryption key on the same page. Store this key securely — you'll use it on every incoming webhook.
- Press Check to send a test unencrypted JSON payload (
{ "result": "TEST" }) so you can verify your endpoint is reachable before going live.
Allowed URL ports
Your notification URL must use one of these TCP ports:
| Port | Use |
|---|---|
| 443 | Standard HTTPS (recommended) |
| 8443 | HTTPS on alternate port |
| 80 | Plain HTTP — sandbox only, never use in production |
| 8080 | Plain HTTP on alternate port — sandbox only |
Network whitelisting
If your firewall, reverse proxy, or web application firewall restricts incoming connections, whitelist the Scan to Pay public source IPs below so webhook notifications can reach your endpoint. Add every IP for the environment you use; production notifications can originate from any of the four production addresses.
| Environment | Public source IP |
|---|---|
| Sandbox (QA) | 13.245.106.90 |
| Production | 13.245.54.149 |
| Production | 13.246.167.191 |
| Production | 13.244.199.225 |
| Production | 13.245.87.168 |
Sandbox uses the QA environment at qa.scantopay.io. If your firewall requires CIDR notation, add each address as an individual /32 entry.
These are source IPs for traffic from Scan to Pay to your endpoint. Continue to use the documented API hostnames for requests to Scan to Pay, and keep notification verification enabled alongside the IP allowlist.
If you suspect a delivery was blocked — no notification arrived for a transaction you expected, no entry in your handler logs — contact support with the transaction ID.
Payload structure
The webhook body is base64-encoded ciphertext. Decode it, then decrypt with your notification key — see Signing and verifying webhooks for the exact decryption code. The decrypted payload is a JSON object with this shape:
{
"transactionId": 81234,
"merchantId": 25,
"merchantName": "Acme Coffee",
"acquirer": "ABSA",
"reference": "demo-order-001",
"amount": 10.00,
"currencyCode": "ZAR",
"code": "0123456789",
"status": "SUCCESS",
"clientMsisdn": "27831234567",
"destination": "27821111111",
"extraReferenceName": null,
"extraReferenceValue": null,
"tipAmount": null,
"referenceTransactionId": 0,
"bankResponse": {
"retrievalReferenceNumber": 6321400012,
"authCode": "123456",
"bankResponse": "00",
"bankResponseMessage": "Approved"
},
"cardInfo": {
"cardType": "VISA",
"accountType": "CREDIT",
"cardHolderName": "J SMITH",
"bin": "411111",
"last4": "1234",
"binLast4": "411111-1234",
"cardIssuer": "ABSA"
},
"clientContact": {
"firstName": "James",
"lastName": "Smith",
"emailAddress": "[email protected]",
"phoneNumber": "27831234567",
"country": "ZA"
},
"clientBilling": null,
"clientShipping": null,
"versionData": {
"version": "1"
}
}Field reference
| Field | Type | Always present | Description |
|---|---|---|---|
transactionId | long | ✓ | Scan to Pay's internal transaction ID. Use this when calling getNotification to re-fetch. |
merchantId | long | ✓ | Your merchant ID — useful for multi-merchant integrators. |
merchantName | string | ✓ | Your registered merchant name. |
acquirer | string | ✓ | The acquiring bank that processed this transaction. |
reference | string | ✓ | Your merchantReference from the original createCode call. Use this to join the notification to your order record. |
amount | decimal | ✓ | Transaction amount in currencyCode. |
currencyCode | string | ✓ | ISO 4217 currency code (e.g. ZAR). |
code | string | ✓ for code purchases | The 10-digit QR code value, if this was a code-based purchase. |
status | enum | ✓ | The notification status — see the table below. Different from the transaction state. |
clientMsisdn | string | ✓ | Customer's mobile number in international format. |
destination | string | optional | Destination MSISDN for airtime / VAS purchases. |
extraReferenceName / extraReferenceValue | string | optional | Extra reference fields supplied at create-code time. |
tipAmount | decimal | optional | Tip portion, if requestTip was set on the code. |
referenceTransactionId | long | ✓ for refunds/reversals | Links a refund or reversal notification back to the original transaction. |
bankResponse | object | ✓ | Acquiring-bank response details (see below). |
cardInfo | object | ✓ | Tokenised card information (BIN + last 4 only — never the full PAN). |
clientContact | object | optional | Customer contact info, if the code requested it. |
clientBilling / clientShipping | object | optional | Customer addresses, if requested. |
versionData | object | ✓ | Versioning envelope. Defaults to {"version": "1"}. |
bankResponse object
bankResponse object| Field | Description |
|---|---|
retrievalReferenceNumber | The bank's RRN. Useful for reconciliation against your acquirer statement. |
authCode | Authorisation code from the issuer. |
bankResponse | ISO response code (e.g. 00, 51, 91). See ISO response codes. |
bankResponseMessage | Human-readable explanation of the bank response. |
cardInfo object
cardInfo object| Field | Description |
|---|---|
cardType | VISA, MASTERCARD, AMEX, DINERS, etc. |
accountType | DEBIT, CREDIT, or CHEQUE. |
cardHolderName | As registered with the issuer. |
bin | First 6 digits of the card. |
last4 | Last 4 digits. |
binLast4 | Convenience field: {bin}-{last4}. |
cardIssuer | The issuing bank. |
Notification status values
The status field is deliberately simpler than the full set of transaction states returned by queryRef — it rolls those up into a smaller vocabulary intended for merchant consumption.
status | Meaning |
|---|---|
SUCCESS | Payment completed successfully. Settle the order. |
CLIENT_CANCEL | Customer cancelled before authorising. Treat as abandoned. |
CLIENT_TIMEOUT | Customer didn't complete in time. Treat as abandoned. |
BANK_OFFLINE | Couldn't reach the bank. Transient — customer can retry. |
BANK_REJECTED | Bank declined. Customer can retry with a different card. |
TRANSACTION_REJECTED | Platform rejected before reaching the bank (validation, limit, fraud). |
SYSTEM_ERROR | Internal Scan to Pay error. Investigate via support. |
REVERSED | Original transaction was reversed (look at referenceTransactionId). |
REFUNDED | Full or partial refund completed. |
LIMIT_FAILED | Failed a TPE or merchant limit check. |
HASH_CHECK_FAILED / HASH_CHECK_MISSING | Card-link hash validation failed. |
BANK_PAYMENT_CANCELLATION | Bank cancelled the payment after authorisation. |
DO_NOT_TRY_AGAIN | Issuer declined permanently — do not retry. |
TRY_AGAIN_AFTER_X_HRS | Issuer rate-limited — retry later. |
CARD_EXPRIY_NOT_ALLOWED | Card expiry rejected by merchant or scheme. |
INTERNATIONAL_BIN_NOT_ALLOWED | International card rejected by merchant configuration. |
BIN_CLASSIFICATION_NOT_ALLOWED | Card BIN classification not permitted. |
TIMEOUT_* (15 variants) | WIG / USSD flow-step timeouts. See Transaction states for the equivalent transaction-state mapping. |
FAILED | Generic external-notification failure (reserved). |
Notification status vs transaction stateIf you also use
queryRefor examine transactions in the Admin Portal, you'll see more detailed transaction states such asEND_BANK_NON_00. The webhook rolls these up into the smaller set of statuses above. For example,END_BANK_NON_00,END_BANK_DECLINE, andEND_INSUFFICIENT_FUNDS_OR_OVER_CREDIT_LIMITall surface asBANK_REJECTEDin the notification. Use the Transaction states page when you need the underlying state.
Acknowledging the webhook
Your handler must return HTTP 200 within the acknowledgement window. The body of your response is ignored — what matters is the status code.
| Your response | What Scan to Pay does |
|---|---|
HTTP 200 (any body) | Cancels the scheduled reversal. Transaction settles normally. |
| Any non-200 | Lets the scheduled reversal job fire. Transaction is reversed. |
| No response (connection error, timeout) | Same as non-200 — reversal fires. |
The acknowledgement window is 45 seconds. If your handler takes longer than that, the reversal runs.
Acknowledge first, process asynchronously. The reversal safety net is aggressive. Have your handler:
- Verify the source and decrypt the payload.
- Persist the raw notification to a queue or table.
- Return
HTTP 200immediately.- Process the notification (update order, send email, fulfil) on a background worker.
If your synchronous business logic ever takes longer than 45 seconds, the transaction will reverse out from under you.
Recovery — re-fetching missed notifications
If your handler missed a delivery — outage, deploy gone wrong, network blip — you can pull the notification back manually using the getNotification endpoint.
curl -u "$USERNAME:$PASSWORD" \
https://qa.scantopay.io/pluto/purchase/notification/81234Response is the same payload the webhook would have delivered, but unencrypted. The endpoint is locked per transaction, so it's safe to call concurrently.
Calling getNotification for a successful transaction that hasn't yet been acknowledged also cancels the reversal job — it's effectively the same as a webhook ack. Use this as your recovery path: scan your order DB for "payment expected, no notification received" cases and pull them.
Refund webhooks
Refunds are delivered on the transaction-webhook channel described in Two delivery channels — not the encrypted merchant notification channel. Everything above about decryption keys, the 45-second window and the reversal safety net does not apply here.
Choosing where the refund notification goes
Both refund endpoints accept an optional webhook field in the request body:
curl -X POST "https://qa.scantopay.io/pluto/purchase/refund/{transactionId}" \
-u "$USERNAME:$PASSWORD" \
-H 'Content-Type: application/json' \
-d '{
"amount": 50.00,
"webhook": "https://mydomain.com/mywallet/refund-webhook"
}'| Field | Type | Required | Detail |
|---|---|---|---|
amount | decimal | ✓ | Amount to refund, up to the original transaction amount |
webhook | string | optional | Destination for this refund's outcome notification. Max 2048 characters. |
If you omit webhook (or send null/empty), the refund inherits the original transaction's webhook URL and payload version. This is the pre-existing behaviour and remains the default.
If you supply webhook, it overrides the inherited URL for this refund only. The payload version is still inherited from the original transaction; if the original has no webhook registered, version 1 is used.
The same field works on the synchronous /doRefund/{transactionId} endpoint.
Multiple destinations. A webhook value may contain several URLs separated by|. Each one receives its own delivery and its own retry schedule.
Validation
The supplied value is parsed as a URI. If it can't be parsed — whitespace-only, spaces in the value, a malformed scheme — the request is rejected with error code 461 INVALID_REQUEST and the message Invalid webhook, must be a valid URL.
Validation is syntactic only. There is no scheme or host allow-list, so plainhttp://URLs and bare tokens are accepted. Always supply an HTTPS URL on a host you control. Payloads on this channel are not encrypted and not signed — see Securing your receiver below.
Refund payload
Sent as plain JSON inside an envelope. The envelope's type is TX and typeValue is the refund transaction's ID:
{
"transactionId": 6489130,
"originalTransactionId": 6481694,
"reference": "INV-4242",
"amount": 50.00,
"currencyCode": "710",
"code": null,
"status": "END_REFUNDED",
"clientMsisdn": "27820000000",
"clientIdentifier": "abc-123",
"retrievalReferenceNumber": 123456789012,
"authCode": "123456",
"bankResponse": "00",
"date": "2026-07-20 11:42:26",
"merchantName": "Demo Store",
"source": "NEDBANK",
"tipAmount": null
}| Field | Type | On refunds |
|---|---|---|
transactionId | long | The refund transaction's ID — not the original |
originalTransactionId | long | The original purchase ID. Use this to reconcile. |
amount | decimal | Amount refunded on this call, not the cumulative total |
status | string | The refund's outcome — see the table below |
code | string | null — a refund has no QR code of its own |
subMerchantName | string | null on refunds |
bankResponse / authCode / retrievalReferenceNumber | — | The acquirer's response to the refund, not the original purchase |
Payload version 2 adds bankResponseMessage and cardIssuer; version 4 additionally carries extraBankResponseDetails. Your version is inherited from the original transaction.
Refund status values
This channel reports the outcome in more detail than the rolled-up values used on the merchant-notification channel, so refund failures are distinguishable from one another. A refund can terminate in any of:
status | Meaning |
|---|---|
END_REFUNDED | Refund succeeded. Bank returned 00. |
END_REFUND_FAILED | The bank declined the refund. Inspect bankResponse for the ISO code. |
END_BANK_ERROR | The bank returned an unreadable or invalid response. |
END_BANK_OFFLINE | The bank could not be reached. Transient — safe to retry the refund. |
END_SYSTEM_ERROR | Internal platform error before the refund reached the bank. |
Map these to customer-facing copy yourself — never display a raw status value to a customer.
Acknowledgement and retries
Your endpoint must return exactly HTTP 200. Note that 201, 202 and 204 all count as failures on this channel.
| Attempt | Delay before it |
|---|---|
| 1 | immediate |
| 2–10 | roughly 1 s, 2 s, 3 s … up to 9 s (linear back-off) |
After 9 retries the delivery is abandoned. Unlike the merchant-notification channel, a failed refund webhook does not reverse anything — the refund has already happened at the bank. You'll need to reconcile manually.
Timeouts are tight: 2 seconds to connect, 3 seconds to read. Acknowledge immediately and do your processing asynchronously.
Securing your receiver
This channel has no HMAC and no signature header. Anyone who learns your URL can post a convincing fake refund notification. Mitigate by:
- Using an unguessable path segment in the webhook URL
- Restricting the endpoint to Scan to Pay's outbound IPs (see Network whitelisting)
- Confirming every refund out-of-band before acting on it — call
queryRefundor the transaction lookup with theoriginalTransactionIdrather than trusting the payload - Treating the payload as PII: it carries MSISDN, merchant reference, RRN and auth code
If your integration requires signed payloads, raise it with your account manager — the encrypted merchant-notification channel is the supported alternative.
Other notification channels
The platform supports three notification methods:
| Method | What it sends | When to use |
|---|---|---|
| HTTP (webhook) | The full transaction payload, encrypted | All production integrations |
| Human-readable summary of the transaction | Operational notifications, not for automated processing | |
| SMS | Brief SMS summary | Low-stakes confirmations |
You can configure any combination of the three in the portal. HTTP is the only channel that triggers the reversal-on-failure safety net — email and SMS deliveries are best-effort and don't affect transaction state.
Test your endpoint
In the sandbox, use the Check button on the Portal notifications page to send a probe:
{ "result": "TEST" }This is sent unencrypted to your URL. Verify your handler:
- Receives the POST
- Returns HTTP 200
- Logs the payload
Once that works, run a full sandbox transaction (see Quickstart) and verify your handler:
- Receives the encrypted production-shape payload
- Decrypts it correctly with your sandbox notification key
- Returns 200 within 45 seconds
- Records the order in your system
Best practices
- Verify before you trust. Decrypt with your notification key. If decryption fails, your payload is fake (or you have the wrong key) — never trust the body.
- Be idempotent. Scan to Pay won't deliberately send the same webhook twice, but operational reality (replays after a failed ack, intermediary retries) can produce duplicates. Treat
transactionIdas the dedup key. - Don't display raw
statusvalues to end customers. MapBANK_REJECTEDto "Sorry, your card was declined" before showing it to humans. - Watch for
REVERSEDnotifications on transactions you thought succeeded. This is how you learn your handler ack'd too late. Tune your handler latency until you stop seeing them. - Whitelist Scan to Pay's outbound IPs in your network — see Network whitelisting above.
- Never log the decrypted payload to plaintext logs. It contains MSISDN, card BIN/last4, and cardholder name. Treat as PII.
What's next
- Decryption code samples → Signing and verifying webhooks
- Issue the refund that triggers a refund webhook → Refunds and reversals
- Full status reference and transaction-state mapping → Transaction states
- Map bank decline codes to customer-facing copy → ISO response codes
- Configure webhook URL programmatically → Portal API → Notifications
- First-time setup walkthrough → Quickstart
- Going live checklist → Going live
Updated 6 days ago
