Scan to Pay

Scan to Pay Overview

How external QR payouts work — pay a Malaysian DuitNow / TNG merchant QR from the user's USDT wallet with Scan to Pay.

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.

ItemValue
Supported QREMV QR with DuitNow GUI A0000006150001 (QR type TNG_MERCHANT_QR)
Payout currencyMYR
Funding walletThe user's existing ACTIVE USDT wallet (selected by the server)
Fee currencyUSDT (charged together with the principal)
Minimum amount1.00 MYR
Maximum amountNo maximum is configured at the moment

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

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>.

Scan to Pay architecture: the mobile app calls mobile-api. mobile-api sends signed internal requests to webhook-api, which requests quotes and payouts from the payment provider. The provider sends a callback to webhook-api. Status updates reach the app by WebSocket and push notification.UC backendExternalMobile AppCalls mobile-api onlymobile-api/api/v1/qr/check · /api/v1/external-transferswebhook-apiInternal · quote, debit, payout, refundPayment providerExecutes the MYR payoutAPI callsSigned internal callQuote · payoutCallbackWebSocket + push

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

  1. 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.
  2. Confirm — in one database transaction the wallet is debited the full debit_amount (principal + fee), a payment history row (EXTERNAL_TRANSFER, status PENDING) is written, and the transfer moves to PROCESSING. The saved provider quote is then executed.
  3. Success — the transfer becomes SUCCESS and the history row becomes SUCCESS.
  4. Definite failure — the payment provider reports the payout failed: the full debit_amount (fee included) is refunded to the same wallet, a credit row EXTERNAL_TRANSFER_REFUND is written, the original history row becomes FAILED, and the transfer ends as FAILED.
  5. Uncertain outcome — if the submission result is unknown (timeout, missing order number, etc.) the funds stay captured and the transfer stays PROCESSING until 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.
Confirm is idempotent. Calling it again for the same 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.

statusdisplay_statusMeaning
PENDINGPROCESSINGQuote created, not yet confirmed. Nothing debited.
PROCESSINGPROCESSINGWallet debited, payout submitted / waiting for the payment provider.
SUCCESSSUCCESSMerchant paid. Final.
FUND_REVERSAL_FAILEDFAILEDPayout failed, refund to wallet still in progress.
FAILEDFAILEDPayout 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:

Exchange-rate route: USDT is converted to USD with the USDT/USD rate, then USD is converted to MYR with the inverse of the MYR/USD rate.USDTWallet currencyUSDBridge currencyMYRMerchant payout× USDT/USD÷ MYR/USD
FieldMeaningExample
amount / currencyMYR paid to the merchant"100.00" / "MYR"
total_fee_amount / total_fee_currencyFee charged in USDT (provider fee converted, rounded up to the cent)"0.25" / "USDT"
debit_amount / debit_currencyTotal taken from the wallet = principal + fee"21.53" / "USDT"
exchange_rateUSDT per 1 MYR (10 decimals)"0.2128000000"
exchange_rate_displayMYR per 1 USDT, for display"4.6992481203"
  • Amounts are returned as strings with 2 decimals. Submit amount with 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 amount must 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.

Copyright © 2026