Payment Routing
A merchant may hold several receiving accounts (channel merchants) on the same channel. Payment routing answers the question: when a payment request comes in, which channel merchant receives it? Routing takes effect per app and is configured in the merchant-managed app workbench; once configured, merchant orders and gateway payments are dispatched automatically by it.
How Routing Works
- Automatic dispatch: when an order does not specify a channel merchant, the system matches it against the app's route config, fills in the product, channel merchant and capability, then enters the channel.
- Deterministic mapping: one channel (or payment method) maps to exactly one channel merchant. The current version has no round-robin, weights or priorities.
- Direct specification bypasses routing: the gateway payment "direct" mode, or API calls that pass a channel merchant explicitly, do not go through route config.
- Opening the routing page for the first time auto-creates a default strategy (by-channel mode) with nothing configured — you still need to fill it in.
Entry: Merchant Management → Merchant List → Manage → Merchant Workbench → App Workbench → the "Payment Routing" card. The page must be opened from the app workbench (it carries the merchant and app parameters); direct visits show a missing-parameter notice.
Two Configuration Dimensions
| Dimension | Granularity | Elements of each entry | Best for |
|---|---|---|---|
| By channel (default) | Payment channel (WeChat/Alipay/Union/Douyin...) | channel → channel merchant | One receiving account per channel, simple |
| By payment method | Specific method (e.g. WeChat JSAPI, WeChat QR, Alipay H5) | method → channel merchant + capability (must be paired) | Splitting methods of the same channel into different accounts |
- In by-channel mode, the capability is derived at runtime by the product — no need to configure it;
- The two dimensions are mutually exclusive — only one "active mode" exists at a time. After switching dimensions and saving, you must click "Set as Active" and confirm; otherwise runtime keeps resolving by the previous mode. Toggling the radio alone does nothing.
- The active mode is labeled "Active" on the toolbar.
Configuration Walkthrough
By Channel (first-time setup)
- Enter the routing page from the app workbench (a default by-channel strategy is created on first open);
- Click "Edit" and pick the channel merchant for each payment channel card (partial configuration is fine; candidates only list the merchant's own enabled, product-matching channel merchants);
- "Save" and confirm the overwrite;
- If the active mode is not "by channel", click "Set as Active".
By Payment Method (fine-grained splitting)
- Click "Edit" and switch the dimension to "by payment method";
- Row by row, pick "channel merchant + payment capability" — both selected together or left empty together; leave unused rows empty;
- "Save" and confirm the overwrite;
- Click "Set as Active"; from then on orders resolve by payment method.
Pairing rule
"Channel merchant + capability" must be filled in pairs; the page and the backend both reject saving when only one is set. Each payment method can only have one row.
Hit Preview
You don't need a real payment to verify the config: on the gateway payment config page, when the payment form is set to "follow routing" or "specify payment method", each combination shows a routing hit preview column telling you which channel merchant and capability an order would use; unconfigured combinations show "Not configured", and the header shows a "routing hits x/y" coverage stat. Scanning the coverage here after configuring is faster than test-paying.
Common Rejections and Troubleshooting
When routing rejects an order, the error names the cause:
| Error / symptom | Cause | Fix |
|---|---|---|
| Channel merchant / product environment mismatch | A sandbox channel merchant wired to a production product (or vice versa); the merchant's environment flag is frozen at creation | Provision a channel merchant for the target environment and update routing |
| Channel merchant disabled | Disabled channel merchants are never hit | Re-enable it or point routing elsewhere |
| Payment product disabled | Disabled products cannot start new payments | Enable the product in Payment Product Configuration |
| Channel has no channel merchant configured | The channel is empty in by-channel mode | Fill in that channel's route |
Configuration health check
The merchant workbench's configuration check raises alerts like "enabled app missing routing strategy" — follow the prompt into the routing page to configure. Route changes take effect immediately after saving, no restart needed.
Related Links
- Channel Merchants — routing targets: creation and enable/disable
- Payment Product Configuration — product status and environment (affect routing hits)
- App Configuration — the app workbench and the routing entry
- Gateway Payment — the main consumer of routing and the hit preview