---
url: "https://pay.weixin.qq.com/doc/v2/partner/4011988366.md"
title: "APP纯签约"
doc_id: 4011988366
---

>更新时间：2026.06.09

外部App拉起微信客户端发起签约前，需先后台调用预签约接口完成预签约，获取pre\_entrustweb\_id，再拉起微信客户端，完成签约，返回App。

接口升级通知

委托代扣APP纯签约接口已于2025年9月23日升级为新版开发接口。此次升级采用平滑迁移策略：

- 存量模板：2025年9月23日前已申请APP纯签约的模板ID可继续使用原接口，旧接口暂不下线

- 新模板限制：2025年9月23日及之后申请的模板，以及此前未接入过APP签约的存量模板，将不再支持OpenBusinessWebview权限申请

- 新的调用方式：商户需使用WXLaunchMiniProgram Open SDK API调起微信签约


新版APP纯签约API文档：[APP调起签约](https://pay.weixin.qq.com/doc/v2/partner/4016049199.md)



## 步骤1：预签约接口

### 接口说明

适用对象：服务商

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

请求方式： POST

数据格式： XML

签名方式： HMAC-SHA256、MD5

是否需要证书： 否

### 请求参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 应用ID | appid | string\[1,32\] | 是 | 服务商申请的公众号或移动应用appid。<br>示例值：wxcbda96de0b165486 |
| 商户号 | mch\_id | string\[1,32\] | 是 | 商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com<br>示例值：1200009811 |
| 子商户应用ID | sub\_appid | string\[1,32\] | 否 | 子商户号绑定的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定)<br>示例值：wxcbda96de0b165489 |
| 子商户号 | sub\_mch\_id | string\[1,32\] | 是 | 微信支付分配的子商户号<br>示例值：1900000109 |
| 模板id | plan\_id | string\[1,28\] | 是 | 协议模板id，设置路径见[开发步骤](https://pay.weixin.qq.com/doc/v2/partner/4011988361.md)。<br>示例值：12535 |
| 签约协议号 | contract\_code | string\[1,128\] | 是 | 商户侧的签约协议号，由商户生成，只能是数字、大小写字母的描述且在同一个商户号下唯一。<br>示例值：100000 |
| 请求序列号 | request\_serial | int64 | 是 | 商户请求签约时的序列号，要求唯一性。禁止使用0开头，序列号主要用于排序，不作为查询条件，纯数字,范围不能超过int64的范围（9223372036854775807）。<br>示例值：1000 |
| 用户账户展示名称 | contract\_display\_account | string\[1,128\] | 是 | 签约用户的名称，用于用户签约页面的“开通账号”处进行展示，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段<br>示例值：微信代扣 |
| 回调通知url | notify\_url | string\[1,256\] | 是 | 用于接收签约成功消息的回调通知地址，以http或https开头，通知url必须为外网可访问的url，不能携带参数。 |
| 版本号 | version | string\[1,8\] | 是 | 固定值1.0<br>示例值：1.0 |
| 签名类型 | sign\_type | string\[1,32\] | 否 | MD5或者HMAC-SHA256，不填默认MD5<br>注意：app预签约的默认签名方式是(sign\_type为空或无该字段)：MD5<br>示例值：MD5 |
| 签名 | sign | string\[1,64\] | 是 | 详见[签名生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md)<br>示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 时间戳 | timestamp | string\[1,10\] | 是 | 系统当前时间，10位<br>示例值：1414488825 |
| 返回app | return\_app | string\[1,1\] | 否 | 用来控制签约页面结束后的返回路径（不传此参数，则签约完成后停留在微信内）。<br>Y表示返回app, 不填则不返回 注：签约参数appid必须为发起签约的app所有，且在微信开放平台注册过。<br>ios和android用户点完成按钮才返回原APP，直接右划关闭页面或左上角不支持返回APP<br>示例值：Y |

### 请求示例：

XML

```
<xml>
 <appid>wxcbda96de0b165486</appid>
 <mch_id>1200009811</mch_id>
 <sub_appid>wxcbda96de0b165489</sub_appid>
 <sub_mch_id>1900000109</sub_mch_id>
 <plan_id>12535</plan_id>
 <contract_code>100000</contract_code>
 <request_serial>1000</request_serial>
 <contract_display_account>微信代扣</contract_display_account>
 <notify_url>https://weixin.qq.com</notify_url>
 <version>1.0</version>
 <sign_type>MD5</sign_type>
 <sign>C380BEC2BFD727A4B6845133519F3AD6</sign>
 <timestamp>1414488825</timestamp>
 <return_app>Y</return_app>
</xml>
```

### 返回参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 返回状态码 | 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 |
| 错误代码 | err\_code | string\[1,32\] | 否 | 错误码<br>示例值：SIGN\_ERROR |
| 错误代码描述 | err\_code\_des | string\[1,32\] | 否 | 错误码描述<br>示例值：签名错误 |
| 请求appid | appid | string\[1,32\] | 是 | 微信开放平台审核通过的应用APPID（请登录[开放平台](https://open.weixin.qq.com/)查看，注意与公众号的APPID不同）<br>示例值：wxcbda96de0b165486 |
| 商户号 | mch\_id | string\[1,32\] | 是 | 商户号是商户在微信申请微信支付成功后分配的账号ID，[登录平台为http://pay.weixin.qq.com](http://pay.weixin.qq.com)<br>示例值：1200009811 |
| 子商户公众账号ID | sub\_appid | string\[1,32\] | 否 | 子商户号绑定的APP的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定)<br>示例值：wxcbda96de0b165489 |
| 子商户号 | sub\_mch\_id | string\[1,32\] | 是 | 微信支付分配的子商户号<br>示例值：1900000109 |
| 跳转签约小程序的username | miniprogram\_username | string\[1,32\] | 否 | 只有以下两种情况才会返回该参数：<br>1、模板ID为2025年9月23日及之后申请的委托代扣模板<br>2、模板ID为2025年9月23日之前申请的委托代扣模板，但申请了WXLaunchMiniProgram权限<br>若返回该字段，则可使用LaunchMiniProgram SDK进行签约，详情可参考[APP调起签约](https://pay.weixin.qq.com/doc/v2/merchant/4015996790.md)，需要将该字段名和值原样填入；若未返回该字段，说明该模版只能通过OpenBusinessWebview SDK进行签约<br>示例值：gh\_xxxxxxxxxxxxx |
| 跳转签约小程序的path | miniprogram\_path | string\[0,256\] | 否 | 只有以下两种情况才会返回该参数：<br>1、模板ID为2025年9月23日及之后申请的委托代扣模板<br>2、模板ID为2025年9月23日之前申请的委托代扣模板，但申请了WXLaunchMiniProgram权限<br>若返回该字段，则可使用LaunchMiniProgram SDK进行签约，详情可参考[APP调起签约](https://pay.weixin.qq.com/doc/v2/partner/4016049199.md)，需要将该字段名和值原样填入；若未返回该字段，说明该模版只能通过OpenBusinessWebview SDK进行签约<br>示例值：pages/index/index?sign\_scene=app&domain\_type=cn&pre\_entrustweb\_id=xxxxxxxxxx |
| 签名 | sign | string\[1,32\] | 是 | 详见[签名生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md)<br>示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 随机字符串 | nonce\_str | string\[1,64\] | 是 | 随机字符串，不长于32位。推荐随机数生成<br>示例值：5K8264ILTKCH16CQ2502SI8ZNMTM67VS |

以下字段在return\_code 、result\_code都为SUCCESS时有返回

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 预签约id | pre\_entrustweb\_id | string\[1,128\] | 是 | 预签约id，两个小时内有效<br>示例值：5778aadY9nltAsZzXixCkFIGYnV2V |

### 返回示例：

正常示例

```
<xml>
 <return_code><![CDATA[SUCCESS]]></return_code>
 <return_msg><![CDATA[OK]]></return_msg>
 <result_code><![CDATA[SUCCESS]]></result_code>
 <appid><![CDATA[wxcbda96de0b165486]]></appid>
 <mch_id><![CDATA[10000098]]></mch_id>
 <sub_appid><![CDATA[wxcbda96de0b165489]]></sub_appid>
 <sub_mch_id><![CDATA[1900000109]]></sub_mch_id>
 <miniprogram_username><![CDATA[gh_xxxxxxxxxxxxx]]></miniprogram_username>
 <miniprogram_path><![CDATA[pages/index/index?sign_scene=app&domain_type=cn&pre_entrustweb_id=xxxxxxxxxx]]></miniprogram_path>
 <nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
 <sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>
 <pre_entrustweb_id><![CDATA[5778aadY9nltAsZzXixCkFIGYnV2V]]></pre_entrustweb_id>
</xml>
```

### 错误码

| 错误码 | 描述 | 解决方案 |
| --- | --- | --- |
| SYSTEMERROR | 接口返回错误 | 请使用相同参数再次调用API |
| PARAMERROR | 参数错误 | 请根据接口返回的详细信息检查您的程序 |
| SIGNERROR | 签名错误 | 请根据指引生成正确签名 |
| PAYAUTHERROR | 权限校验错误 | 确认商户委托代扣权限权限 |

## 步骤2：签约接口

### 接入流程

一、该接口需要额外申请OpenBusinessWebview权限（仅支持在2025年9月22日之前申请过OpenBusinessView权限的商户在存量模板使用。2025年9月23日起，不再开放申请，且新增模板不可使用OpenBusinessView。请参考[APP调起签约-WXLaunchMiniProgram](https://pay.weixin.qq.com/doc/v2/partner/4016049199.md)文档使用WXLaunchMiniProgram，用户体验更好），请联系对接您的运营同学协助申请，无法联系到运营同学时，可前往微信公众号「[腾讯客服](https://kf.qq.com/)」联系人工客服获取更多帮助，具体参看[接入流程](https://pay.weixin.qq.com/doc/v2/partner/4011988361.md)

     邮件模板如下：

     标题：OpenBusinessWebview权限申请\_APP纯签约

     正文：

      （1）说明使用背景

      （2）appid、mchid（appid和mchid需要有绑定关系）

二、在微信开放平台（open.weixin.qq.com）注册APP信息

三、在开放平台-资源中心下载SDK：[资源下载](https://developers.weixin.qq.com/doc/oplatform/Downloads/iOS_Resource.html)

四、按照下面的接口指引文档完成对接

### 接口说明

适用对象：服务商

请求方式： POST

### 请求参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 预签约id | pre\_entrustweb\_id | string\[1,128\] | 是 | 预签约id<br>示例值：5778aadY9nltAsZzXixCkFIGYnV2V |

注意：

预签约id（pre\_entrustweb\_id）需要从[预签约接口](https://pay.weixin.qq.com/doc/v2/partner/4011988366.md#%E6%AD%A5%E9%AA%A41%EF%BC%9A%E9%A2%84%E7%AD%BE%E7%BA%A6%E6%8E%A5%E5%8F%A3)的返回参数获取，其他参数请严格按照下方接入代码示例传入

### 接入代码示例：

- IOS


```
WXOpenBusinessWebViewReq *req = [[WXOpenBusinessWebViewReq alloc] init];
req.businessType =12; //固定值
NSMutableDictionary *queryInfoDic = [NSMutableDictionary dictionary];
[queryInfoDic setObject:"5778aadY9nltAsZzXixCkFIGYnV2V" forKey:"pre_entrustweb_id"];
req.queryInfoDic = queryInfoDic;
[WxApi sendReq:req];
```

- Android


```
WXOpenBusinessWebview.Req req = new WXOpenBusinessWebview.Req();
req.businessType = 12;//固定值
HashMap  queryInfo = new HashMap<>();
queryInfo.put("pre_entrustweb_id","5778aadY9nltAsZzXixCkFIGYnV2V");
req.queryInfo = queryInfo;
api.sendReq(req);
```

### 返回参数

WXOpenBusinessWebview.Resp，返回参数内容无需关注，如果签约成功，商户系统会收到“[签约结果通知](https://pay.weixin.qq.com/doc/v2/partner/4011988378.md)”