Development Guide

Update Time：2025.03.24

Service process

Below shows how the merchant's backend interacts with the WeChat payment system:

Step 1:Users submit order on vendor’s page and select to pay by WeChat payment

Step 2:The Vendor's server calls the Unified Order API to create an order and get the payment jump url (trade_type = MWEB).

Step 3:hWeChat payment will verify the vendor’s authority

Step 4:The WeChat payment server returns payment jump url to the vendor to call WeChat payment

Step 5:The vendor returns the payment jump url to the front-end page

Step 6:The vendor will request the payment jump url through front-end page (WeChat will verify the request source, which is the “payment directory”, so please configure it in the WeChat backstage).

Step 7:The payment jump url will call the WeChat payment.

Step 8:The jump page will be closed when WeChat client is loaded.

Step 9:Jump back to the vendor’s page when payment is complete.

Guide for Obtaining User IP by H5 Payment

HH5 Payment requires merchants to upload the user’s real IP address "payer_client_ip" in the unified ordering API. The following guides for obtaining the user’s IP are provided to ensure that the user’s IP address obtained by WeChat is consistent with that obtained by the merchant.

Without agent

The way to obtain the IP is relatively simple when the front-end access layer of the merchant. Get 'REMOTE_ADDR' directly.

With agent

In the case of an agent, as the client needs to be replaced to access the server, when the request packet passes through the reverse agent, the IP header of the IP packet is modified in the agent server, and the source IP address of the packet header obtained by the back-end web server is the IP address of the agent server. Therefore, the backend server program cannot obtain the user's real IP.

When nginx has an agent:

Add the following to the configuration in nginx:

1vi /usr/local/apache/conf/httpd.conf
2Include conf/extra/httpd-remoteip.conf
3vi /usr/local/apache/conf/extra/httpd-remoteip.conf
4LoadModule remoteip_module modules/mod_remoteip.so
5RemoteIPHeader X-Forwarded-For
6RemoteIPinternalProxy 127.0.0.1
7

When Apache has an agent:

1proxy_set_header Host $host;
2proxy_set_header X-Real-IP $remote_addr;
3proxy_set_header X-Real-Port $remote_port;
4proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
5

Code example

1string  GetClientIp(CgiInput *  poInput)  { 
2	string  client_ip  =  ""; 
3	string  strClientIPList; 
4	GetHttpHeader("X-Forwarded-For",  strClientIPList);  
5	if  (strClientIPList.empty())  { 
6		GetHttpHeader("X-Real-IP",  strClientIPList); 
7	}  
8	if  (!strClientIPList.empty())  { 
9		size_t  iPos  =  strClientIPList.find( "," ); 
10		if ( iPos  !=  std::string::npos )  { 
11			client_ip  =  strClientIPList.substr( iPos ); 
12		} 
13		else  { 
14			client_ip  =  strClientIPList; 
15		} 
16	}  
17	if  (client_ip.empty())  { 
18		GetHttpHeader("PROXY_FORWARDED_FOR",  strClientIPList); 
19		//Perform compatibility 
20		if (strClientIPList.empty())  { 
21			client_ip  =  getRemoteAddr(); 
22		} 
23		else  { 
24			size_t  iPos  =  strClientIPList.find( "," ); 
25			if ( iPos  !=  std::string::npos )  { 
26				client_ip  =  strClientIPList.substr( iPos ); 
27			} 
28			else  { 
29				client_ip  =  strClientIPList; 
30			}  
31		} 
32	}  
33	if (!MMPayCommFunc::IsIp(client_ip)) 
34		client_ip  =  getRemoteAddr(); 
35	return  client_ip; 
36} 
37

FAQs

Callback page

In the normal process, the user will return to the page where the payment is initiated after completing the payment. If the user needs to return to the specified page, you can splice the redirect_url parameter after MWEB_URL to specify the callback page.
For example, if you want to redirect users to https://www.wechatpay.com.cn after the payment is completed, you can do the following:

1Suppose you get MWEB_URL= https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096 through the unified order API,
2
3the spliced address should be MWEB_URL= https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn.

Note:

Urlencode processing for redirect_url is required.
After the redirect_url is set, the user may return to the specified page when: 1. more than 5 seconds after the WeChat Pay middle page calls the WeChat cashier; 2. the user taps Cancel Payment or taps Finish after the payment is completed. There is no guarantee that the payment process has ended when the user returns to the specified page. Therefore, the redirect_url address set by the merchant cannot automatically perform the order check operation. The user needs to tap the button to trigger the order check operation. See the figure below for the display effect of returning to the specified page.

Other Common Errors

-->

Problem	Problem Description	Solution
	The network environment fails to pass the security verification. Please try again later.	The terminal IP (spbill_create_ip) of the unified order transmission on the merchant side is inconsistent with the terminal IP detected on WeChat when the user actually transfers the payment. This problem generally occurs when the merchant fails to transmit the correct terminal IP to spbill_create_ip while placing an order. Please refer to Guide for Obtaining Client IP for details. The network is changed when the unified order is placed and the payment is transferred. For example, the unified order is placed in the Wi-Fi network, after the order is successfully placed, the network is switched to 4G to transfer the payment. In such a case, the normal interception will be triggered and the user needs to re-initiate the payment process in the same network environment.
	The merchant parameter format is incorrect. Please contact the merchant.	The current referrer for H5 payment is empty. This problem generally occurs when the user directly accesses the page to initiate H5 Payment. Please follow the normal process to initiate the payment after being redirected, or capture the packet to check whether the referrer value is empty If H5 Payment is initiated in the app, you need to manually set the referrer in the webview, such as (Map extraHeaders = new HashMap(); extraHeaders.put("Referer", "the authorized domain submitted by the merchant when you apply for H5 Payment");//e.g. http://www.baidu.com ))
	The merchant has unconfigured parameters. Please contact the merchant.	The domain currently calling H5 Payment (obtained from the referrer WeChat) is inconsistent with the authorized domain submitted when you apply for H5 Payment. If you need to add or modify the authorized domain, please log in to the merchant platform corresponding to the merchant account in Product Center > Development Configuration to configure the authorized domain. If the redirect_url is set, check whether the domain of the redirect URL is the same as the authorized domain submitted when you apply for H5 Payment.
	Payment request has expired. Please re-initiate payment.	After the MWEB_URL returned by the unified order is generated, it will remain valid for 5 minutes. If it expires, regenerate the MWEB_URL and initiate the payment.
	Open the order outside WeChat to make payment.	H5 Payment cannot be called directly in WeChat. Instead, call it in a third-party browser.
	iOS: Signature verification failed Android: System is busy, please try again later	Make sure that the same MWEB_URL is only called by one WeChat account. If it is called by another WeChat account, please place an order again to generate a new MWEB_URL. If redirect_url is added to MWEB_URL, check whether the parameter splicing format is wrong, whether urlencode is performed on the value of redirect_url. See the following example format: https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f23161 9da20804912345&package=1037687096&redirect_url= https%3A%2F%2Fwww.wechatpay.com.cn