---
url: "https://pay.weixin.qq.com/doc/v2/merchant/4011987295.md"
title: "H5纯签约 "
doc_id: 4011987295
---

>更新时间：2026.03.18

该方式适用于手机、平板电脑等使用H5浏览器的设备场景使用微信签约扣款。商户在网站前端通过微信支付H5纯签约接口与用户签订委托扣款协议，再通过后台接口申请扣款来完成代扣交易。

注意

1、如果签约成功，微信会异步通知给商户（notify\_url为通知路径），如果签约失败则不通知。

2、调用此接口后获得redirect\_url，需要在前端跳转到redirect\_url，在商户的前端页面<head>处需要添加声明<meta name="referrer" content="no-referrer-when-downgrade">

3、此外，不能使用window.location.replace(redirect\_url)的方式跳转，而要通过window.location.href = redirect\_url的方式跳转。

4、在redirect\_url页面，会唤起微信。无论用户是否同意，redirect\_url的页面会在3秒后自动回到refer页面。

5、如果获取的refer只有域名没有路径，那么签约完成后，需要用户手动回到浏览器。

特别提醒：该业务接口暂未全面开放，需要单独申请后方可使用，详情可查看申请指引：[委托代扣-App&H5纯签约申请流程](https://doc.weixin.qq.com/doc/w3_AJ8AyQbhAD4CN41Af5nZSQvqQrvcM?scode=AJEAIQdfAAor2TVMnMAJ8AyQbhAD4)



## 接口说明

适用对象：直连商户

请求URL： https://api.mch.weixin.qq.com/papay/h5entrustweb

请求方式： GET

签名方式： HMAC-SHA256、MD5

是否需要证书： 否

## 请求参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 应用ID | appid | string\[1,32\] | 是 | 直连商户申请的公众号或移动应用appid。<br>示例值：wxcbda96de0b165486 |
| 商户号 | mch\_id | string\[1,32\] | 是 | 商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com<br>示例值：1200009811 |
| 模板id | plan\_id | string\[1,28\] | 是 | 协议模板id，设置路径见[开发步骤](https://pay.weixin.qq.com/doc/v2/merchant/4011986709.md)。<br>示例值：12535 |
| 签约协议号 | contract\_code | string\[1,128\] | 是 | 商户侧的签约协议号，由商户生成，只能是数字、大小写字母的描述且在同一个商户号下唯一。<br>示例值：100000 |
| 请求序列号 | request\_serial | int 64 | 是 | 商户请求签约时的序列号，要求唯一性。禁止使用0开头，序列号主要用于排序，不作为查询条件，纯数字，范围不能超过int64的范围（9223372036854775807）。<br>示例值：1000 |
| 用户账户展示名称 | contract\_display\_account | string\[1,128\] | 是 | 签约用户的名称，用于用户签约页面的“开通账号”处进行展示，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段<br>示例值：微信代扣 |
| 回调通知url | notify\_url | string\[1,256\] | 是 | 用于接收签约成功消息的回调通知地址，以http或https开头，通知url必须为外网可访问的url，不能携带参数。<br>请对notify\_url参数值进行encode处理,注意是对参数值进行encode，例如参数为notify\_url=“https://weixin.qq.com”，则需要encode的内容为https://weixin.qq.com。<br>示例值：https://weixin.qq.com |
| 版本号 | version | string\[1,8\] | 是 | 固定值1.0<br>示例值：1.0 |
| 签名 | sign | string\[1,64\] | 是 | 详见[签名生成算法](https://pay.weixin.qq.com/doc/v2/merchant/4011985891.md)<br>示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 签名类型 | sign\_type | string\[1,32\] | 否 | MD5或者HMAC-SHA256，不填默认HMAC-SHA256<br>注意：H5的预签约的默认签名方式是(sign\_type为空或无该字段)：HMAC-SHA256<br>示例值：MD5 |
| 时间戳 | timestamp | string\[1,10\] | 是 | 系统当前时间，10位<br>示例值：1414488825 |
| 客户端 IP | clientip | string\[1,32\] | 是 | 用户客户端的IP地址，同时支持IPV4和IPV6。<br>示例值：119.145.83.6 |
| 回调应用appid | return\_appid | string\[1,32\] | 否 | 用来控制签约页面结束后的返回路径。<br>当指定该字段时，且商户模板标注商户具有指定返回app的权限时，签约成功将返回return\_appid指定的app应用，如果不填且签约发起时的浏览器UA可被微信识别，则跳转到浏览器，否则留在微信<br>示例值：wxcbda96de0b165486 |

## 请求示例

URL

```
https://api.mch.weixin.qq.com/papay/h5entrustweb?appid=wx426a3015555a46be&contract_code=122&contract_display_account=name1&mch_id=1223816102&notify_url=https%3A%2F%2Fwww.qq.com%2Ftest%2Fpapay&plan_id=106&request_serial=123& return_appid= wxcbda96de0b165542&clientip=12.1.1.12&timestamp=1414488825&version=1.0&sign= 130C7B07DD3B8074F7BF8BEF5C9A86487A1C57478F8C55587876B9C782F72036
```

## 返回参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 返回状态码 | return\_code | string\[1,16\] | 是 | SUCCESS/FAIL<br>非签约结果标识，签约发起是否成功需要查看result\_code来判断。<br>示例值：SUCCESS |
| 返回信息 | return\_msg | string\[1,128\] | 否 | 返回信息，如非空，为错误原因<br>如：签名失败 等。<br>示例值：签名失败 |

以下字段在return\_code为SUCCESS的时候有返回

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 业务结果 | result\_code | string\[1,16\] | 是 | SUCCESS/FAIL<br>示例值：SUCCESS |
| 业务结果描述 | result\_msg | string\[1,128\] | 否 | 如非空，为错误原因，如签名错误<br>示例值：SIGN\_ERROR |
| 跳转URL | redirect\_url | string\[1,256\] | 否 | redirect\_url的有效期为10分钟，跳转签约页面url，用户通过跳转访问此URL即可进入微信签约页面，进行签约。注意这里请求跳转url的页面地址必须在微信后台配置（申请H5签约权限时配置）。<br>示例值：https://payapp.weixin.qq.com |

## 返回示例

正常示例

```
<xml>
 <return_code><![CDATA[SUCCESS]]></return_code>
 <return_msg><![CDATA[PARAM_ERROR]]></return_msg>
 <result_code><![CDATA[SUCCESS]]></result_code>
 <result_msg><![CDATA[SIGN_ERROR]]></result_msg>
 <redirect_url><![CDATA[https://payapp.weixin.qq.com]]></redirect_url>
</xml>
```