---
url: "https://pay.weixin.qq.com/doc/v2/partner/4011988379.md"
title: "查询签约关系"
doc_id: 4011988379
---

>更新时间：2025.08.15

查询签约关系接口提供单笔签约关系查询。

注意：

- 查询签约关系可通过下面两种方式查询：


    方式一：使用微信返回的委托代扣协议contract\_id进行查询。

    方式二：plan\_id+contract\_code模式：传入模板id和签约协议号进行查询。

两种查询方式返回结果相同



## 接口说明

适用对象：服务商

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

请求方式： POST

数据格式： XML

是否需要证书： 否

请求频率限制：默认300qps

## 方式1：使用委托代扣协议查询

### 请求参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 应用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 | contract\_id | string\[1,32\] | 是 | 委托代扣签约成功后由微信返回的委托代扣协议id，选择contract\_id查询，则此参数必填<br>示例值：100005698 |
| 版本号 | version | string\[1,8\] | 是 | 固定值1.0<br>示例值：1.0 |
| 签名 | sign | string\[1,64\] | 是 | 签名规则[详见签名生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md)<br>示例值：E1EE61A91C8E90F299DE6AE075D60A2D |

### 请求示例：

XML

```

<xml>
  <sign>019C869758CC7F258C42F05CDB9EE361</sign>
  <mch_id>10000097</mch_id>
  <sub_mch_id>1900000109</sub_mch_id>
  <appid>wxf5b5e87a6a0fde94</appid>
  <contract_id>201509160000028648</contract_id>
  <version>1.0</version>
</xml>

```

## 方式2：使用模板id和签约协议号查询

### 请求参数

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 应用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,128\] | 是 | 商户在微信商户平台配置的代扣模板id，选择plan\_id+contract\_code查询，则此参数必填<br>示例值：123 |
| 签约协议号 | contract\_code | string\[1,128\] | 是 | 商户请求签约时传入的签约协议号，商户侧须唯一。选择plan\_id+contract\_code查询，则此参数必填<br>示例值：1023658866 |
| 版本号 | version | string\[1,8\] | 是 | 固定值1.0<br>示例值：1.0 |
| 签名 | sign | string\[1,64\] | 是 | 签名规则[详见签名生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md)<br>示例值：E1EE61A91C8E90F299DE6AE075D60A2D |

### 请求示例：

- XML


