Payment Channel Integration
This page expands Steps 5 and 6 of From Deployment to First Payment, covering the full details of the two flagship channels — Alipay (direct) and WeChat Pay (direct) — from channel-side preparation to key configuration, including the differences between sandbox and production environments.
Other channels (UnionPay, Douyin, etc.) follow the same shape: create a channel merchant → configure keys in the channel merchant detail → verify. Specific parameters are in the Payment Channels series.
Common Flow
Environment snapshot (important)
At creation, a channel merchant freezes the sandbox / production snapshot of the payment product's environment at that moment; it never changes with product switching afterwards, and channel merchants whose environment does not match are excluded from routing. Switch the environment in "Access Configuration → Payment Product Configuration" first, then create the channel merchant; sandbox and production each need their own set of channel merchants. See From Deployment to First Payment - Step 3.
Creation entry and form comparison of the two channels:
| Channel | Creation form fields | Key configuration location |
|---|---|---|
| Alipay (direct) | Channel merchant name + Alipay merchant user ID (PID starting with 2088) | Channel merchant detail → App Management → "Manage" on the app card → Key Configuration |
| WeChat Pay (direct) | Channel merchant name + WeChat Pay merchant number (mchId) | Channel merchant detail → Basic Management → Direct Key Configuration |
The entry for creating channel merchants is Merchant Workbench → Channel Merchants → Create Channel Merchant (a two-step wizard: pick product → fill in channel info).
Alipay (direct)
Channel-Side Preparation
- Register an Alipay Open Platform account and create a web/mobile app to obtain the app ID (AppId);
- Generate an RSA2 key pair with Alipay's official key tool (public key mode); configure the app public key into the open platform and obtain the Alipay public key from the open platform "Open Platform Keys" page;
- For sandbox integration, use the sandbox app and sandbox buyer account provided on the open platform "Sandbox" page — no business verification required.
App Management and Key Configuration
Alipay direct keys are organized per app: enter the channel merchant detail → App Management group → App Management, first register the Alipay app (app name, Alipay app ID, app type), then configure credentials in the app card's "Manage" → Key Configuration tab:
Basic Configuration — choose one of two authentication modes:
| Authentication mode | Fields to configure | Notes |
|---|---|---|
Public key (public_key) | App ID, Alipay public key, app private key | Simplest to configure; first choice for integration |
Certificate (cert) | App ID, app public key certificate, Alipay public key certificate, Alipay root certificate (three .crt files uploaded), app private key | Required by some APIs (e.g. transfers) |
Communication Key (optional): an AES key obtained from the open platform console, used only for encrypting/decrypting certain API messages.
The most common misconfiguration
The "Alipay public key" is the key shown by the open platform for verifying Alipay's messages — not the "app public key" you generated yourself. Swapping the two is the number-one cause of integration failure. In certificate mode, the setting must also match the "interface signature mode" configured on the open platform side.
No gateway URL needs configuring: the system automatically picks the Alipay gateway by the channel merchant's environment (sandbox / production), and there is no gateway field in the UI. Whether the keys are correct is verified when payment debug initiates a transaction (this channel has no "connection test" button for now).
Supported Pay Methods
alipay_qr QR, alipay_jsapi (incl. mini program), alipay_pc, alipay_h5, alipay_app, and alipay_barcode payment code — 6 in total.
WeChat Pay (direct)
WeChat has no sandbox environment
WeChat does not provide a sandbox integration environment (only Alipay does). The sandbox flow of the go-live main track applies to Alipay (direct) only; WeChat channel merchants can only be created in the production environment — verify with small real payments during integration, and once verified they are ready for live use.
Channel-Side Preparation
Obtain the following credentials from the WeChat Merchant Platform (location: Account Center → API Security):
| Credential | Where to obtain | Corresponding field |
|---|---|---|
WeChat Pay merchant number mchId | Merchant platform home | Filled in when creating the channel merchant |
| API V3 key | API Security → Set APIv3 Key | API V3 key |
API certificate apiclient_cert.pem + private key apiclient_key.pem | API Security → Apply for API Certificate | API certificate / API certificate private key |
| Certificate serial number | Serial number of the certificate | Certificate serial number |
Payment public key pub_key.pem + key ID | Merchant platform "Payment Public Key" (new merchants) | Payment public key / payment public key ID |
Direct Key Configuration
Enter the channel merchant detail → Basic Management → the Direct Key Configuration drawer; the fields come in two groups, "API Key" and "Payment Certificates / Payment Public Key":
| Group | Fields | Required |
|---|---|---|
| API key | API V3 key | Yes |
| Payment certificates | API certificate (apiclient_cert.pem), certificate serial number | Yes |
API certificate private key (apiclient_key.pem) | No (blank keeps the existing value) | |
| Payment public key | Payment public key (pub_key.pem), payment public key ID | Yes |
Background of the two credential sets
Merchants onboarded by WeChat after 2024 use a "payment public key" instead of "platform certificates"; older merchants can still use the certificate system. This system assembles the SDK credentials from the "merchant certificate + serial number + payment public key" combination: the certificate signs merchant-side requests and the payment public key verifies WeChat-side messages — just fill in what the merchant platform actually provides; when editing, a blank encrypted field keeps the existing value.
Payment Apps (WeChat)
WeChat's wxAppId is not part of the keys; it is registered separately per app: Merchant Workbench → Payment Configuration → Payment Apps (WeChat) (or Payment Management → Payment Apps). Each record holds the app name, app type, WeChat AppId, and AppSecret.
Hard binding between app types and pay methods:
| Pay method | Required app type |
|---|---|
wechat_jsapi / unified cashier (opened inside WeChat) | Official Account (the scene hard-binds openId; web authorization required) |
wechat_mini mini program payment | Mini Program |
wechat_app APP payment | Mobile App |
wechat_qr / wechat_h5 / wechat_barcode | Any of the above |
So before accepting WeChat JSAPI or mini program payments, you must first register an app of the corresponding type under "Payment Apps (WeChat)", otherwise routing cannot resolve.
Transfer Scene Configuration (only for WeChat transfers)
WeChat merchant transfers require the message to carry a transfer scene. Location: channel merchant detail → Transaction Configuration → Transfer Scene:
- Transfer scene ID: the scene registered under the "Merchant Transfer" product in the WeChat merchant platform (e.g.
1000-xxx); - Transfer initiating app: the payment app corresponding to the appId carried in transfer messages.
Not needed if you only collect payments and never transfer.
Domain Verification Files
When you configure domain ownership and QR code rules, WeChat/Alipay fetch a verification file under the payment gateway domain and compare it for ownership. Upload the file contents into the system — the payment gateway's nginx has the reverse proxy built in (files are stored in the database and served dynamically by the backend; no manual file placement on the server):
Scenario 1: merchant-level — verification of the merchant's own official account / mini program domain (WeChat authorization callback)
- Download the verification file from the WeChat official account platform as prompted (e.g.
MP_verify_PjhdRxpB8FhG06Fr.txt); - Upload it to the system: merchant panel → Business Configuration → Domain Verification Files (operations staff can also upload it on the merchant workbench "Domain Verification Files" page);
- Applies to official account "web authorization domain / JS interface security domain" and mini program "business domain" verification; only
MP_verify_*.txtfiles are accepted.
Scenario 2: platform-level — verification files for the cashier/aggregate mini program "plain-link QR code" rules
- Configure plain-link QR code rules in the WeChat mini program backend (the system's three code prefixes:
/m/*QR terminals,/cm/*unified cashier,/am/*aggregate pay), or configure "associated plain QR codes" on the Alipay Open Platform; - The verification file downloaded from the platform (a random-name .txt for WeChat, .html for Alipay) is uploaded by operations under Payment Management → Access Configuration → Domain Verification Files;
- The verification file answers same-name requests verbatim under the domain root path and the
/m/,/cm/,/am/directories (platform fetches are not redirected).
After uploading, complete the domain/rule configuration on the corresponding platform and it takes effect.
Supported Pay Methods
wechat_qr QR, wechat_jsapi, wechat_h5, wechat_app, wechat_mini mini program, and wechat_barcode payment code — 6 in total.
Channel Merchant Detail Groups Overview
After creating a channel merchant, enter the detail via "Manage" in the list; the group structure:
| Group | Alipay (direct) | WeChat (direct) |
|---|---|---|
| Basic Management | Basic info | Basic info, Direct Key Configuration |
| Transaction Configuration | Transfer scene, transfer initiating app | Transfer Scene, transfer initiating app |
| App Management | Merchant apps (app ID + key configuration), capability binding | App binding, capability binding |
FAQ
| Symptom | Cause and handling |
|---|---|
| Alipay reports "key error / signature verification failed" | Alipay public key and app public key swapped; or the authentication mode is inconsistent with the open platform "interface signature mode" |
| Alipay transfer reports insufficient permission | Transfer APIs require certificate mode; public key mode cannot call them; also check product permissions |
| WeChat reports "certificate serial number mismatch" | The serial number and the uploaded apiclient_cert.pem are not from the same certificate; re-download from the merchant platform |
| WeChat JSAPI reports "missing appid / openid" | No Official Account-type app registered under "Payment Apps (WeChat)", or the user openId was not obtained |
| Payment page opened in WeChat is blank / says domain not verified | Domain verification file not uploaded, or nginx does not reverse-proxy /MP_verify_*.txt |
| Payment reports "channel merchant environment mismatch" | The channel merchant's environment snapshot does not match the product's current environment; re-create the channel merchant in the correct order |
Related Links
- From Deployment to First Payment: the go-live main track (including the full sandbox verification flow)
- Business System Integration: system integration after keys are verified
- Payment Channels: parameter index of all channels