Payment Gateway: Deployment & Go-Live
The payment gateway is a standalone frontend project; its build output is pure static files, and it deploys like the web admin console (static hosting + API reverse proxy). Its particularity is the domain contract: payment links, redirects, and auth callback addresses are all generated by the backend against the payment gateway domain, so the deployed domain must align with the platform configuration.
Build
- Node 22+ and pnpm 10+;
- The build output is pure static files (
dist/); production builds automatically strip debug console output.
Key build settings (hard-coded in the env files; adjust them as needed before building):
| Setting | Description |
|---|---|
| Backend API URL | Left empty in production = requests use relative paths and rely on a same-domain reverse proxy to reach the backend (recommended) |
| API prefix | Fixed /api/; requests look like https://your-domain/api/... |
Four Deployment Essentials
Static hosting: serve the build output with nginx or any static server; it is independent of the other frontends (the web consoles) and can be deployed separately;
API reverse proxy: under the same domain, reverse-proxy
/api/to the backend service (same policy as the admin console), no CORS setup needed:nginxlocation /api/ { proxy_pass http://backend-address/; }SPA fallback: all paths fall back to
index.html— gateway addresses are deep paths like/cashier/xxx,/h/xxx,/auth/xxx; refreshes and direct hits must not 404:nginxlocation / { try_files $uri $uri/ /index.html; }HTTPS: pages facing payers must be HTTPS; terminate the certificate at the nginx layer.
The Domain Contract (Key Point)
Most page addresses of the payment gateway are generated by the backend for channels, payers, and login users — the frontend does not assemble them itself:
| Address | Who uses it | When generated |
|---|---|---|
Payment links /cashier/..., /h/..., /aggregate/... | Payer | Returned to the merchant system at pre-pay / QR terminal creation |
Pay result page /pay-result/{trade-no} | Payer | Payments with a return URL configured; the channel redirects here after processing |
Transfer confirmation page /transfer-confirm/{transfer-no} | Payee | Generated when a WeChat transfer is initiated |
| Auth redirect | Payer | The WeChat web authorization domain / Alipay authorization callback URL registered is exactly the gateway domain |
Third-party login relay entry /auth/oauth-callback/... | Web console login users | Login / binding callbacks of redirect-type platforms uniformly land on the gateway domain |
Therefore the payment gateway must be deployed under the platform's payment gateway domain (maintained in the backend "Endpoint Config"): the backend generates the addresses, the frontend serves the pages, and only when the two sides match do users avoid 404. Before going live, check the deployed domain against the backend gateway domain configuration; for the auth and relay mechanisms see Authentication & Relay.
Linkage with Cashier Configuration
After the payment gateway is online, what the cashier shows still depends on two configurations (the pages themselves need no change):
- The merchant's cashier configuration: the payment method list, recommended and lock flags (see the merchant console docs);
- Domain verification: WeChat JSAPI payment requires completing domain ownership verification (verification file upload), see Channel Integration - Domain Verification Files.
Common Deployment Problems
| Symptom | Cause |
|---|---|
| Direct link / refresh returns 404 | SPA fallback not configured (try_files ... /index.html) |
| Page opens but all requests fail | /api/ reverse proxy missing or pointing at the wrong backend |
| 404 after the post-payment redirect | Deployed domain does not match the backend payment gateway domain configuration |
| Third-party login ends in 404 / cannot return to the originating console | The "payment gateway frontend URL" in endpoint config does not match the actually deployed domain |
| Payment auth reports domain not registered / invalid callback | The authorization domain registered on the open platform does not match the payment gateway domain |
| Desktop shows the mobile page | Normal — dispatch is by UA; check the link does not carry ?device=mobile |
| Payment inside WeChat prompts domain not verified | Verification file not uploaded, or the payment directory not configured |
Related Links
- Overview: the responsibility map and the address-generation mechanism
- Authentication & Relay: auth callbacks and login relay
- Run: backend and frontend deployment overview
- Channel Integration: domain verification and joint testing