Payment gateways in Vietnam and why server location affects integration

You have built an e-commerce site that ships to Vietnam, and now the client asks for VNPay or MoMo at checkout. The API documentation looks clean, REST endpoints, JSON responses, the usual OAuth flow. You code the integration, launch a test payment, and the callback never arrives. The transaction succeeds on the bank side, but your server logged nothing.

The gateway is trying to reach your webhook URL and failing, not because the URL is wrong, but because the IP it sees doesn't belong to Vietnam. Most local payment gateways in Vietnam enforce IP whitelisting or geo-restrictions on the callback channel. Your application can live anywhere, but the endpoint that receives the transaction notification must sit inside Vietnam.

越南支付网关要求回调服务器拥有越南 IP，否则交易通知无法送达。

Vietnam payment gateways require the callback server to have a local IP, otherwise transaction notifications cannot be delivered.

Why Vietnam payment gateways enforce local IP whitelisting

Three large gateways dominate online payments in Vietnam: VNPay (state-aligned, covers most bank transfers and ATM cards), MoMo (the dominant e-wallet with over 30 million users), and ZaloPay (VNG-owned, tightly integrated with Zalo messaging). A smaller player is OnePay (owned by Vietcombank, common in corporate B2B billing). Every one of them implements IP-level restrictions on the server-to-server callback, the POST request that reports a successful transaction back to your system.

The technical root is straightforward: these gateways operate under State Bank of Vietnam (SBV) regulations that require the merchant's system to be identifiable and auditable. The callback IP must match a whitelist you submitted during onboarding. If your callback server is behind a Singapore IP or a shared cloud provider range, the gateway drops the notification. There is no fallback, no email summary, no dashboard that lets you re-deliver a missed callback. You must catch it in real time or implement a manual reconciliation flow, which is expensive and error-prone at scale.

There is a common workaround: run the API endpoint on a server with a Vietnam IP, and let that server forward the callback to your main application via a private tunnel (WireGuard, a Tailscale mesh, or a simple signed HTTP forward). This means your application can stay on your usual cloud provider (DigitalOcean, AWS, Hetzner) while a lightweight relay sits on a Vietnam VPS with a dedicated IPv4. The relay receives the POST, verifies the signature, and pushes the notification onward. This is the architecture we see in most production integrations.

Some developers attempt to use Cloudflare Spectrum or a reverse proxy with a Vietnam origin. This does not work for many gateways because the gateway reads the IP at the TLS handshake level, not the HTTP header. If the terminating IP is not in Vietnam, the connection is dropped before your application sees a byte.

Callback routing and settlement: the two channels you must separate

A typical payment gateway in Vietnam operates two distinct communication channels to the merchant:

Channel 1, Browser redirect (frontend). After the user completes payment on the gateway's page, the user's browser is redirected back to your return_url. This is a GET request with query parameters containing the transaction ID and a hash. Because the redirect happens from the user's browser, it carries the user's IP, not a Vietnam gateway IP. This channel works from any server location, it is essentially a client-side handoff.

Channel 2, Server callback (backend). The gateway sends a POST or GET request directly from its own backend to your ipn_url (VNPay) or notify_url (MoMo). This is the authoritative transaction confirmation. The signature on this request is the one you must verify, the browser redirect data can be forged or arrive from a stale page. The callback comes from the gateway's servers, which sit inside Vietnam. It hits your server at a rate of one request per transaction, plus retries if the response is not HTTP 200.

Channel 2 is where the IP restriction applies. The gateway will connect to the IP address your ipn_url resolves to. If that IP is not in the Vietnam range and not on your whitelist, the connection is not established. The gateway logs a failed delivery and typically retries 3-5 times with exponential backoff, then stops. After that, the transaction exists in the gateway's database as "successful" but your system never received confirmation. You discover it during manual reconciliation, a day later.

Settlement timing also differs from what Western developers expect from gateways like Stripe or Adyen. In Vietnam, most gateways settle to the merchant's bank account at the start of the next business day (T+1). Weekend transactions settle on Monday morning. Some gateways batch settlements weekly. This is standard local practice, not a dysfunction. Your accounting system must tolerate a settlement lag that is not present with international processors.

The infrastructure landscape inside Vietnam

To host a callback relay or a full application inside Vietnam, you need to understand the local connectivity environment. The backbone is operated by four major telecom groups: VNPT (the former state monopoly, now VNPT Group, runs most of the fixed-line and fiber infrastructure), Viettel (the military-run telecom, the largest mobile operator and a major datacenter builder), FPT Telecom (the private competitor, strong in consumer broadband and business internet), and CMC Telecom (a smaller player focused on enterprise and datacenter services). All four operate Tier 3 datacenters in Ho Chi Minh City and Hanoi.

When you rent a Vietnam VPS, your server is hosted inside these datacenters, typically Viettel IDC or VNPT IDC. The networking reality is different from what you expect in Singapore or Tokyo domestic bandwidth is generous, but international bandwidth is a constrained shared pool. The typical Vietnam VPS comes with unlimited traffic with no data cap. Domestic bandwidth runs at 100 Mbps by default on a 1 Gbps port, the port is 1 Gbps, but the speed is shaped to 100 Mbps. International bandwidth is a shared pool of roughly 4 to 10 Mbps per server. This matters for your payment architecture: the callback relay that receives notifications and forwards them outbound will compete with general outbound traffic. If your application also streams data to an overseas database or API, bandwidth contention becomes noticeable.

