Vietnam: VietQR, NAPAS 247 and MoMo sit at different payment layers

Imagine a checkout with two buttons: VietQR and MoMo. In the first journey, the customer scans bank details and transfers money. In the second, they open an approved MoMo payment flow. Both may feel equally fast, yet leave different identifiers and require different confirmation evidence. They can share an internal ledger without sharing external status semantics.

Most importantly, VietQR and NAPAS 247 should not be counted as two successive, independent payments. In the particular NAPAS FastFund 247 service using VietQR, the code conveniently addresses the same bank transfer. That arrangement is distinguished here from MoMo’s merchant API. The scope is lawful revenue collection, not permission for every industry to use local rails.

One purchase through VietQR: what to verify

NAPAS describes transfers between participating bank accounts by scanning VietQR, available around the clock, with each transaction below VND 500 million. This describes that transfer product, not every Vietnamese QR payment. The code simplifies entering bank details but does not establish that the recipient is your PSP’s approved merchant. NAPAS service description.

At checkout, retain the bank, destination account, displayed beneficiary, expected amount, payment narrative, instruction time and order expiry. These are recommended internal fields, not a claim that every static VietQR necessarily contains all of them. If the payer enters the amount or reference, define the response to mistakes, missing text and payments made after an order closes.

A dangerous assumption is: “the QR contains the order number, so the bank will return that number in a convenient field.” Test the entire journey: instruction generation, the buyer’s banking screen, actual incoming transfer and recipient export. If text is truncated, normalized or omitted by your servicing channel, discover that during the pilot. Do not automate credits using a feature neither the contract nor testing has established.

MoMo requires a merchant arrangement

MoMo’s official onboarding sequence includes a merchant profile, test integration, account verification, production credentials, production testing and go-live approval. It does not describe personal-wallet permissions. Sandbox access proves that integration development is possible, not that the sector, legal entity or settlement arrangement has been accepted.

Separate enterprise verification from the buyer’s ability to authorize a payment. For example, MoMo’s current result-code list includes 4002 for information not verified through C06, with biometric updating through NFC required. Code 1004 concerns a daily or monthly limit; 1005 concerns an expired URL or QR. These are distinct causes, and blindly repeating a request does not resolve them.

Five identifiers instead of one vague ID

In the MoMo model, distinguish partnerCode, orderId, requestId, transId and your internal order ID. Partner and order identify context, requestId identifies the request, and MoMo supplies transId. Status queries use partnerCode, orderId, requestId and a signature. Names and roles come from the applicable documentation version; preserve values without losing case or formatting.

Add an internal attempt number. One order may have an unpaid first attempt and a successful second attempt. A refund belongs to the successful financial transaction, rather than whichever page was most recently opened. Store the expected VND amount and returned outcome for every attempt; a product name or phone number is not a uniqueness key.

IPN matters more than the customer returning to the browser

MoMo posts results server-to-server to ipnUrl. Its documentation requires signature verification and matching partnerCode, orderId and amount, with HTTP 204 returned within 15 seconds. resultCode 0 indicates success of the relevant operation; 9000 indicates successful authorization. The latter must not automatically become completed payment in a separate-capture flow. IPN rules.

Your processing must be idempotent: one confirmed financial event creates one entry even if delivered repeatedly. A recommended sequence is to verify the request, durably record the event, acknowledge promptly, and perform heavier fulfilment through a queue. If the notification disappears, use the official status query rather than asking the customer to pay again merely to generate another receipt.

Another boundary matters: HTTP 2xx indicates successful API-request handling but does not replace inspection of the business code and operation type. Payment-page creation, authorization and final successful payment answer different questions. Customer messaging should state the confirmed result, instead of displaying “paid” after any technically successful server response.

A refund is a separate operation with its own outcome

MoMo’s refund API requires a new refund orderId distinct from the purchase, requestId, amount and the original successful payment’s transId. A separate refund-result query is available. Partial refunds must stay within the remaining refundable balance. Documentation distinguishes numerical limits by payment method, so one ceiling should not be applied to every MoMo product.

In an illustrative case, a customer pays VND 400,000 and later receives approval for a partial refund. The system reserves that refund amount, links it to the original transId and tracks the outcome separately. If the request times out, first establish whether it was accepted. Creating another refund with a new identifier before checking can repeat reimbursement.

What the payment API does not establish

Settlement timing, fees, reserves, permitted goods and the enterprise’s right to collect payments follow the contract and applicable rules. MoMo verification and a bank account do not replace sector authorization. Vietnamese authorities separately explain liability for organizing unlawful gambling; online-game rules also do not make virtual items freely cash-redeemable money.

A local method’s suitability for a particular gaming business cannot therefore be inferred from a scannable QR or responsive API. A good integration establishes something else: every lawful payment has an evidenced status, linked order, clear settlement obligation and verifiable refund. VietQR, NAPAS 247 and MoMo occupy different roles in that picture, without inventing three independent movements of funds.