Product Documentation General instructions Access Guidelines FAQs

Development Guide

Update Time：2025.03.24

Service process

This payment method is explained below. The Unified Order API, Query Order API, and accepting order notifications require signatures, which are created on the Merchant's service backend, as shown in Figure 9.6.

Figure 9.6 In-app payment sequence chart

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

Step 1:Payer selects products within the Merchant's app, submits the order, and chooses WeChat payment.

Step 2:The Merchant receives payer's payment transaction and calls the Unified Order API. For more information, see 【Unified Order】.

Step 3:he Unified Order API returns a normal prepay_id, and creates a signature based on the signature rules. The relevant data is transferred to the Merchant's app. Fields contained in the signature include cappId, partnerId, prepayId, nonceStr, timeStamp, and package.

Note:the value format of package is Sign=WXPay

Step 4:The Merchant's app uses the SDK to open WeChat payment within WeChat. For more information, see 【App-based Development Guide】

Step 5:The Merchant's backend receives payment notifications. For more information, see 【Payment Result Notification】

Step 6:The Merchant's backend queries the payment result. For more information, see 【Query Order】.

App-based Development Guide

Instructions for iOS

We will use Xcode10.0 running an iOS 7.0 environment as an example to illustrate the process.

1.APPID for Project Settings

After the Merchant has successfully applied for an App in the WeChat Open Platform, the Platform will provide an unique APPID to the Merchant. When creating a project in Xcode, the developer should enter the APPID value in the “URL Schemes” field, as marked in red in Figure 8.7.

Figure 8.7

2.APPID for Registration

The WeChat SDK “lib” and “head” files should be imported into the Xcode project. Before calling the API, you should register your APPID with WeChat, as shown below:

1[WXApi registerApp:@"wxd930ea5d5a258f4f" withDescription:@"demo 2.0"];

3.Call Payment

The Merchant's server calls the Unified Order API (for more information, see Section 9.1 Unified Order) to create an advance transaction. After obtaining prepay_id and signing relevant parameters, the advance transaction data is transferred to the App to start a payment. See below for an example on how to do this:

1PayReq *request = [[[PayReq alloc] init] autorelease];
2request.partnerId = @"10000100";
3request.prepayId= @"1101000000140415649af9fc314aa427";
4request.package = @"Sign=WXPay";
5request.nonceStr= @"a462b76e7436e98e0ed6e13c64b4fd1c";
6request.timeStamp= @"1397527777";
7request.sign= @"582282d72dd2b03ad892830965f428cb16e7a256";
8[WXApi safeSendReq:request];

4)Payment Result Callback

As shown in the sample included in the SDK, onResp() can be added to WXPayEntryActivity. After completing payment, WeChat will be redirected to the Merchant's app and do a callback using onResp(). The Developer receives notifications in this function and determines the returned error code if necessary. If the payment is successful, the payment result shall be queried from the WeChat payment system and shown to Payer. The payment result is subject to the payment notifications from the WeChat payment system and the result returned to the Payer after querying the API. See below for an example on how to do this:

1- (void)onResp:(BaseResp *)resp {
2    if ([resp isKindOfClass:[PayResp class]]) {
3        PayResp *response = (PayResp *)resp;
4        switch (response.errCode) {
5            case WXSuccess:
6     	    		//Prompt of successful payment according to server-based query result or API returned data
7     	     		NSlog(@"Payment Successful");
8            	break;
9        	 default: 
10           	NSlog(@"Payment Failed， retcode=%d",resp.errCode);
11            	break;
12            }
13	}
14}

errCode value list:

Name	Description	Solution
0	Success	Displays the success page
-1	Error	This may be caused by signature error, unregistered APPID, incorrect APPID in project settings, unmatched APPID in the registration and project settings, or other exceptions.
-2	Canceled by user	This occurs when the Payer cancels payment and returns to the App. In this case, no further steps are required.

Instructions for Android

1.Backend Settings

After the Merchant has successfully applied for an App in the WeChat Open Platform, the Platform will provide an unique APPID to the Merchant. For payment security reasons, the Merchant's app package name and signature must match in the Platform. Only when these are configured properly can payment be initiated. This can be done in “App Platform (应用平台)”->”Android App (Android 应用)” on the WeChat Open Platform, as marked in red in Figure 8.8.

Figure 8.8

The App package name is the same as the one set in the configuration file "AndroidManifest.xml" of the app’s project settings. For an example, look at the package name "net.sourceforge.simcpux" in Figure 8.9.

The App signature is the keystore used for compiling according to project's app package name, which should be a 32-bit md5 string generated by a signature tool. If developers install the signature tool on a testing phone, they can run it to generate the app’s signature string, as shown in the strings in green in Figure 8.9. Download a signature tool

Figure 8.9

2.APPID for Registration

The WeChat JAR package should be imported into the App project. Before calling the API, you need to register your APPID with WeChat, as shown below:

Before calling the API, you should register your APPID with WeChat, as shown below:

1final IWXAPI msgApi = WXAPIFactory.createWXAPI(context, null);
2// Register this app with WeChat
3msgApi.registerApp("wxd930ea5d5a258f4f");

3.Call Payment

The Merchant's server calls the Unified Order API (for more information, see Section 9.1 Unified Order) to create an advance transaction. After obtaining prepay_id and signing relevant parameters, the advance transaction data is transferred to the App to start a payment. See below for an example of how to do this:

1IWXAPI api;
2PayReq request = new PayReq();
3request. appId = "wxd930ea5d5a258f4f";
4request. partnerId = "1900000109";
5request.prepayId= "1101000000140415649af9fc314aa427",;
6request. packageValue = "Sign=WXPay";
7request.nonceStr= "1101000000140429eb40476f8896f4c9";
8request.timeStamp= "1398746574";
9request.sign= "7ffecb600d7157c5aa49810d2d8f28bc2811827b";
10api.sendReq(req);

4.Payment Result Callback

As shown in the sample included in the SDK, onResp() can be added to WXPayEntryActivity. After completing payment, WeChat will be redirected to Merchant's app and do a callback using onResp(). The Developer receives notifications in this function and determines the returned error code if necessary. If the payment is successful, the payment result shall be queried from the WeChat payment system and shown to Payer. The payment result is subject to the payment notifications from the WeChat payment system and the result returned to the Payer after querying the API. See below for an example on how to do so:

1public void onResp(BaseResp resp) {
2	if (resp.getType() == ConstantsAPI.COMMAND_PAY_BY_WX) {
3		Log.d(TAG, "onPayFinish, errCode = " + resp.errCode);
4		AlertDialog.Builder builder = new AlertDialog.Builder(this);
5		builder.setTitle(R.string.app_tip);
6	}
7}

errCode value list:

Name	Description	Solution
0	Success	Displays the success page
-1	Error	This may be caused by signature error, unregistered APPID, incorrect APPID in project settings, unmatched APPID in the registration and project settings, or other exceptions.
-2	Canceled by users	This happens occurs when the Payer cancels payment and returns to App. In this case, no further steps are required.