```

<xml>
  <sign>019C869758CC7F258C42F05CDB9EE361</sign>
  <mch_id>10000097</mch_id>
  <sub_mch_id>1900000109</sub_mch_id>
  <appid>wxf5b5e87a6a0fde94</appid>
  <plan_id>123</plan_id>
  <contract_code>1023658866</contract_code>
  <version>1.0</version>
</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 |

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

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 商户号 | mch\_id | string\[1,32\] | 是 | 微信支付分配的商户号<br>示例值：10000098 |
| 应用ID | appid | string\[1,32\] | 是 | 服务商申请的公众号或移动应用appid。<br>示例值：wxcbda96de0b165486 |
| 子商户应用ID | sub\_appid | string\[1,32\] | 否 | 子商户号绑定的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定)<br>示例值：wxcbda96de0b165489 |
| 子商户号 | sub\_mch\_id | string\[1,32\] | 是 | 微信支付分配的子商户号<br>示例值：1900000109 |
| 委托代扣协议id | contract\_id | string\[1,32\] | 是 | 签约成功后，微信返回的委托代扣协议id<br>示例值：Wx15463511252015071056489715 |
| 模板id | plan\_id | string\[1,128\] | 是 | 协议模板id<br>示例值：123 |
| 请求序列号 | request\_serial | int64 | 是 | 商户请求签约时的序列号，商户侧须唯一。序列号主要用于排序，不作为查询条件，纯数字,范围不能超过int64的范围（9223372036854775807）。<br>示例值：1695 |
| 签约协议号 | contract\_code | string\[1,128\] | 是 | 签约协议号<br>示例值：100001256 |
| 用户账户展示名称 | contract\_display\_account | string\[1,128\] | 是 | 签约用户的名称，用于页面展示，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段<br>示例值：微信代扣 |
| 协议状态 | contract\_state | int | 是 | 协议状态，枚举值：<br>0：已签约<br>1：未签约<br>9：签约进行中<br>示例值：1 |
| 协议签署时间 | contract\_signed\_time | string\[1,32\] | 是 | 协议签署时间<br>示例值：2015-07-01 10:00:00 |
| 协议到期时间 | contract\_expired\_time | string\[1,32\] | 是 | 协议到期时间<br>（目前协议时间为长期有效，可以忽略该字段）<br>示例值：2016-07-01 10:00:00 |
| 协议解约时间 | contract\_terminated\_time | string\[1,32\] | 否 | 当contract\_state=1时，该值有效<br>示例值：2015-09-01 10:00:00 |
| 协议解约方式 | contract\_termination\_mode | int | 否 | 当contract\_state=1时，该值有效<br>1：有效期过自动解约（预留功能）<br>2：用户主动解约<br>3：商户API解约<br>4：商户平台解约<br>5：注销（用户微信账户注销）<br>7：用户联系客服发起的解约<br>示例值：3 |
| 签名 | sign | string\[1,64\] | 是 | [详见签名生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md)<br>示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 解约备注 | contract\_termination\_remark | string\[1,512\] | 否 | 当contract\_state=1时，该值有效<br>示例值：解约原因 |
| 用户标识 | openid | string\[1,128\] | 是 | 商户appid下的用户唯一标识<br>示例值：ozoKAt9TIPHfwVMkcniiNKZ1vbyw |
| 用户子标识 | sub\_openid | string\[1,128\] | 否 | sub\_appid下，用户的唯一标识<br>示例值：oUpF8uMuAJO\_M2pxb1Q9zNjWeS6o |

以下字段在result\_code为FAIL的时候有返回

| 参数名 | 变量 | 类型\[长度限制\] | 必填 | 描述 |
| --- | --- | --- | --- | --- |
| 错误代码 | err\_code | string\[1,32\] | 是 | 错误码<br>示例值：SIGN\_ERROR |
| 错误代码描述 | err\_code\_des | string\[1,32\] | 是 | 错误码描述<br>示例值：签名错误 |

## 返回示例：

正常示例

```

<xml>
	<return_code> <![CDATA[SUCCESS]]> </return_code>
	<result_code> <![CDATA[SUCCESS]]> </result_code>
	<mch_id> <![CDATA[80000000]]> </mch_id>
	<appid> <![CDATA[wx426b3015555b46be]]> </appid>
	<sub_mch_id> <![CDATA[10010405]]> </sub_mch_id>
	<contract_id>203</contract_id>
	<plan_id>66</plan_id>
	<openid> <![CDATA[oHZx6uMbIG46UXQ3SKxVYEgw1LZs]]> </openid>
	<request_serial>123</request_serial>
	<contract_code> <![CDATA[1005]]> </contract_code>
	<contract_display_account> <![CDATA[test]]> </contract_display_account>
	<contract_state>1</contract_state>
	<contract_signed_time>2015-07-01 10:00:00</contract_signed_time>
	<contract_expired_time>2015-07-01 10:00:00</contract_expired_time>
	<contract_terminated_time>2015-07-01 10:00:00</contract_terminated_time>
	<contract_termination_mode>3</contract_termination_mode>
	<contract_termination_remark> <![CDATA[delete ....]]> </contract_termination_remark>
	<err_code>0</err_code>
	<err_code_des> <![CDATA[SUCCESS]]> </err_code_des>
	<sign> <![CDATA[8FC9DACB7DDF9B48333DCCC2224E0CAC]]> </sign>
</xml>

```

## 错误码

| 错误码 | 描述 | 解决方案 |
| --- | --- | --- |
| SIGN\_ERROR | 签名错误 | 验证签名算法 |
| PARAMETER FAIL | 参数错误 | 验证参数 |
| XML FAIL | XML格式错误 | 检查XML格式 |
| RESULT NULL | 查询为空 | 传入正确查询参数 |
| -48 | MERCHANT PERMISSION ERROR | 确认商户权限(包含appid和mchid绑定关系) |
| -25 | 查询签约关系不存在 | 确认签约关系 |