用户状态查询

应用场景

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

流程介绍

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

接口链接

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

是否需要证书

不需要

请求参数

字段名 变量名 必填 类型 示例值 描述
公众账号id appid String(32) wxcbda96de0b165486 服务商商户号绑定的APPID
子商户公众账号id sub_appid String(32) wxcbda96de0b165489 子商户号绑定的服务号,小程序,APP的appid(需要在服务商的商户平台为子商户绑定)
商户号 mch_id String(32) 10000098 服务商商户号
子商户号 sub_mch_id String(32) 1900000109 子商户号
随机字符串 nonce_str String(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS 随机字符串,不长于32位。
签名类型 sign_type String(32) HMAC-SHA256 签名类型,默认为HMAC-SHA256
签名 sign String(64) EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5 签名,详见签名生成算法
交易场景 trade_scene String(16) PARKING 委托代扣的交易场景值,目前支持 :
1. PARKING:车场停车场景 ;
2. PARKING SPACE 车位停车场景;
3. GAS 加油场景;
4. HIGHWAY 高速场景;
该值会向微信用户进行展示
跳转场景 jump_scene String(16) H5 商户跳转的业务场景,不传默认是小程序,也支持APP和公众号H5跳转

APP:通过APP跳转

H5:通过公众号H5跳转

用户标识 openid 三选一 String(32) oUpF8uMuAJO_M2pxb1Q9zNjWeS6o 用户在商户appid下的唯一标识。
用户子标识 sub_openid String(32) oUpF8uMuAJO_M2pxb1Q9zNjWeS6o 用户在子商户appid下的唯一标识。
车牌号 plate_number String(32) 粤B888888 车牌号。仅包括省份+车牌,不包括特殊字符。
版本号 version String(16) 3.0 版本号,固定值
3.0:车场停车(PARKING)场景
2.0:其他场景

举例如下:

<xml>
<mch_id>100000981</mch_id>
<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
<appid>wxcbda96de0b165486</appid>
<nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
<sign_type>HMAC-SHA256</sign_type>
<trade_scene>PARKING</trade_scene>
<sign>EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
<openid> oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</ openid>
<plate_number>粤A00000</plate_number >
</xml>

返回结果

字段名 变量名 必填 类型 示例值 描述
返回状态码 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 String(16) NORMAL NORMAL:正常用户,已开通车主服务,且已授权访问

PAUSED:已暂停车主服务

OVERDUE: 用户已开通车主服务,但欠费状态。提示用户还款,请跳转到车主服务

UNAUTHORIZED:用户未授权使用当前业务,或未开通车主服务。请跳转到授权接口
用户标识 openid String(32) oUpF8uMuAJO_M2pxb1Q9zNjWeS69 用户在商户appid下的唯一标识,当用户入驻车主平台时进行返回
发起扣费方式 deduct_mode String(16) PROACTIVE 发起扣费的方式 
PROACTIVE:表示用户主动发起的免密支付 
AUTOPAY:表示用户无感的支付
传入openid作为查询条件时,只会返回PROACTIVE
用户子标识 sub_openid String(32) oUpF8uMuAJO_M2pxb1Q9zNjWeS6o sub_appid下,用户的唯一标识
跳转路径 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 值的内容为车牌数组
--车牌号 plate_number String(32) 粤B888888 车牌号。仅包括省份+车牌,不包括特殊字符。
--车牌通道标识 channel_type String(32) ETC 车牌通道信息标识,仅在HIGHWAY高速场景下进行返回。可选:MTC,ETC,ETC;MTC。同时具有2个标识时,以分号间隔标识
--常用车牌标志 common_use_flag

String(16)

COMMON_USE

在3.0接口时,如果该车牌是免密支付方式且是常用车牌则会返回该字段,商户可以根据该字段引导用户进行免密支付升级到无感支付 
引导用户升级无感支付的路径是:pages/no-sense-payment/index,具体请求参数和方式见免密升级无感api

举例如下:

<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid>wx2421b1c4370ec43b</appid>
<mch_id>10000100</mch_id>
<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
<user_status><![CDATA[NORMAL]]></user_status> 
<result_code><![CDATA[SUCCESS]]></result_code>
<sign>EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5</sign>
<plate_number_list><![CDATA[粤A11110]]></plate_number_list>
</xml>

错误码

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