QR Payout API
Routes
| Method | Path | Purpose |
|---|---|---|
POST | /api/v2/qr/check | Identify a scanned QR |
POST | /api/v2/external-transfers/qr-payout/quote | Create a quote (no money moves) |
POST | /api/v2/external-transfers/{uuid}/confirm | Debit the wallet and submit the payout |
GET | /api/v2/external-transfers/{uuid} | Read one transfer (syncs with the payment provider while PROCESSING) |
All routes require Authorization: Bearer <access_token>. Accept-Language (en, zh, vi,
ja) localizes error messages.
1. Check QR Content
POST /api/v2/qr/check
Tells the app what kind of QR was scanned, so it can open the right flow. This call does not contact the payment provider and does not create anything.
Request body
{
"content": "00020101021126580014A0000006150001020889000123..."
}
contentis required — the raw string decoded from the QR image.
Response — Scan to Pay merchant QR
{
"status_code": 200,
"message": "Success",
"data": {
"type": "EXTERNAL_TRANSFER",
"external_transfer": {
"qr_type": "TNG_MERCHANT_QR",
"receiver_id": "890001234",
"receiver_name": "KEDAI MAKAN ALI",
"amount": "",
"currency": "MYR"
}
}
}
type values
type | Next step |
|---|---|
EXTERNAL_TRANSFER | Open the Scan to Pay flow (create quote). |
INTERNAL_TRANSFER | UC internal card transfer; internal_transfer is returned instead. Not Scan to Pay. |
UNKNOWN | Not a supported QR. Show "unsupported QR". |
Notes
amountis empty for a static QR — let the user type the amount.- When
amountis set (dynamic QR), lock the amount field to that value; the quote rejects any other amount withQR_AMOUNT_MISMATCH. receiver_namecomes from the QR. Show it so the user can verify the merchant.
2. Create QR Payout Quote
POST /api/v2/external-transfers/qr-payout/quote
Prices the payout against the user's USDT wallet and reserves a provider quote. The wallet is not debited. The server chooses the wallet; the client does not send a wallet ID.
Request body
{
"qr_content": "00020101021126580014A0000006150001020889000123...",
"amount": "100.00",
"remark": "Lunch"
}
| Field | Type | Required | Rules |
|---|---|---|---|
qr_content | string | yes | Raw QR string; must be a supported DuitNow QR |
amount | string (decimal) | yes | MYR amount, ≥ 1.00, max 2 decimals; must equal the QR amount for a dynamic QR |
remark | string | no | Up to 255 characters; trimmed |
Server checks (in order)
- QR parses as a supported DuitNow / TNG merchant QR
- Currency is supported (
MYR) andamountis within limits / matches the QR amount - The user has a USDT wallet and it is
ACTIVE - Exchange rates
USDT/USDandMYR/USDare available - Wallet balance covers the principal
- The payment provider returns a quote that has not already expired
- Wallet balance covers principal + fee
Success response
{
"status_code": 200,
"message": "Success",
"data": {
"id": 1024,
"uuid": "8f6a3c1e-2b4d-4f7a-9c1e-5d2b7a9e0f13",
"request_id": "8f6a3c1e-2b4d-4f7a-9c1e-5d2b7a9e0f13",
"wallet_id": 77,
"receiver_id": "890001234",
"receiver_name": "KEDAI MAKAN ALI",
"amount": "100.00",
"currency": "MYR",
"status": "PENDING",
"display_status": "PROCESSING",
"total_fee_amount": "0.25",
"total_fee_currency": "USDT",
"debit_amount": "21.53",
"debit_currency": "USDT",
"exchange_rate": "0.2128000000",
"exchange_rate_display": "4.6992481203",
"quote_expires_at": "2026-11-04T08:15:00Z",
"confirmed_at": null,
"remark": "Lunch"
}
}
Response fields
| Field | Meaning |
|---|---|
id | Transfer ID. Also the reference_id of the related wallet / transaction-history rows. |
uuid | Transfer UUID — use it for confirm and status calls. |
request_id | Merchant order number sent to the payment provider (same as uuid). |
wallet_id | Wallet the quote is priced against; debited on confirm and credited by any refund. |
receiver_id, receiver_name | Merchant from the QR. |
amount, currency | MYR paid to the merchant. |
status, display_status, sub_status | See Statuses. |
total_fee_amount, total_fee_currency | Fee in USDT. |
debit_amount, debit_currency | Total USDT taken from the wallet on confirm. |
exchange_rate | USDT per 1 MYR. |
exchange_rate_display | MYR per 1 USDT. |
quote_expires_at | Confirm before this time. |
confirmed_at | null until confirmed (the moment the wallet was debited). |
remark | User remark. |
3. Confirm QR Payout
POST /api/v2/external-transfers/{uuid}/confirm
Debits debit_amount from the quoted wallet once, then submits the saved provider quote.
Path parameter
uuid— required, the transfer UUID from the quote.
Request body
None. The owner is taken from the access token.
Success response
Same shape as the quote response. Typically:
{
"status_code": 200,
"message": "Success",
"data": {
"uuid": "8f6a3c1e-2b4d-4f7a-9c1e-5d2b7a9e0f13",
"status": "PROCESSING",
"display_status": "PROCESSING",
"debit_amount": "21.53",
"debit_currency": "USDT",
"confirmed_at": "2026-11-04T08:12:31Z"
}
}
Important behavior
- A successful confirm means the wallet was charged and the payout was handed to the payment provider, not that the merchant has been paid. Show a "processing" screen and wait for the final status.
- Idempotent: repeating confirm for an already confirmed or finished transfer returns its current state without charging again and without the expiry check. Safe to retry on network errors.
- Confirm after
quote_expires_at(for a not-yet-confirmed transfer) returnsQUOTE_EXPIRED. - If the balance dropped since the quote, confirm returns
INSUFFICIENT_BALANCEand nothing is debited. - A transfer that belongs to another user returns
404.
4. Get External Transfer
GET /api/v2/external-transfers/{uuid}
Returns one of the current user's transfers. When the transfer is PROCESSING and an provider order
exists, the server first asks the payment provider for the latest order status and applies it, then returns the
updated transfer.
Path parameter
uuid— required.
Response
Same shape as the quote response.
Polling guidance
- Prefer the WebSocket event; poll only as a fallback.
- Poll every 3–5 seconds while
display_statusisPROCESSING, back off after ~1 minute. - Stop when
display_statusisSUCCESSorFAILED. - If the payment provider cannot be reached, the call still returns the stored transfer.
cURL Examples
# Quote
curl -X POST "$BASE_URL/api/v2/external-transfers/qr-payout/quote" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept-Language: en" \
-d '{"qr_content":"0002010102112658...","amount":"100.00","remark":"Lunch"}'
# Confirm
curl -X POST "$BASE_URL/api/v2/external-transfers/$UUID/confirm" \
-H "Authorization: Bearer $TOKEN"
# Status
curl "$BASE_URL/api/v2/external-transfers/$UUID" \
-H "Authorization: Bearer $TOKEN"