Thanh toán điện tử nghe có vẻ đơn giản — chỉ là gọi một API rồi nhận callback. Nhưng bất cứ developer nào đã làm production payment system đều biết: mọi thứ phức tạp hơn nhiều ở lớp thứ 2 và thứ 3.
Các mô hình tích hợp chính tại Việt Nam
Hiện tại có 4 luồng chính cần hiểu:
- VietQR: QR tĩnh/động dựa trên chuẩn EMVCo, xác nhận qua Napas. Phù hợp cho POS và invoice. Lưu ý: timeout mặc định 5 phút, cần handle expiry rõ ràng.
- VNPAY / VNPAY-QR: Gateway có redirect flow. Cần whitelist IP merchant, verify checksum SHA512 cho mọi IPN callback — nhiều dev bỏ qua bước này và bị tấn công replay.
- MoMo: Direct capture API và in-app deeplink cho mobile. Token-based, có thêm extra data field để truyền metadata.
- Stripe (cho quốc tế): Payment Intent model với webhook. Cần handle idempotency key để tránh double-charge khi network retry.
3 lỗi làm chúng tôi mất nhiều giờ nhất
1. Không xử lý pending state: Giữa lúc user hoàn tất thanh toán và IPN về đến server của bạn có thể là 0.5 giây đến 30 giây. Trong khoảng thời gian này, order không nên ở trạng thái “failed” hay “success” — cần có state “pending_payment” riêng, hoặc user sẽ thấy lỗi và bấm thanh toán lại.
2. Tin vào redirect return URL: Return URL chỉ là UX — user có thể đóng tab trước khi redirect về. Toàn bộ logic xử lý đơn phải nằm trong IPN/webhook handler, không phải return URL callback.
3. Test chỉ trên sandbox: Sandbox của các gateway Việt Nam thường không mô phỏng đúng timeout, network error, và duplicate notification. Cần staging environment với real test card/account để catch edge cases trước go-live.
Checklist trước khi go-live
- ☑ Verify signature/checksum trên mọi IPN callback
- ☑ Idempotency check — không process cùng một transaction_id hai lần
- ☑ Handle timeout và network failure — retry với exponential backoff
- ☑ Log toàn bộ raw request/response (masked) cho debugging
- ☑ Reconciliation job hàng ngày đối chiếu với portal của gateway
- ☑ Alert khi IPN bị delay >2 phút hoặc failure rate >0.5%
Payment system lỗi = doanh thu bị treo. Đầu tư thêm 2–3 ngày để làm đúng ngay từ đầu luôn rẻ hơn debug production lúc 2 giờ sáng.
