About 642 wordsAbout 2 min
2025-06-24
Payment Domain Authorization
According to WeChat requirements, the merchant's domain must be added to WeChat's H5 payment authorized domains. The Referer request header must also be set. We default to adding the domain from your account opening application to WeChat's H5 payment authorized domains.
If you need to add other domains, please send the relevant application information to acquire-risk@pingpongx.com and CC acquire-ts@pingpongx.com.
Application materials:
- Merchant Client ID
- Merchant authorized domain
Payment Scenario Description
PC Payment
- Display WeChat payment QR code
- Users complete payment by scanning QR code with WeChat
- Page displays real-time payment status updates
Mobile Payment
- WeChat in-browser: Direct WeChat payment invocation is not currently supported, JSAPI call required per WeChat requirements.
- Non-WeChat browsers:
- iOS: Redirect to WeChat client
- Android: Display QR code or attempt to invoke WeChat
- Other cases: Display QR code for scan-to-pay
Note
- Your domain must be added to WeChat H5 payment authorized domains.
- WeChat has strict requirements for Referer, please ensure Referer request header is set.
- Ensure users access payment page through page redirection rather than direct access to payment link
Common Issues
Error message: "Merchant parameter format is incorrect, please contact merchant to resolve"
Problem cause:
- Referer request header is empty or missing
- User directly accesses payment link without page redirection
Solution:
- Ensure users access payment page through page redirection rather than direct access to payment link
- App WebView needs to manually set Referer request header:
Map<String, String> extraHeaders = new HashMap<>(); extraHeaders.put("Referer", "https://your-authorized-domain");
Error message: "Merchant has unconfigured parameters, please contact merchant to resolve"
Problem cause:
- Current webpage domain does not match H5 payment authorized domain configured in WeChat backend
Solution:
- Contact us to confirm if authorized domain is correct
- Modify or add correct authorized domain
Error message: "Payment request has expired, please initiate payment again"
Problem cause:
- Payment link exceeds 5-minute validity period
Solution:
- Re-call payment interface to generate new payment link
Error message: "Please open order in WeChat external browser to complete payment"
Problem cause:
- Using H5 payment method within WeChat client
Solution:
- Use JSAPI payment in WeChat environment
- Guide users to open payment page in external browser
Error message: "Signature verification failed" or "System busy"
Problem cause:
- Multiple WeChat accounts accessing same payment link
- Callback URL encoding is incorrect
Solution:
- Generate independent payment link for each user
- Ensure callback URL parameters are correctly encoded
Error message: "H5 transaction parameters passed by merchant are incorrect"
Problem cause:
- Client IP address is incorrect (such as using 127.0.0.1)
Solution:
- Use real client IP address
Referer Configuration Instructions
WeChat H5 payment has strict requirements for Referer (source domain in HTTP request header):
Referer function: WeChat server determines current webpage source domain through Referer header, checking if it matches H5 payment authorized domain configured in WeChat merchant platform.
Common Referer issue solutions:
| Issue Type | Specific Manifestation | Solution |
|---|---|---|
| Referer empty | Direct access to payment link or WebView without Referer set | Ensure access through page redirection; WebView manually set Referer |
| Domain mismatch | Current domain does not match authorized domain | Add or modify authorized domain in WeChat merchant platform |
| WebView configuration | App H5 unable to invoke payment | Manually add Referer Header |
