Merchant query resolution
How merchants raise and resolve operational queries with their acquirer and the Scan to Pay Operations team.
A merchant query is any operational issue a merchant raises after they've gone live — a transaction that didn't reconcile, a webhook that never arrived, a customer complaint about a charge they don't recognise, a portal access problem. This page documents the standard process for getting those queries resolved.
This is different from Customer disputes, which is the cardholder-initiated process flowing through banks. Merchant queries are merchant-initiated and typically operational rather than financial.
For the rules of the process, see Query resolution — business rules.
When to use this process
| Query type | Where to start |
|---|---|
| Transaction succeeded but no webhook received | Webhooks recovery section first, then Support if unresolved |
| Webhook decryption failing | Signing and verifying webhooks troubleshooting, then Support |
| API password lost / locked out | Admin Portal login recovery section |
| Customer claims they paid but you have no record | Use Querying transactions; if still missing, [email protected] |
| Settlement amount doesn't match your transaction total | Acquiring bank (the merchant's bank, not Scan to Pay) |
| Recurring system issue affecting many transactions | [email protected] immediately |
| Account billing / commercial dispute | Your account manager or [email protected] |
| Cardholder fraud claim | This is a Customer dispute, not a merchant query |
The first step is usually to self-diagnose using the docs and APIs. If you can't resolve it, escalate to the right support team — see Support.
Standard query process
- Self-diagnose using the relevant Platform documentation (Webhooks, Errors, Transaction states, Querying transactions).
- Gather evidence —
transactionId,merchantReference, the exact error message or unexpected behaviour, screenshots if relevant. The Support page request template lists what to include. - Open a ticket via the support portal or email the right channel (operational queries →
[email protected]; live incidents →[email protected]). - Receive a case reference by reply email. Keep the subject line intact on follow-ups.
- Provide additional info as the support team investigates.
- Receive resolution — explanation, fix, or routing to the right party if the issue is with your acquirer rather than Scan to Pay.
Response times depend on priority. See Support — Priority levels and response times.
Query types and likely root cause
| Symptom | Likely cause | First check |
|---|---|---|
| Transaction missing from your reconciliation | Webhook missed or your handler errored | getTransactionState lookup by transactionId |
| Customer reports successful payment but you didn't get a webhook | Webhook handler returned non-200; transaction auto-reversed | Inspect your webhook receiver logs around that timestamp |
You see a REVERSED you didn't trigger | Same as above — auto-reversal due to missed webhook ack | Inspect 45-second-window violations |
| Webhook arrives but decryption fails | Notification key drift between Scan to Pay and your system | Regenerate the key in Portal; redeploy |
| Customer paid with debit card; can't refund | PASA rule — debit cards can't be refunded. Use reversal if within window, or EFT manually | Refunds and reversals |
| API password "stopped working" | Someone (you or a teammate) rotated it without coordinating the deploy | Regenerate and update your config |
Transaction stuck in OFF_TO_BANK for hours | Bank-side delay or platform issue | Escalate to system support; provide transactionId |
The patterns repeat — almost every operational query traces back to webhook acknowledgement, credential rotation, or bank communication. The platform's webhook reversal safety net and credential-rotation rules cause more support tickets than anything else.
Escalation
If a query isn't resolved in the time the priority allows (see Support) or you believe it's been deprioritised incorrectly:
- Reply on the existing ticket asking for escalation
- CC [email protected]
- For P1 (critical, transaction-blocking) issues, call +27 10 449 1784 directly — phone is fastest for P1/P2
Don't open a duplicate ticket; that splits the conversation and slows resolution.
What's next
- The rules governing this process → Query resolution — business rules
- Support contacts and SLAs → Support
- Recover a missed webhook → Webhooks
- Look up transaction details for an investigation → Querying transactions
- Customer-initiated disputes (different process) → Customer disputes
Updated 3 days ago