1.Notes on Filling in notify_url

• Merchants must fill in the notify_url with the address of their own system, not with the example address found in the port document or demo.

• notify_url must be a complete full path address starting with either https:// or http://. Ensure that the domain name and IP address in the URL are accessible from the external network. Do not enter "localhost", "127.0.0.1", "192.168.x.x", or other local or internal IP addresses.

• notify_url cannot contain parameters.

• Examples of common errors:

2.Notes on Callback Processing Logic

• The code processing logic of notify_url cannot perform login status verification.

• Merchants system must return a response message within 5 seconds after receiving the notification of payment results. Otherwise, WeChat Pay will process this as a failed notification attempt and will resend the notification.

• The same notification may be sent multiple times to the merchants system. Therefore, the merchants system must be able to handle duplicate notifications correctly. If a notification has already been processed, WeChat Pay shall receive a successful notification callback.

• Merchants who have firewall policy restrictions on WeChat Pay callback IP addresses are required to add the following IP segments to the whitelist:

• To ensure security of the merchant systems, WeChat Pay may generate an incorrect signature for a very small number of responses or notification callbacks to detect whether the merchant system can correctly verify the signature.

3.Common Scenarios of Failed Callback Reception by Merchants

I. Callback URL Configuration Issues

1. Incorrect address configuration

   • The callback notification URL (notify_url) configured by the merchant on the WeChat Pay merchant platform or within the API parameters contains typographical errors, such as incorrect domain names or missing path segments;

   • The address does not use the publicly accessible HTTPS protocol, which is required by default for callback URLs in WeChat Pay;

   • Use of internal network addresses (e.g., 192.168.x.x, localhost) prevents WeChat Pay servers from accessing through internal networks.

2. Address lacks ICP filing / DNS resolution issues

   • The domain name associated with the callback URL has not completed ICP filing with the Ministry of Industry and Information Technology. This requirement is mandatory for domestic servers. While ICP filing is not required for overseas servers, it is essential to ensure that the domain name resolution functions properly;

   • The DNS resolution for the domain name failed due to issues such as expired resolution records or misconfigured A/AAAA records, preventing the WeChat Pay server from resolving the merchant server's IP address.

II. Network and Server Connectivity Issues

1. Merchant server firewall / security group blocking

   • The merchant server's firewall (e.g., Linux iptables, Windows Firewall) or the security group of the cloud service provider has not permitted incoming request for WeChat Pay callback notifications. It is necessary to add the WeChat Pay callback IP to the whitelist. The list of WeChat Pay callback IPs can be viewed at Notes on Callback Processing Logic;

   • The server has enabled security policies such as CC attack protection and WAF (Web Application Firewall), which mistakenly identified WeChat Pay callback requests as malicious and blocked them.

2. Network link failure

   • The network hosting the merchant's server experiences packet loss and high latency (e.g., exceeding 3 seconds), resulting in timeout of the notification request sent by WeChat Pay;

   • The CDN or reverse proxy (e.g., Nginx, Cloudflare) used by the merchant may be misconfigured, preventing the proper forwarding of the callback request to the backend business server.

III. Other Special Scenarios

1. If the merchant has not configured the apiv3key, WeChat Pay will not send a callback notification.

2. If the notify_url callback notification receiving address is not configured in the API, WeChat Pay will not send a callback notification.