Scan to Pay

QR Payout API

Check a scanned QR, create a Scan to Pay quote, confirm it, and read the transfer.

Routes

MethodPathPurpose
POST/api/v1/qr/checkIdentify a scanned QR
POST/api/v1/external-transfers/qr-payout/quoteCreate a quote (no money moves)
POST/api/v1/external-transfers/{uuid}/confirmDebit the wallet and submit the payout
GET/api/v1/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/v1/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..."
}
  • content is 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

typeNext step
EXTERNAL_TRANSFEROpen the Scan to Pay flow (create quote).
INTERNAL_TRANSFERUC internal card transfer; internal_transfer is returned instead. Not Scan to Pay.
UNKNOWNNot a supported QR. Show "unsupported QR".

Notes

  • amount is empty for a static QR — let the user type the amount.
  • When amount is set (dynamic QR), lock the amount field to that value; the quote rejects any other amount with QR_AMOUNT_MISMATCH.
  • receiver_name comes from the QR. Show it so the user can verify the merchant.

2. Create QR Payout Quote

POST /api/v1/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"
}
FieldTypeRequiredRules
qr_contentstringyesRaw QR string; must be a supported DuitNow QR
amountstring (decimal)yesMYR amount, ≥ 1.00, max 2 decimals; must equal the QR amount for a dynamic QR
remarkstringnoUp to 255 characters; trimmed

Server checks (in order)

  1. QR parses as a supported DuitNow / TNG merchant QR
  2. Currency is supported (MYR) and amount is within limits / matches the QR amount
  3. The user has a USDT wallet and it is ACTIVE
  4. Exchange rates USDT/USD and MYR/USD are available
  5. Wallet balance covers the principal
  6. The payment provider returns a quote that has not already expired
  7. 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

FieldMeaning
idTransfer ID. Also the reference_id of the related wallet / transaction-history rows.
uuidTransfer UUID — use it for confirm and status calls.
request_idMerchant order number sent to the payment provider (same as uuid).
wallet_idWallet the quote is priced against; debited on confirm and credited by any refund.
receiver_id, receiver_nameMerchant from the QR.
amount, currencyMYR paid to the merchant.
status, display_status, sub_statusSee Statuses.
total_fee_amount, total_fee_currencyFee in USDT.
debit_amount, debit_currencyTotal USDT taken from the wallet on confirm.
exchange_rateUSDT per 1 MYR.
exchange_rate_displayMYR per 1 USDT.
quote_expires_atConfirm before this time.
confirmed_atnull until confirmed (the moment the wallet was debited).
remarkUser remark.

3. Confirm QR Payout

POST /api/v1/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) returns QUOTE_EXPIRED.
  • If the balance dropped since the quote, confirm returns INSUFFICIENT_BALANCE and nothing is debited.
  • A transfer that belongs to another user returns 404.

4. Get External Transfer

GET /api/v1/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_status is PROCESSING, back off after ~1 minute.
  • Stop when display_status is SUCCESS or FAILED.
  • If the payment provider cannot be reached, the call still returns the stored transfer.

cURL Examples

# Quote
curl -X POST "$BASE_URL/api/v1/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/v1/external-transfers/$UUID/confirm" \
  -H "Authorization: Bearer $TOKEN"

# Status
curl "$BASE_URL/api/v1/external-transfers/$UUID" \
  -H "Authorization: Bearer $TOKEN"
Copyright © 2026