查询签约关系

更新时间：2024.11.14

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

注意：

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

方式一：使用微信返回的委托代扣协议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。示例值：wxcbda96de0b165486
商户号	mch_id	string[1,32]	是	商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com 示例值：1200009811
子商户应用ID	sub_appid	string[1,32]	否	子商户号绑定的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定) 示例值：wxcbda96de0b165489
子商户号	sub_mch_id	string[1,32]	是	微信支付分配的子商户号示例值：1900000109
委托代扣协议id	contract_id	string[1,32]	是	委托代扣签约成功后由微信返回的委托代扣协议id，选择contract_id查询，则此参数必填示例值：100005698
版本号	version	string[1,8]	是	固定值1.0 示例值：1.0
签名	sign	string[1,64]	是	签名规则详见签名生成算法示例值：E1EE61A91C8E90F299DE6AE075D60A2D

请求示例：

XML

1
2<xml>
3  <sign>019C869758CC7F258C42F05CDB9EE361</sign>
4  <mch_id>10000097</mch_id>
5  <sub_mch_id>1900000109</sub_mch_id>
6  <appid>wxf5b5e87a6a0fde94</appid>
7  <contract_id>201509160000028648</contract_id>
8  <version>1.0</version>
9</xml>
10

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

请求参数

参数名	变量	类型[长度限制]	必填	描述
应用ID	appid	string[1,32]	是	服务商申请的公众号或移动应用appid。示例值：wxcbda96de0b165486
商户号	mch_id	string[1,32]	是	商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com 示例值：1200009811
子商户应用ID	sub_appid	string[1,32]	否	子商户号绑定的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定) 示例值：wxcbda96de0b165489
子商户号	sub_mch_id	string[1,32]	是	微信支付分配的子商户号示例值：1900000109
模板id	plan_id	string[1,128]	是	商户在微信商户平台配置的代扣模板id，选择plan_id+contract_code查询，则此参数必填示例值：123
签约协议号	contract_code	string[1,128]	是	商户请求签约时传入的签约协议号，商户侧须唯一。选择plan_id+contract_code查询，则此参数必填示例值：1023658866
版本号	version	string[1,8]	是	固定值1.0 示例值：1.0
签名	sign	string[1,64]	是	签名规则详见签名生成算法示例值：E1EE61A91C8E90F299DE6AE075D60A2D

请求示例：

1
2<xml>
3  <sign>019C869758CC7F258C42F05CDB9EE361</sign>
4  <mch_id>10000097</mch_id>
5  <sub_mch_id>1900000109</sub_mch_id>
6  <appid>wxf5b5e87a6a0fde94</appid>
7  <plan_id>123</plan_id>
8  <contract_code>1023658866</contract_code>
9  <version>1.0</version>
10</xml>
11

返回参数

参数名	变量	类型[长度限制]	必填	描述
返回状态码	return_code	string[1,16]	是	SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断示例值：SUCCESS
返回信息	return_msg	string[1,128]	否	返回信息，如非空，为错误原因如：签名失败等。示例值：签名失败

以下字段在return_code为SUCCESS的时候有返回

参数名	变量	类型[长度限制]	必填	描述
业务结果	result_code	string[1,16]	是	SUCCESS/FAIL 示例值：SUCCESS

以下字段在return_code 和result_code都为SUCCESS的时候有返回

