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 notificationsTransaction webhooks
Most of this page describes✅see Refund webhooks
URL is configuredOn the Portal, per merchant profilePer transaction — on the Remote API /generateTransactionId or /purchaseTx call, at wallet registration, or on the refund request
PayloadBase64-encoded and encryptedPlain JSON, wrapped in a { type, typeValue, message } envelope
status valuesRolled-up — SUCCESS, REFUNDED, BANK_REJECTED …More granular — END_REFUNDED, END_REFUND_FAILED …
You must replyHTTP 200 within 45 secondsHTTP 200 — any other code is a failure
If you don'tThe transaction is reversedRetried up to 9 times, then abandoned
Delivery timeouts45 s2 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

  1. You register a notification URL on the Scan to Pay Portal against your merchant profile, and generate a notification key.
  2. A customer completes a payment.
  3. 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.
  4. Scan to Pay HTTP-POSTs the encrypted payload to your notification URL.
  5. Your handler decrypts the payload, processes it, and returns HTTP 200 within the acknowledgement window.
  6. The reversal job is cancelled. The transaction settles normally.
  7. 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 queryRef for the merchant — it returns HTTP 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:

  1. Log in as the merchant administrator.
  2. Open the email dropdown (top right) → Notifications.
  3. Add your HTTP notification URL. It must be HTTPS-capable and reachable from the public internet.
  4. Generate a notification decryption key on the same page. Store this key securely — you'll use it on every incoming webhook.
  5. 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:

PortUse
443Standard HTTPS (recommended)
8443HTTPS on alternate port
80Plain HTTP — sandbox only, never use in production
8080Plain 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.

EnvironmentPublic source IP
Sandbox (QA)13.245.106.90
Production13.245.54.149
Production13.246.167.191
Production13.244.199.225
Production13.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

FieldTypeAlways presentDescription
transactionIdlong✓Scan to Pay's internal transaction ID. Use this when calling getNotification to re-fetch.
merchantIdlong✓Your merchant ID — useful for multi-merchant integrators.
merchantNamestring✓Your registered merchant name.
acquirerstring✓The acquiring bank that processed this transaction.
referencestring✓Your merchantReference from the original createCode call. Use this to join the notification to your order record.
amountdecimal✓Transaction amount in currencyCode.
currencyCodestring✓ISO 4217 currency code (e.g. ZAR).
codestring✓ for code purchasesThe 10-digit QR code value, if this was a code-based purchase.
statusenum✓The notification status — see the table below. Different from the transaction state.
clientMsisdnstring✓Customer's mobile number in international format.
destinationstringoptionalDestination MSISDN for airtime / VAS purchases.
extraReferenceName / extraReferenceValuestringoptionalExtra reference fields supplied at create-code time.
tipAmountdecimaloptionalTip portion, if requestTip was set on the code.
referenceTransactionIdlong✓ for refunds/reversalsLinks a refund or reversal notification back to the original transaction.
bankResponseobject✓Acquiring-bank response details (see below).
cardInfoobject✓Tokenised card information (BIN + last 4 only — never the full PAN).
clientContactobjectoptionalCustomer contact info, if the code requested it.
clientBilling / clientShippingobjectoptionalCustomer addresses, if requested.
versionDataobject✓Versioning envelope. Defaults to {"version": "1"}.

bankResponse object

FieldDescription
retrievalReferenceNumberThe bank's RRN. Useful for reconciliation against your acquirer statement.
authCodeAuthorisation code from the issuer.
bankResponseISO response code (e.g. 00, 51, 91). See ISO response codes.
bankResponseMessageHuman-readable explanation of the bank response.

cardInfo object

FieldDescription
cardTypeVISA, MASTERCARD, AMEX, DINERS, etc.
accountTypeDEBIT, CREDIT, or CHEQUE.
cardHolderNameAs registered with the issuer.
binFirst 6 digits of the card.
last4Last 4 digits.
binLast4Convenience field: {bin}-{last4}.
cardIssuerThe 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.

