Mini Program Signing

Update Time：2025.03.21

The merchant backend obtains a signing session ID by requesting this interface, and then calls the signing page of the mini program for Auto-debit through the mini program signing interface.

Tips：

The mini-program signing is divided into two steps. In step 1, the session_id is obtained through the pre-signing interface, and then the signing is invoked through step 2.

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/miniprogram-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 for Institutional 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]	No	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]	Yes	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 pre-sign ID	expired_time	string[1, 64]	No	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

Request 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  "success_notify_url": "https://yoursite.com",
8  "user_client_ip": "119.145.83.6",
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

SUCCESS

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

ERROR

1{
2"code":"SYSTEM_ERROR",
3"message":"Parameter error"
4}

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	SYSTEM_ERROR	System error	Please try the request again

Step 2: Mini Program Signing API

wx.navigateToMiniProgram

Applicable object: Common mode Institutional mode

Interface: wx.navigateToMiniProgram(OBJECT) interface

Description: This interface has been supported since Version 6.5.9 of iOS WeChat client and Version 6.5.10 of Android client.

Request Parameters

Name

Variable Name

Type

Required

Description

WeChat signing mini program appid

appId

string[1, 32]

Yes

Fixed value wxbd687630cd02ce1d Please add this appid to the configuration item navigateToMiniProgramAppIdList of the mini program configuration file app.json
Example: wxbd687630cd02ce1d

Data of the scenario information that is passed to the mini program

extraData

object

Yes

Body For details, see the description about the extraData field

Data of the scenario information that is passed to the mini program

Example:

Example

1wx.navigateToMiniProgram({
2	appId: wxbd687630cd02ce1d,
3	path: 'pages/Oversea/walletSelect?sessionId=201710180325670965',
4	extraData: {},
5	success(res) {
6		// Jumped to the signing mini program successfully
7	},
8	fail(res) {
9		// Failed to jump to the signing mini program 
10	}
11})

Response Parameters

Name	Variable Name	Type	Required	Description
Auto-debit contract ID	contract_id	string[1, 64]	Yes	Auto-debit contract ID returned by WeChat after successful signing Example: 201710180325670965

Example:

Example

1App({
2	onShow(res)  {
3		if  (res.scene  ===  1038)  {  //Scenario value 1038: return from the opened min program
4			const  { 
5				appId,
6				 extraData 
7			}  =  res.referrerInfo
8			if  (appId  ==  'wxbd687630cd02ce1d')  {  // appId is wxbd687630cd02ce1d: jump back from the signing min program
9				if  (typeof  extraData  ==  'undefined') {
10					// TODO
11					// The client min program is not sure of the signing result and needs to request the merchant-side background to confirm the signing result
12					return;
13				}
14				if (extraData.return_code  ==  'SUCCESS') {
15					// TODO
16					// The client min program signs successfully and needs to request the merchant-side background to confirm the signing result
17					var  contract_id  =  extraData.contract_id
18					return;
19				} 
20				else  {
21					// TODO
22					// Signing failed
23					return;
24				}
25			}
26		}
27	}
28})