Payment integration sounds straightforward — call an API, handle a callback. But any developer who has shipped a production payment system knows: things get considerably more complex at layers two and three.
The main integration models in Vietnam
There are four primary flows you need to understand:
- VietQR: Static/dynamic QR based on the EMVCo standard, confirmed via Napas. Ideal for POS and invoicing. Note: the default timeout is 5 minutes — expiry must be handled explicitly.
- VNPAY / VNPAY-QR: Gateway with a redirect flow. Merchant IP whitelisting required; SHA512 checksum verification is mandatory for every IPN callback — many developers skip this step and become vulnerable to replay attacks.
- MoMo: Direct capture API and in-app deeplink for mobile. Token-based, includes an extra data field for metadata.
- Stripe (for international payments): Payment Intent model with webhooks. Idempotency keys are essential to prevent double charges on network retries.
The 3 mistakes that cost us the most time
1. Not handling the pending state: Between the moment a user completes payment and when the IPN reaches your server, there may be a 0.5–30 second window. During this time, the order should neither be “failed” nor “success” — a separate “pending_payment” state is required, otherwise users will see an error and attempt to pay again.
2. Trusting the redirect return URL: The return URL is a UX mechanism only — the user may close their tab before being redirected. All order processing logic must live in the IPN/webhook handler, not in the return URL callback.
3. Testing only on sandbox: Vietnamese gateway sandboxes typically don’t accurately simulate timeouts, network errors, or duplicate notifications. A staging environment with real test cards/accounts is necessary to catch edge cases before go-live.
Go-live checklist
- ☑ Verify signature/checksum on every IPN callback
- ☑ Idempotency check — never process the same transaction_id twice
- ☑ Handle timeouts and network failures with exponential backoff retry
- ☑ Log all raw request/response data (masked) for debugging
- ☑ Daily reconciliation job against the gateway portal
- ☑ Alert when IPN is delayed more than 2 minutes or failure rate exceeds 0.5%
Payment system failures equal suspended revenue. Investing 2–3 extra days to get it right from the start is always cheaper than debugging production at 2 AM.
