Scan to Pay Overview
What It Does
External transfers let a user scan a Malaysian DuitNow QR (Touch 'n Go merchant QR) and pay the merchant in MYR, funded from the user's own USDT wallet. This feature is called Scan to Pay; the payout is executed by an external payment provider.
| Item | Value |
|---|---|
| Supported QR | EMV QR with DuitNow GUI A0000006150001 (QR type TNG_MERCHANT_QR) |
| Payout currency | MYR |
| Funding wallet | The user's existing ACTIVE USDT wallet (selected by the server) |
| Fee currency | USDT (charged together with the principal) |
| Minimum amount | 1.00 MYR |
| Maximum amount | No maximum is configured at the moment |
Lifecycle
Each path is explained in Status, Events & Errors.
Flow Summary
Step 1. Identify the QRPOST /api/v1/qr/check → type is EXTERNAL_TRANSFER
Step 2. Create a quotePOST /api/v1/external-transfers/qr-payout/quote → price, fee, total debit, quote_expires_at. No money moves.
Step 3. Confirm the quotePOST /api/v1/external-transfers/{uuid}/confirm → the wallet is debited once and the payout is submitted to the payment provider.
Step 4. Track the result
WebSocket event EXTERNAL_TRANSFER_STATUS, push notification, or poll
GET /api/v1/external-transfers/{uuid}.
All routes require Authorization: Bearer <access_token>.
The app only ever talks to the mobile-api routes on these pages. The calls between
mobile-api and webhook-api, and the provider callback, are server-to-server and are not part of
the client integration.
Money Flow
- Quote — the server checks the wallet balance covers principal + fee, asks the payment provider for a quote, and stores it with the exchange-rate snapshot. The wallet is not touched.
- Confirm — in one database transaction the wallet is debited the full
debit_amount(principal + fee), a payment history row (EXTERNAL_TRANSFER, statusPENDING) is written, and the transfer moves toPROCESSING. The saved provider quote is then executed. - Success — the transfer becomes
SUCCESSand the history row becomesSUCCESS. - Definite failure — the payment provider reports the payout failed: the full
debit_amount(fee included) is refunded to the same wallet, a credit rowEXTERNAL_TRANSFER_REFUNDis written, the original history row becomesFAILED, and the transfer ends asFAILED. - Uncertain outcome — if the submission result is unknown (timeout, missing order number, etc.)
the funds stay captured and the transfer stays
PROCESSINGuntil the provider's callback, a status sync, or an investigation resolves it. The server never refunds or resubmits a payout it cannot prove was rejected.
uuid returns the current transfer and
never charges the wallet twice.Statuses
The response carries both the internal status and a simplified display_status. Build the UI on
display_status.
status | display_status | Meaning |
|---|---|---|
PENDING | PROCESSING | Quote created, not yet confirmed. Nothing debited. |
PROCESSING | PROCESSING | Wallet debited, payout submitted / waiting for the payment provider. |
SUCCESS | SUCCESS | Merchant paid. Final. |
FUND_REVERSAL_FAILED | FAILED | Payout failed, refund to wallet still in progress. |
FAILED | FAILED | Payout failed and the wallet has been refunded. Final. |
sub_status can be MANUAL_REVIEW when the payment provider has put the payout under manual review. The
transfer is still PROCESSING; show it as "under review".
Amounts and Exchange Rate
The USDT debit is priced through USD using the latest stored rates:
| Field | Meaning | Example |
|---|---|---|
amount / currency | MYR paid to the merchant | "100.00" / "MYR" |
total_fee_amount / total_fee_currency | Fee charged in USDT (provider fee converted, rounded up to the cent) | "0.25" / "USDT" |
debit_amount / debit_currency | Total taken from the wallet = principal + fee | "21.53" / "USDT" |
exchange_rate | USDT per 1 MYR (10 decimals) | "0.2128000000" |
exchange_rate_display | MYR per 1 USDT, for display | "4.6992481203" |
- Amounts are returned as strings with 2 decimals. Submit
amountwith at most 2 decimals. - Rates are frozen at quote time. Confirming uses the quoted numbers, not new rates.
- If the QR already contains an amount (dynamic QR), the submitted
amountmust equal it.
Quote Expiry
Every quote has quote_expires_at (set by the payment provider). Confirming after that time returns
QUOTE_EXPIRED; create a new quote instead. Show a countdown on the confirmation screen and
re-quote when it runs out.
Rate Limits
POST .../qr-payout/quote and POST .../{uuid}/confirm are limited to 60 requests per minute
per IP.