参数名	变量	类型[长度限制]	必填	描述
商户号	mch_id	string[1,32]	是	微信支付分配的商户号示例值：10000098
应用ID	appid	string[1,32]	是	服务商申请的公众号或移动应用appid。示例值：wxcbda96de0b165486
子商户应用ID	sub_appid	string[1,32]	否	子商户号绑定的appid(非必填，如需操作，需要服务商在商户平台为子商户绑定) 示例值：wxcbda96de0b165489
子商户号	sub_mch_id	string[1,32]	是	微信支付分配的子商户号示例值：1900000109
委托代扣协议id	contract_id	string[1,32]	是	签约成功后，微信返回的委托代扣协议id 示例值：Wx15463511252015071056489715
模板id	plan_id	string[1,128]	是	协议模板id 示例值：123
请求序列号	request_serial	int64	是	商户请求签约时的序列号，商户侧须唯一。序列号主要用于排序，不作为查询条件，纯数字,范围不能超过int64的范围（9223372036854775807）。示例值：1695
签约协议号	contract_code	string[1,128]	是	签约协议号示例值：100001256
用户账户展示名称	contract_display_account	string[1,128]	是	签约用户的名称，用于页面展示，参数值不支持UTF8非3字节编码的字符，例如表情符号，所以请勿传微信昵称到该字段示例值：微信代扣
协议状态	contract_state	int	是	协议状态，枚举值： 0：已签约 1：未签约 9：签约进行中示例值：1
协议签署时间	contract_signed_time	string[1,32]	是	协议签署时间示例值：2015-07-01 10:00:00
协议到期时间	contract_expired_time	string[1,32]	是	协议到期时间（目前协议时间为长期有效，可以忽略该字段）示例值：2016-07-01 10:00:00
协议解约时间	contract_terminated_time	string[1,32]	否	当contract_state=1时，该值有效示例值：2015-09-01 10:00:00
协议解约方式	contract_termination_mode	int	否	当contract_state=1时，该值有效 1：有效期过自动解约（预留功能） 2：用户主动解约 3：商户API解约 4：商户平台解约 5：注销（用户微信账户注销） 7：用户联系客服发起的解约示例值：3
签名	sign	string[1,64]	是	详见签名生成算法示例值：C380BEC2BFD727A4B6845133519F3AD6
解约备注	contract_termination_remark	string[1,512]	否	当contract_state=1时，该值有效示例值：解约原因
用户标识	openid	string[1,128]	是	商户appid下的用户唯一标识示例值：ozoKAt9TIPHfwVMkcniiNKZ1vbyw
用户子标识	sub_openid	string[1,128]	否	sub_appid下，用户的唯一标识示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

以下字段在result_code为FAIL的时候有返回

参数名	变量	类型[长度限制]	必填	描述
错误代码	err_code	string[1,32]	是	错误码示例值：SIGN_ERROR
错误代码描述	err_code_des	string[1,32]	是	错误码描述示例值：签名错误

返回示例：

正常示例

1
2<xml>
3	<return_code> <![CDATA[SUCCESS]]> </return_code>
4	<result_code> <![CDATA[SUCCESS]]> </result_code>
5	<mch_id> <![CDATA[80000000]]> </mch_id>
6	<appid> <![CDATA[wx426b3015555b46be]]> </appid>
7	<sub_mch_id> <![CDATA[10010405]]> </sub_mch_id>
8	<contract_id>203</contract_id>
9	<plan_id>66</plan_id>
10	<openid> <![CDATA[oHZx6uMbIG46UXQ3SKxVYEgw1LZs]]> </openid>
11	<request_serial>123</request_serial>
12	<contract_code> <![CDATA[1005]]> </contract_code>
13	<contract_display_account> <![CDATA[test]]> </contract_display_account>
14	<contract_state>1</contract_state>
15	<contract_signed_time>2015-07-01 10:00:00</contract_signed_time>
16	<contract_expired_time>2015-07-01 10:00:00</contract_expired_time>
17	<contract_terminated_time>2015-07-01 10:00:00</contract_terminated_time>
18	<contract_termination_mode>3</contract_termination_mode>
19	<contract_termination_remark> <![CDATA[delete ....]]> </contract_termination_remark>
20	<err_code>0</err_code>
21	<err_code_des> <![CDATA[SUCCESS]]> </err_code_des>
22	<sign> <![CDATA[8FC9DACB7DDF9B48333DCCC2224E0CAC]]> </sign>
23</xml>
24

错误码

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

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服