Scan to Pay
Status, Events & Errors
Track Scan to Pay results through WebSocket, push and transaction history, and handle error codes.
How the App Learns the Final Result
| Channel | When | What to do |
|---|---|---|
WebSocket EXTERNAL_TRANSFER_STATUS | Every status change (success, failure, refund, review hold) | Call GET /api/v2/external-transfers/{uuid} and refresh the screen |
| Push notification | Final SUCCESS or FAILED (after refund) | Open the transfer / history detail |
Polling GET /api/v2/external-transfers/{uuid} | Fallback when WebSocket is not connected | Stop on SUCCESS / FAILED |
WebSocket Event
Connect to GET /api/v2/ws as described on the WebSocket page.
Scan to Pay updates arrive on channel external_transfer.events:
{
"event": "EXTERNAL_TRANSFER_STATUS",
"channel": "external_transfer.events",
"data": {
"mobile_user_id": 10001,
"event_type": "EXTERNAL_TRANSFER_STATUS",
"transfer_uuid": "8f6a3c1e-2b4d-4f7a-9c1e-5d2b7a9e0f13"
}
}
The event carries no status — it is a signal. Read the transfer with transfer_uuid to get
the current status / display_status.
Push Notifications
| Result | Title (en) | Title (zh) |
|---|---|---|
| Success | Transfer Successful | 转账成功 |
| Failed (refunded) | Transfer Failed | 转账失败 |
Push is best-effort; always confirm through the API.
Transaction History
External transfers appear in the user's wallet / transaction history (Transactions):
transaction_type | Direction | Amount | Status |
|---|---|---|---|
EXTERNAL_TRANSFER | OUT | debit_amount USDT (with MYR amount and USDT fee) | PENDING → SUCCESS / FAILED |
EXTERNAL_TRANSFER_REFUND | IN | Full debit_amount USDT returned | SUCCESS |
- Order IDs are
EXT-{uuid}for the payment andEXT-{uuid}-REFUNDfor the refund. reference_idon both rows is the transferid.- When the transfer has
sub_statusMANUAL_REVIEW, the history detail showsMANUAL_REVIEWas its status.
Lifecycle
| Path | What happens |
|---|---|
| paid out | The provider confirms the payout (callback or status sync). Final SUCCESS. |
| payout failed | The provider reports a definite failure. The full debit_amount (fee included) is refunded to the same wallet, then the transfer becomes FAILED. |
| quote expired before submit | The wallet was debited, but the payout could not be submitted before the provider quote expired. Nothing was sent, so it is refunded the same way as a failure. |
| outcome unknown | The submission result is unknown (timeout, no order number). The money stays held and the transfer stays PROCESSING with sub_status MANUAL_REVIEW until the provider callback, a status sync or an investigation resolves it. |
| provider review | The provider has put the payout under manual review. Still PROCESSING, sub_status MANUAL_REVIEW. |
| never confirmed | The quote expires. No status change, nothing debited, no history row. |
- Conflicting provider results (for example a failure reported after a success) put the transfer on
hold: its
statusstays as it is andsub_statusbecomesMANUAL_REVIEW. You can therefore seeSUCCESSorFAILEDtogether withMANUAL_REVIEW; treat it as "under review". - An abandoned
PENDINGquote currently returnsdisplay_statusPROCESSINGfromGET /external-transfers/{uuid}. Usequote_expires_atandconfirmed_at: nullto show it as expired in the app. - A refund that cannot complete stays
FUND_REVERSAL_FAILEDand is retried automatically. - The server re-checks stuck
PROCESSINGtransfers and retries owed refunds every 10 minutes, for up to 48 hours after creation. After that, the transfer is left for the operations team to investigate; it is never auto-refunded or resubmitted without proof the payout failed.
Error Format
Errors use the standard envelope with a machine-readable error_code. Branch on error_code;
display message (localized by Accept-Language).
{
"trace_id": "2a6d1a45d8c9402d",
"status_code": 400,
"message": "Insufficient Balance",
"error_code": "INSUFFICIENT_BALANCE",
"data": null
}
As described in the overview, check status_code in the body.
Error Codes
error_code | status_code | Route | Meaning / app action |
|---|---|---|---|
INVALID_QR | 400 | quote | QR is not a valid supported QR. Ask the user to rescan. |
INVALID_CURRENCY | 400 | quote | QR currency is not supported (only MYR). |
TRANSFER_AMOUNT_BELOW_MINIMUM | 400 | quote | Amount below 1.00 MYR. |
TRANSFER_AMOUNT_ABOVE_MAXIMUM | 400 | quote | Amount above the maximum (none configured today). |
QR_AMOUNT_MISMATCH | 400 | quote | Amount differs from the amount inside a dynamic QR. |
WALLET_NOT_FOUND | 400 | quote, confirm | User has no USDT wallet. Guide them to create / top up one. |
WALLET_UNAVAILABLE | 400 | quote, confirm | Wallet is not ACTIVE (e.g. frozen) or not USDT. |
INSUFFICIENT_BALANCE | 400 | quote, confirm | Balance does not cover principal + fee. |
EXCHANGE_RATE_MISSING | 400 | quote | Rates unavailable. Retry later. |
QUOTE_EXPIRED | 400 | confirm | Quote expired before confirm. Create a new quote. |
WALLET_DEBIT_FAILED | 500 | confirm | Debit rolled back; nothing was charged. Safe to retry confirm. |
EXTERNAL_TRANSFER_DISABLED | 503 | quote, confirm | Feature switched off on the server. Show "temporarily unavailable". |
Other failures (no error_code):
status_code | When |
|---|---|
| 400 | Request validation failed (missing qr_content / amount, remark > 255), or uuid is not a valid UUID |
| 404 | Transfer not found or not owned by the current user |
| 502 | Provider quote failed, or the payout service could not be reached — retry the quote |
| 429 | Rate limit (60 / minute / IP) exceeded on quote or confirm |
Integration Checklist
- Scan →
POST /qr/check; continue only whentypeisEXTERNAL_TRANSFER. - Lock the amount when the QR carries one; otherwise enforce ≥
1.00with 2 decimals. - Quote → show merchant, MYR amount, fee, total USDT debit, rate and a countdown to
quote_expires_at. - Confirm → treat any
200as "processing", not "paid". - Retry confirm on timeouts with the same
uuid— it never double-charges. - Finish on
display_statusSUCCESS/FAILEDfrom the WebSocket-triggered read or polling. - Show
MANUAL_REVIEWas "under review", not as a failure.