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

ChannelWhenWhat to do
WebSocket EXTERNAL_TRANSFER_STATUSEvery status change (success, failure, refund, review hold)Call GET /api/v1/external-transfers/{uuid} and refresh the screen
Push notificationFinal SUCCESS or FAILED (after refund)Open the transfer / history detail
Polling GET /api/v1/external-transfers/{uuid}Fallback when WebSocket is not connectedStop on SUCCESS / FAILED

WebSocket Event

Connect to GET /api/v1/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

ResultTitle (en)Title (zh)
SuccessTransfer 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_typeDirectionAmountStatus
EXTERNAL_TRANSFEROUTdebit_amount USDT (with MYR amount and USDT fee)PENDING → SUCCESS / FAILED
EXTERNAL_TRANSFER_REFUNDINFull debit_amount USDT returnedSUCCESS
  • Order IDs are EXT-{uuid} for the payment and EXT-{uuid}-REFUND for the refund.
  • reference_id on both rows is the transfer id.
  • When the transfer has sub_status MANUAL_REVIEW, the history detail shows MANUAL_REVIEW as its status.

Lifecycle

Scan to Pay lifecycle: scan the QR, create a quote (PENDING), confirm to debit the wallet (PROCESSING). PROCESSING ends in SUCCESS when paid out, or in FUND_REVERSAL_FAILED then FAILED after the refund when the payout fails. An unknown outcome or provider review holds the transfer as PROCESSING with sub_status MANUAL_REVIEW until it resolves. A quote that is never confirmed expires with nothing debited.1 · Quote2 · Payment3 · Paid3 · RefundScan QRPOST /qr/check → EXTERNAL_TRANSFERPENDINGQuote saved · nothing debitedQuote expiresNever confirmedPROCESSINGWallet debited · sent to providerMANUAL_REVIEWStill PROCESSING · held for reviewSUCCESSMerchant paid · finalFUND_REVERSAL_FAILEDPayout failed · refund runningFAILEDRefunded to same wallet · finalCreate quoteConfirm · wallet debitedOutcome unknown / reviewPaid outPayout failedRefund to same wallet
PathWhat happens
paid outThe provider confirms the payout (callback or status sync). Final SUCCESS.
payout failedThe 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 submitThe 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 unknownThe 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 reviewThe provider has put the payout under manual review. Still PROCESSING, sub_status MANUAL_REVIEW.
never confirmedThe 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 status stays as it is and sub_status becomes MANUAL_REVIEW. You can therefore see SUCCESS or FAILED together with MANUAL_REVIEW; treat it as "under review".
  • An abandoned PENDING quote currently returns display_status PROCESSING from GET /external-transfers/{uuid}. Use quote_expires_at and confirmed_at: null to show it as expired in the app.
  • A refund that cannot complete stays FUND_REVERSAL_FAILED and is retried automatically.
  • The server re-checks stuck PROCESSING transfers 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_codestatus_codeRouteMeaning / app action
INVALID_QR400quoteQR is not a valid supported QR. Ask the user to rescan.
INVALID_CURRENCY400quoteQR currency is not supported (only MYR).
TRANSFER_AMOUNT_BELOW_MINIMUM400quoteAmount below 1.00 MYR.
TRANSFER_AMOUNT_ABOVE_MAXIMUM400quoteAmount above the maximum (none configured today).
QR_AMOUNT_MISMATCH400quoteAmount differs from the amount inside a dynamic QR.
WALLET_NOT_FOUND400quote, confirmUser has no USDT wallet. Guide them to create / top up one.
WALLET_UNAVAILABLE400quote, confirmWallet is not ACTIVE (e.g. frozen) or not USDT.
INSUFFICIENT_BALANCE400quote, confirmBalance does not cover principal + fee.
EXCHANGE_RATE_MISSING400quoteRates unavailable. Retry later.
QUOTE_EXPIRED400confirmQuote expired before confirm. Create a new quote.
WALLET_DEBIT_FAILED500confirmDebit rolled back; nothing was charged. Safe to retry confirm.
EXTERNAL_TRANSFER_DISABLED503quote, confirmFeature switched off on the server. Show "temporarily unavailable".

Other failures (no error_code):

status_codeWhen
400Request validation failed (missing qr_content / amount, remark > 255), or uuid is not a valid UUID
404Transfer not found or not owned by the current user
502Provider quote failed, or the payout service could not be reached — retry the quote
429Rate limit (60 / minute / IP) exceeded on quote or confirm

Integration Checklist

  1. Scan → POST /qr/check; continue only when type is EXTERNAL_TRANSFER.
  2. Lock the amount when the QR carries one; otherwise enforce ≥ 1.00 with 2 decimals.
  3. Quote → show merchant, MYR amount, fee, total USDT debit, rate and a countdown to quote_expires_at.
  4. Confirm → treat any 200 as "processing", not "paid".
  5. Retry confirm on timeouts with the same uuid — it never double-charges.
  6. Finish on display_status SUCCESS / FAILED from the WebSocket-triggered read or polling.
  7. Show MANUAL_REVIEW as "under review", not as a failure.
Copyright © 2026