用户状态查询

更新时间：2024.11.14

应用场景

在停车场、高速、加油等场景下，商户需获取用户车主服务状态/需要关联车主服务。本接口，会查询用户是否开通、授权、有欠费或黑名单用户情况，并将对应的用户状态进行返回。

流程介绍

调用用户状态查询api获取当前用户车主状态，如果当前用户车主状态异常（如有欠费(OVERDUE)，未授权(UNAUTHORIZED)，校验授权关系失败(VEHICLE_AUTH_ERROR)），
接口同步返回跳转路径(path字段)商户侧需根据步骤2引导用户进入车主服务进行相关操作；如果当前用户车主状态正常，不会返回path字段，不需要再引导用户进入车主服务
– 小程序,APP跳转，通过跳转路径(path)调用 ‘用户授权/开通接口api’ 进入车主小程序的对应页面，用户进行授权/开通的操作
– H5跳转，通过跳转路径(path)调用 ‘用户授权/开通接口api’ 进入车主H5对应的页面，用户进行授权/开通操作
返回商户小程序,APP或H5页面后再次调用用户状态查询api确认用户最新车主状态及车牌信息

接口链接

https://api.mch.weixin.qq.com/vehicle/pay/querystate

是否需要证书

不需要

请求参数

字段名	变量名	必填	类型	示例值	描述
公众账号id	appid	是	String（32）	wxcbda96de0b165486	微信支付分配的公众账号id 此appid需为已授权appid
商户号	mch_id	是	String（32）	10000098	微信支付分配的商户号
随机字符串	nonce_str	是	String（32）	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	随机字符串，不长于32位。
签名类型	sign_type	是	String（32）	HMAC-SHA256	签名类型，默认为HMAC-SHA256
签名	sign	是	String（64）	EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5	签名，详见签名生成算法
交易场景	trade_scene	是	String（16）	PARKING	委托代扣的交易场景值，目前支持： PARKING：车场停车场景； PARKING SPACE 车位停车场景； GAS 加油场景； HIGHWAY 高速场景； BRIDGE 路桥场景；该值会向微信用户进行展示
跳转场景	jump_scene	否	String（16）	H5	商户跳转的业务场景，不传默认是小程序，也支持APP和公众号H5跳转 APP:通过APP跳转 H5:通过公众号H5跳转
用户标识	openid	二选一	String（32）	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	用户在商户appid下的唯一标识。openid和车牌号必须选传其中之一
车牌号	plate_number	二选一	String（32）	粤B888888	车牌号。仅包括省份+车牌，不包括特殊字符。openid和车牌号必须选传其中之一
版本号	version	是	String（16）	3.0	版本号，固定值 3.0：车场停车（PARKING）场景 2.0：其他场景

举例如下：

1<xml>
2<mch_id>100000981</mch_id>
3<appid>wxcbda96de0b165486</appid>
4<nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
5<sign_type>HMAC-SHA256</sign_type>
6<trade_scene>PARKING</trade_scene>
7<sign>EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
8<openid> oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</openid>
9<plate_number>粤A00000</plate_number >
10</xml>

返回结果

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

字段名

变量名

必填

类型

示例值

描述

返回状态码

return_code

是

String（16）

SUCCESS

SUCCESS/FAIL

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

返回信息

return_msg

否

String（128）

签名失败

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

签名失败

参数格式校验错误

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

字段名	变量名	必填	类型	示例值	描述
请求appid	appid	是	String（32）	wxcbda96de0b165486	appid是商户在微信申请公众号或移动应用成功后分配的账号ID，登录平台为mp.weixin.qq.com或open.weixin.qq.com
商户号	mch_id	是	String（32）	10000098	商户号是商户在微信申请微信支付成功后分配的账号ID，登录平台为pay.weixin.qq.com
随机字符串	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

是

String（16）

NORMAL

NORMAL：正常用户，已开通车主服务，且已授权访问
PAUSED：已暂停车主服务
OVERDUE: 用户已开通车主服务，但欠费状态。提示用户还款，请跳转到车主服务
UNAUTHORIZED：用户未授权使用当前业务，或未开通车主服务。请跳转到授权接口

用户标识

openid

否

String（32）

wxd930ea5d5a258f4f

用户在商户appid下的唯一标识，当用户入驻车主平台时进行返回

发起扣费方式

deduct_mode

否

String（16）

PROACTIVE

发起扣费的方式
PROACTIVE：表示用户主动发起的免密支付
AUTOPAY：表示用户无感的支付
传入openid作为查询条件时，只会返回PROACTIVE

跳转路径

path

否

String（1024）

pages/route/index

跳转车主小程序的页面路径，如果该参数返回不为空，商户侧需调用‘用户授权/开通接口’引导用户进入车主小程序进行授权/开通的操作,‘用户授权/开通接口’请查看下面的详细说明;

H5跳转同理，需跳转的场景有：
-用户状态正常，但无车牌
-用户欠费
-用户未授权
-用户未开通/暂停车主服务

车牌信息

plate_number _info

否

String（512）

{"plate_number_info":[{"plate_number":"粤B888888","channel_type":"ETC"}]}

车牌号列表。仅包括省份+车牌，不包括特殊字符。
注：在PARKING SPACE场景下无返回。

plate_number _info 值的内容为车牌数

举例如下：

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<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
7<user_status><![CDATA[NORMAL]]></user_status> 
8<result_code><![CDATA[SUCCESS]]></result_code>
9<sign>EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
10<plate_number_list><![CDATA[粤A11110]]></plate_number_list>
11</xml>

错误码

名称	描述	原因	解决方案
SYSTEMERROR	接口返回错误	系统超时	请使用相同参数再次调用API
PARAM_ERROR	参数错误	请求参数未按指引进行填写	请根据接口返回的详细信息检查您的程序
INVALID_REQUEST	非法请求	非法请求	请检查请求参数、商户权限等是否正确
PAYAUTH_ERROR	权限校验错误	商户号产品权限校验错误	请检查商户号代扣产品权限

文档是否有帮助

更多支持

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