Each server gets a dedicated IPv4 from the Vietnam range. That is exactly what the payment gateways will whitelist. The server runs KVM virtualization with NVMe storage, offers full root or Administrator access, and supports snapshots and backups. Billing is monthly, with options from VNLite (1 vCPU, 2 GB RAM, 20 GB NVMe) up to VNx8 (8 vCPU, 16 GB RAM, 100 GB NVMe). For a callback relay that does nothing but forward payment notifications, even the smallest plan is typically enough. For a full e-commerce backend, the VNx2 or VNx4 range is the practical starting point.

Other gateways: ZaloPay, OnePay, and the national QR standard

ZaloPay is the payment arm of VNG Corporation and is tightly integrated with the Zalo messaging platform (which has over 70 million registered users in Vietnam). ZaloPay's API pattern is closer to MoMo's: a REST JSON API with OAuth 2.0 for merchant authentication, and a callback that expects a Vietnam IP. ZaloPay also offers a QR code generation API that lets the user scan and pay at physical POS terminals, the callback for payment confirmation again comes from inside Vietnam.

OnePay is the online payment gateway of Vietnam Joint Stock Commercial Bank for Foreign Trade (Vietcombank). It is commonly used for B2B payments and utility bill collection. OnePay's integration is more rigid, the whitelist is maintained by the bank and changes take 1-2 business days. If you need to add or rotate a callback IP, you submit a form and wait. This makes it even more important to provision a static Vietnam IP that will not change during upgrades or provider migrations.

Since 2020, Vietnam has been pushing a national QR payment standard called VietQR, managed by the National Payment Corporation of Vietnam (NAPAS). This is not a gateway you integrate directly, it is the standard that banks use for peer-to-peer and merchant QR payments. MoMo and ZaloPay both support VietQR. If your merchant shows a QR code at a physical store, the payment could be routed through any participating bank or e-wallet. As an application developer, you do not handle VietQR directly unless you build a payment aggregator, but you should understand that the QR payment ecosystem is bank-led, not gateway-led.

Common failure scenarios and troubleshooting

Callback never arrives. If the webhook URL resolves to a Vietnam IP but the gateway still does not connect, check two things: (1) whether the gateway requires port whitelisting as well as IP whitelisting, VNPay and MoMo both default to port 80/443 but some environments are locked to specific source ports. (2) Whether the gateway performs a reverse DNS check on your IP. Some gateways refuse connections from IPs without a matching PTR record. Set up an rDNS entry for your Vietnam IP pointing back to a meaningful hostname.

Callback arrives but fails signature verification. Vietnamese gateways often use a custom HMAC construction with MD5, SHA-256, or a mix. The documentation is written in Vietnamese and the signature example may use utf8 encoding implicitly. If your verification logic uses ascii or latin1, the signature will not match. Log the raw POST body and compute the hash in a test script using the exact encoding the gateway expects, usually utf8.

Callback works but transactions fail settlement. A transaction may appear successful in the gateway dashboard but never settle to your bank account. This typically means the gateway required additional documentation (business registration, a signed merchant agreement) that was never finalized. Settlement activation is a manual step at many Vietnamese gateways. Do not assume an approved sandbox means a live production settlement. Confirm settlement readiness with a small live transaction before going public.

CI/CD interrupted by IP change. If you redeploy your callback relay to a new server with a different Vietnam IP, all whitelists must be updated before the old IP is destroyed. This is a coordination point that many teams miss. Use a load balancer with a stable IP or a VIP (Virtual IP) that can be moved between servers. Some Vietnam VPS providers allow you to reserve an IP and reassign it to a new instance, leverage that.

When a Vietnam server is not enough

Having a Vietnam IP is necessary but not sufficient. The gateway also expects the callback to be reachable with low latency and zero packet loss. If your server has a high packet loss rate to the gateway's internal network (within Vietnam), the callback may time out even though the IP is whitelisted. This is rare in practice because domestic routing inside Vietnam is stable, the major datacenters interconnect directly with the backbone operators. But if you choose a server that is not in a Tier 3 datacenter with direct peering to Viettel and VNPT, you may see issues. The safe choice is a provider that explicitly places servers inside Viettel IDC or VNPT IDC.

Another edge case: some gateways check the ASN (Autonomous System Number) of your IP, not just its geographic assignment. If your Vietnam IP is announced by a provider whose ASN is registered in Singapore or the US, the gateway may flag it. This is unusual, but it happens. Stick with providers that announce their Vietnam IPs from a Vietnam-registered ASN (typically AS 45544 for Viettel, AS 45899 for VNPT, AS 18403 for FPT).

FAQ

Related articles

• Warming up a new sending IP: a realistic 30-day schedule
• SPF, DKIM, and DMARC on a self-hosted SMTP server
• How to rent a VPS in Vietnam as a foreign company
• Vietnam VPS vs Singapore VPS for serving Vietnamese users