statusMeaning
SUCCESSPayment completed successfully. Settle the order.
CLIENT_CANCELCustomer cancelled before authorising. Treat as abandoned.
CLIENT_TIMEOUTCustomer didn't complete in time. Treat as abandoned.
BANK_OFFLINECouldn't reach the bank. Transient — customer can retry.
BANK_REJECTEDBank declined. Customer can retry with a different card.
TRANSACTION_REJECTEDPlatform rejected before reaching the bank (validation, limit, fraud).
SYSTEM_ERRORInternal Scan to Pay error. Investigate via support.
REVERSEDOriginal transaction was reversed (look at referenceTransactionId).
REFUNDEDFull or partial refund completed.
LIMIT_FAILEDFailed a TPE or merchant limit check.
HASH_CHECK_FAILED / HASH_CHECK_MISSINGCard-link hash validation failed.
BANK_PAYMENT_CANCELLATIONBank cancelled the payment after authorisation.
DO_NOT_TRY_AGAINIssuer declined permanently — do not retry.
TRY_AGAIN_AFTER_X_HRSIssuer rate-limited — retry later.
CARD_EXPRIY_NOT_ALLOWEDCard expiry rejected by merchant or scheme.
INTERNATIONAL_BIN_NOT_ALLOWEDInternational card rejected by merchant configuration.
BIN_CLASSIFICATION_NOT_ALLOWEDCard BIN classification not permitted.
TIMEOUT_* (15 variants)WIG / USSD flow-step timeouts. See Transaction states for the equivalent transaction-state mapping.
FAILEDGeneric external-notification failure (reserved).
📘

Notification status vs transaction state

If you also use queryRef or examine transactions in the Admin Portal, you'll see more detailed transaction states such as END_BANK_NON_00. The webhook rolls these up into the smaller set of statuses above. For example, END_BANK_NON_00, END_BANK_DECLINE, and END_INSUFFICIENT_FUNDS_OR_OVER_CREDIT_LIMIT all surface as BANK_REJECTED in 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 responseWhat Scan to Pay does
HTTP 200 (any body)Cancels the scheduled reversal. Transaction settles normally.
Any non-200Lets 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:

  1. Verify the source and decrypt the payload.
  2. Persist the raw notification to a queue or table.
  3. Return HTTP 200 immediately.
  4. 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/81234

Response 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"
  }'
FieldTypeRequiredDetail
amountdecimal✓Amount to refund, up to the original transaction amount
webhookstringoptionalDestination 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 plain http:// 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
}
FieldTypeOn refunds
transactionIdlongThe refund transaction's ID — not the original
originalTransactionIdlongThe original purchase ID. Use this to reconcile.
amountdecimalAmount refunded on this call, not the cumulative total
statusstringThe refund's outcome — see the table below
codestringnull — a refund has no QR code of its own
subMerchantNamestringnull 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:

statusMeaning
END_REFUNDEDRefund succeeded. Bank returned 00.
END_REFUND_FAILEDThe bank declined the refund. Inspect bankResponse for the ISO code.
END_BANK_ERRORThe bank returned an unreadable or invalid response.
END_BANK_OFFLINEThe bank could not be reached. Transient — safe to retry the refund.
END_SYSTEM_ERRORInternal 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.

AttemptDelay before it
1immediate
2–10roughly 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 queryRefund or the transaction lookup with the originalTransactionId rather 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:

MethodWhat it sendsWhen to use
HTTP (webhook)The full transaction payload, encryptedAll production integrations
EmailHuman-readable summary of the transactionOperational notifications, not for automated processing
SMSBrief SMS summaryLow-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:

  1. Receives the POST
  2. Returns HTTP 200
  3. Logs the payload

Once that works, run a full sandbox transaction (see Quickstart) and verify your handler:

  1. Receives the encrypted production-shape payload
  2. Decrypts it correctly with your sandbox notification key
  3. Returns 200 within 45 seconds
  4. 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 transactionId as the dedup key.
  • Don't display raw status values to end customers. Map BANK_REJECTED to "Sorry, your card was declined" before showing it to humans.
  • Watch for REVERSED notifications 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


Did this page help you?