H5 Signing API
Latest update time：2024.03.18 Release notes
The merchant backend obtains a signing url by requesting this interface, and then requests the signing url on the h5 page to redirect to WeChat to complete signing.
1. API Intro
Applicable object: Common mode Institutional mode
Request Url: https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/h5-pre-entrust-sign
Request method: POST
Pathparameter is a path parameter.
Queryparameter needs to be passed in the request URL.
Bodyparameter 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 forCommon mode Example: wxcbda96de0b165486 |
| Sub-merchant ID | sub_mchid | string[1, 32] | Yes | Body Sub-merchant ID allocated by WeChat Pay Note: Only forInstitutional mode Example: 10000097 |
| App ID of the service provider | sp_appid | string[1, 32] | Yes | Body Appid bound to the service provider Note: Only forInstitutional 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 |
| Client IP | user_client_ip | string[1, 32] | Yes | Body Specifies the the IP of consumer Example: 119.145.83.6 |
| Appid of application to redirect back | return_appid | string[1, 32] | No | BodySpecifies the redirect back route after signing. The appid should be configured when applying the product authority.
If this value is set and the merchants have got the authorization, consumers would be redirected back to a specified APP after signing is successful. If this value is not set, and the source request browser UA could be recognized by WeChat, consumers will be redirect back to merchant source page after sigining is successful, while consumers might stay in WeChat when source UA cannot be recognized. Example: wxcbda96de0b165486 |
| 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:
{
"appid": "wxcbda96de0b165486",
"expired_time": "2021-11-20T13:29:35+08:00",
"out_contract_code": "100001256",
"plan_id": 123,
"return_appid": "wxcbda96de0b165486",
"return_url": "https://yoursite.com",
"success_notify_url": "https://yoursite.com",
"user_client_ip": "119.145.83.6",
"user_display_name": "Zhang San"
}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:
{
"sign_url": "https://apihk.mch.weixin.qq.com/v3/global/papay?sessionid=202109211651"
}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. |
| 403 | CONTRACT_NOT_EXIST | The contract cannot be found | Please check whether the request contract is correct or whether it is terminated. |
| 400 | PARAM_ERROR | Parameter error | Please check the request parameter format. |
| 500 | SYSTEMERROR | System error | Please try the request again |
Page navigation
