APP Singing

Update Time：2025.03.21

The merchant backend obtains a signing session ID by requesting this interface, and then calls the signing SDK to redirect to WeChat signing page.

Step 1:Obtaining Signing Session ID API

1. API Intro

Applicable object: Common mode Institutional mode

Request Url:https: //apihk.mch.weixin.qq.com/v3/global/papay/contracts/app-pre-entrust-sign

Request method: POST

Path parameter is a path parameter.

Query parameter needs to be passed in the request URL.

Body parameter needs to be passed in the request JSON.

UML

2. Request Parameters

Name	Variable Name	Type	Required	Description
App ID	appid	string[1, 32]	Yes	Body Appid bound to the merchant ID Note: Only for Common mode Example: wxcbda96de0b165486
Sub-merchant ID	sub_mchid	string[1, 32]	Yes	Body Sub-merchant ID allocated by WeChat Pay Note: Only for Institutional mode Example: 10000097
App ID of the service provider	sp_appid	string[1, 32]	Yes	Body Appid bound to the service provider Note: Only forI nstitutional mode Example: wxcbda96de0b165486
App ID of the sub-merchant	sub_appid	string[1, 32]	No	Body Appid bound to the sub-merchant ID for initiating signing Example: wxcbda96de0b165484
Template ID	plan_id	int	Yes	Body Agreement template ID, which is generated by WeChat Pay when the merchant submits a deduction permission application to WeChat Pay Example: 123
Signed contract No.	out_contract_code	string[1, 32]	Yes	Body The signed contract No. at the merchant side, generated by the merchant and must be unique at the merchant side Example: 100001256
Displayed user account name	user_display_name	string[1, 32]	Yes	Body The name of the signing user, displayed on the page; urlencode is not required for the value, and the parameter value does not support the non-3-byte coded characters of UTF8, e.g., emoji, so WeChat nickname cannot be passed to this field. Example: Zhang San
Signing success notification URL	success_notify_url	string[1, 256]	Yes	Body Callback notification URL starting with HTTPS; urlencode is not required for the value Example: https://yoursite.com
User ID under the merchant’s appid	openid	string[1, 128]	No	Body Openid of the user under the merchant’s appid For details, see Obtaining openid Example: ouFhd5X9s9WteC3eWRjXV3lea123
Client IP	user_client_ip	string[1, 32]	No	Body Specifies the the IP of consumer Example: 119.145.83.6
Expire time of signing ID	expired_time	string[1, 32]	Yes	Body Specifies the expire time of signing url. Time difference between expired_time and request time should be less than 10 minutes and bigger than 5 minutes for mobile h5 and PC web signing scenarios, while it icould be less than 2 hours and bigger than 5 minutes for other scenarios. If this value is not set, the validity of signing url is 10 minutes in default for mobile h5 and PC web signing scenarios, while it is 2 hours for other signing scenarios. This filed is in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. Example: 2021-11-20T13:29:35+08:00

Example:

Scenario 1:Common mode

1{
2 "appid": "wxcbda96de0b165486",
3  "expired_time": "2021-11-20T13:29:35+08:00",
4  "openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
5  "out_contract_code": "100001256",
6  "plan_id": 123,
7  "return_url": "https://yoursite.com",
8  "success_notify_url": "https://yoursite.com",
9  "user_display_name": "Zhang San"
10}

Scenario 2:Service Provide Mode/Institution Mode

1{
2  "expired_time": "2021-11-20T13:29:35+08:00",
3  "openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
4  "out_contract_code": "100001256",
5  "plan_id": 123,
6  "return_url": "https://yoursite.com",
7  "sp_appid": "wxcbda96de0b165486",
8  "sub_appid": "wxcbda96de0b165484",
9  "sub_mchid": "10000097",
10  "success_notify_url": "https://yoursite.com",
11  "user_display_name": "Zhang San"
12}

3. Response Parameters

Name	Variable Name	Type	Required	Description
Auto-debit signing session ID	session_id	string[1,128]	Yes	Auto-debit signing session ID returned by WeChat Example: 201710180325670965

Example:

Normal return

1{
2  "session_id": "201710180325670965"
3}

4. Error Codes

Error Codes	Error Message	Description	Solution
403	CONTRACT_EXISTED	The contract is already signed	The user has already sign the contract. If another contract is required to sign, please change the out_contract_code and retry.
400	PARAM_ERROR	Parameter error	Please check the request parameter format.
500	SYSTEMERROR	System error	Please try the request again

Step 2:Obtaining Signing Session ID API

Brief Introduction

Please refer to the following for the SDK description:

Android openSDK download (version >=5.3.1): Android resources

Android SDK guidelines: openSDK guidelines

iOS openSDK download (version >=1.8.4): iOS resources

iOS SDK guidelines: openSDK guidelines

API Used: WXOpenBusinessView

Interface compatibility:

● Compatibility with iOS: For Weixin version 7.0.3 or above, the developer can initiate Weixin mini-programs through this openSDK interface; for Weixin version below 7.0.3, the developer can jump to Weixin through this openSDK interface, but cannot initiate Weixin mini-programs. In this case, Weixin will prompt the user that the application request is invalid or the Weixin version is too low.
● Compatibility with Android: For Weixin version 7.0.3 or above, the developer can initiate Weixin mini-programs through this openSDK interface; for Weixin version below 7.0.3, the developer can neither jump to Weixin nor initiate Weixin mini-programs through this openSDK interface. In this case, the developer needs to prompt the user to update the Weixin.

Request Parameters

Name	Variable Name	Type	Required	Description
WeChat Redirecting Type	businessType	string[1,32]	Yes	Fixed value: wxpayOverseaEntrustAuthorization Example: wxpayOverseaEntrustAuthorization
Pre-sign ID	sessionId	string[1,128]	Yes	Session ID, got from pre-sign request Example: 20211115171992080208

Example:

Scenario 1: IOS

1WXOpenBusinessViewReq *req = [WXOpenBusinessViewReq object];
2req.businessType = @"wxpayOverseaEntrustAuthorization"; // Fixed value
3req.query = @"sessionId=20211115171992080208"; // The session ID got from pre-sign response
4req.extInfo = @"{\"miniProgramType\":0}"; // Fixed value
5[WXApi sendReq:req];

Scenario 2: Android

1// Sign
2int wxSdkVersion = api.getWXAppSupportAPI();
3if (wxSdkVersion >= Build.OPEN_BUSINESS_VIEW_SDK_INT) {
4WXOpenBusinessView.Req req = new WXOpenBusinessView.Req();
5req.businessType = "wxpayOverseaEntrustAuthorization"; // Fixed value
6String SesssionId = "20211115171992080208"; // The session ID got from pre-sign response
7req.query = "sessionId=" + SesssionId; // Configure parameter
8req.extInfo = "{\"miniProgramType\": 0}"; // Fixed value
9Boolean ret = api.sendReq(req);
10} else {
11// Consumer need to update the WeChat version to complete signing
12}
13 
14
15/******** Sample code for receiving signing success notification by onResp of WXEntryActivity*******/
16@Override
17public void onResp(BaseResp r) {
18if (r.getType() == ConstantsAPI.COMMAND_OPEN_BUSINESS_VIEW) {
19WXOpenBusinessView.Resp launchMiniProgramResp = (WXOpenBusinessView.Resp) r;
20String text = String.format("nextMsg=%snerrStr=%snbusinessType=%s",
21resp.extMsg, resp.errStr, resp.businessType);
22Toast.makeText(this, text, Toast.LENGTH_lONG).show();}
23}