JSAPI Singing

Update Time：2025.03.21

The merchant backend obtains a signing url by requesting this interface, and then requests the signing url on the h5 page open inside of WeChat.

1. API Intro

Applicable object: Common mode Institutional mode

Request Url: https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/jsapi-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]	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]	Yes	Body Openid of the user under the merchant’s appid For details, see Obtaining openid Example: ouFhd5X9s9WteC3eWRjXV3lea123
Url of redirecting back after signing	return_url	string[1, 256]	No	Body Specifies the url to redirect back after signing, the domain of the url should be provided when applying authority for backend configuration. It won’t redirect back to this url if the domain is not configured. Example: www.yoursite.com
Expire time of signing ID	expired_time	string[1, 32]	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

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
Signing redirect URL	sign_url	string[1,512]	Yes	The validity of sign_url is 10 minutes in default, consumers could be redirected to WeChat signing page by accessing this url. Example: https://apihk.mch.weixin.qq.com/v3/global/papay?sessionid=202109211651

Example:

Normal return

1{
2  "sign_url": "https://apihk.mch.weixin.qq.com/v3/global/papay?sessionid=202109211651"
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