用户状态查询api

更新时间：2024.12.30

应用场景

用于查询用户是否有欠费或黑名单用户情况，确定能否符合微信侧开通乘车卡免密支付要求。如已经开通乘车卡，则需传签约号，可确定是否符合继续使用乘车卡的要求。

接口链接

https://api.mch.weixin.qq.com/transit/partnerpay/querystate

是否需要证书

不需要

请求参数

字段名	变量名	必填	示例值	类型	描述
公众账号id	appid	是	wxcbda96de0b165486	String(32)	服务商商户号绑定的APPID
子商户公众账号id	sub_appid	否	wxcbda96de0b165489	String(32)	子商户号绑定的服务号，小程序，APP的appid(需要在服务商的商户平台为子商户绑定)
商户号	mch_id	是	10000098	String(32)	服务商商户号
子商户号	sub_mch_id	是	1900000109	String(32)	子商户号
随机字符串	nonce_str	是	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	String(32)	随机字符串，不长于32位。
委托代扣协议id	contract_id	是	Wx15463511252015071056489715	String(32)	签约成功后，微信返回的委托代扣协议id 查用户是否能继续使用乘车卡时必传，此时，才会返回签约信息，如contract_state
签名类型	sign_type	是	HMAC-SHA256	String(32)	签名类型，默认为HMAC-SHA256
签名	sign	是	EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5	String(64)	签名，详见签名生成算法
微信open ID	openid	是	oYobu0Dmn6TdodZnFWKOEkqoRbI8	String(32)	用户微信open ID

举例如下：

1<xml>
2<mch_id>10000098</mch_id>
3<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
4<appid>wxcbda96de0b165486</appid>
5<nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
6<contract_id>Wx15463511252015071056489715</contract_id>
7<sign_type>HMAC-SHA256</sign_type>
8<sign> EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
9< openid > oYobu0Dmn6TdodZnFWKOEkqoRbI8</ openid >
10</xml>

返回结果

字段名	变量名	必填	类型	示例值	描述
返回状态码	return_code	是	String(16)	SUCCESS	SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看trade_state来判断
返回信息	return_msg	否	String(128)	签名失败	返回信息，如非空，为错误原因签名失败参数格式校验错误

字段名

变量名

必填

类型

示例值

描述

返回状态码

return_code

是

String(16)

SUCCESS

SUCCESS/FAIL

此字段是通信标识，非交易标识，交易是否成功需要查看trade_state来判断

返回信息

return_msg

否

String(128)

签名失败

返回信息，如非空，为错误原因

签名失败

参数格式校验错误

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

字段名	变量名	必填	类型	示例值	描述
请求appid	appid	是	String(32)	wxcbda96de0b165486	appid是商户在微信申请公众号或移动应用成功后分配的账号ID，登录平台为mp.weixin.qq.com或open.weixin.qq.com
子商户公众账号id	sub_appid	否	String(32)	wxcbda96de0b165489	微信分配的子商户公众账号ID
商户号	mch_id	是	String(32)	10000098	商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com
子商户号	sub_mch_id	是	String(32)	1900000109	微信支付分配的子商户号
随机字符串	nonce_str	是	String(32)	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	随机字符串，不长于32位。推荐随机数生成算法
签名	sign	是	String(64)	EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5	签名，详见签名生成算法
业务结果	result_code	是	String(16)	SUCCESS	SUCCESS/FAIL
错误代码	err_code	否	String(32)	SYSTEMERROR	错误码
错误代码描述	err_code_des	否	String(128)	系统错误	结果信息描述

以下字段在return_code 、result_code都为SUCCESS时有返回

字段名	变量名	必填	示例值	类型	描述
用户状态	user_state	是	NORMAL	String(16)	NORMAL：允许开通 /乘车/进站 BLOCKED: 不允许开通/乘车/进站 OVERDUE: 用户欠费状态，提示用户到微信还款，不允许开通代扣用户状态为对应当前查询的子商户号的状态，不代表所有子商户号的状态
委托代扣协议id	contract_id	否	Wx15463511252015071056489715	String(32)	请求时传的签约号，即微信返回的委托代扣协议id 查用户是否能继续使用乘车卡时必传，此时，才会返回签约信息，如contract_state
签约模板id	plan_id	否	123	int	商户在微信商户平台设置的代扣协议模板id
签约协议号	contract_code	否	1023658866	String(32)	商户请求签约时传入的签约协议号，商户侧须唯一
协议状态	contract_state	否	1	int	0-签约中 1-解约

举例如下：

1<xml>
2<return_code><![CDATA[SUCCESS]]></return_code>
3<return_msg><![CDATA[OK]]></return_msg>
4<appid>wx2421b1c4370ec43b</appid>
5<mch_id>10000100</mch_id>
6<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
7<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
8<user_state><![CDATA[NORMAL]]></user_state>
9<contract_id>Wx15463511252015071056489715</contract_id>
10<plan_id>123</plan_id > 
11<contract_code >1023658866</ contract_code > 
12<contract_state >1</ contract_state>
13<result_code><![CDATA[SUCCESS]]></result_code>
14<sign>EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
15</xml>

错误码

名称	描述	原因	解决方案
SYSTEMERROR	接口返回错误	系统超时	请使用相同参数再次调用API
CONTRACT_NOT_EXIST	签约协议不存在	签约协议号不存在	请检查签约协议号是否正确
PARAM_ERROR	参数错误	请求参数未按指引进行填写	请根据接口返回的详细信息检查您的程序
INVALID_REQUEST	非法请求	非法请求	请检查请求参数、商户权限等是否正确
FORMAT_ERROR	XML格式错误	XML格式错误	请检查XML参数格式是否正确
PAYAUTH_ERROR	权限校验错误	商户号产品权限校验错误	权限校验错误服务商或子商户号权限校验错误请检查如下三个权限： 1.服务商商户号受理权限 2.子商户号代扣产品权限 3.子商户号授予父商户号代扣权限

文档是否有帮助

更多支持

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