用户状态查询

应用场景

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

流程介绍

  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(需要在服务商的商户平台为子商户绑定)


此appid需为已授权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 高速场景;
5. BRIDGE 路桥场景;
该值会向微信用户进行展示

跳转场景

jump_scene

String(16)

H5

商户跳转的业务场景,不传默认是小程序,也支持APP和公众号H5跳转

APP:通过APP跳转

H5:通过公众号H5跳转

用户标识

openid

String(32)

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

用户在商户appid下的唯一标识。openid、sub_openid和车牌号必须选传其中之一,如果选择传sub_openid,则必须传sub_appid

用户子标识

sub_openid

String(32)

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

用户在子商户appid下的唯一标识。openid、sub_openid和车牌号必须选传其中之一,如果选择传sub_openid,则必须传sub_appid

车牌号

plate_number

String(32)

粤B888888

车牌号。仅包括省份+车牌,不包括特殊字符。openid、sub_openid和车牌号必须选传其中之一,如果选择传sub_openid,则必须传sub_appid

版本号

version

String(16)

2.0

固定值2.0
2.0接口返回车牌信息plate_number _info字段,不再返回plate_number_list

举例如下:

<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下的唯一标识,当用户入驻车主平台时进行返回

用户子标识 sub_openid String(32) oUpF8uMuAJO_M2pxb1Q9zNjWeS6o sub_appid下,用户的唯一标识

跳转路径

path

String(1024)

pages/route/index

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

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

车牌号

plate_number_list

String(128)

粤B888888

车牌号列表。仅包括省份+车牌,不包括特殊字符。多个车牌时,以分好间隔。
注:在PARKING SPACE场景下无返回

-车牌信息

plate_number _info

String(512)

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

接口版本请求参数version为2.0 版本时进行返回。此时,不再返回plate_number_list字段。
车牌号列表。仅包括省份+车牌,不包括特殊字符。
注:在PARKING SPACE场景下无返回。

plate_number _info 值的内容为车牌数组

举例如下:

<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

非法请求

非法请求

请检查请求参数、商户权限等是否正确

PAYAUTH_ERROR

权限校验错误

商户号产品权限校验错误

请检查商户号代扣产品权限

用户授权/开通接口api

应用场景

在停车场、高速、加油等场景下,商户需在用户授权后,使用车主服务进行扣费。当用户未授权、未开通时,商户可引导用户到此接口进行授权或开通车主服务。

目前车主服务只支持蓝牌,绿牌和黑牌,商户侧引导用户添加车牌时需明确告知用户黄牌车牌号请不要添加到车主平台

1.小程序跳转接口调用请求说明

接口

wx.navigateToMiniProgram(OBJECT)接口

说明

iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持

OBJECT参数说明:

字段含义 变量名 必填 类型 示例值 描述

微信车主小程序appid

appId

String

wxbcad394b3d99dac9

固定值
wxbcad394b3d99dac9

+场景信息传递给小程序的数据

extraData

object

{ "appid": "wx426a3015555a46be", "sub_appid": "wx426a3015555a46b1", "mch_id": "10000098", "sub_mch_id": "10000096", "nonce_str": "FF1A406564EE70106445", "sign_type": "HMAC-SHA256", "sign":"EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5", "trade_scene": "PARKING", "openid": "oUpF8uMEb4qRXf22hE3X68TekukE" }

签约的请求参数,详情见extraData字段详细说明

打开小程序的页面路径

path

string

pages/route/index

打开小程序的页面路径,取值为‘用户状态查询接口’返回的跳转路径(path字段,如查询接口没返回该字段,说明不需要再调用’用户授权/开通接口‘)

接口调用成功的回调函数

success

Function

 

 

接口调用失败的回调函数

fail

Function

 

 

接口调用结束的回调函数

complete

Function

 

调用成功、失败都会执行


示例:
wx.navigateToMiniProgram({
    appId: 'wxbcad394b3d99dac9',
    path: 'pages/route/index',
    extraData: {
        appid: 'wx426a3015555a46be',
        sub_appid: 'wx426a3015555a46b1',
        mch_id: '10000098',
        sub_mch_id: '10000096',
        nonce_str: 'FF1A406564EE70106445',
        sign_type: 'HMAC-SHA256',
        sign:'EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5',
        trade_scene: 'PARKING',
        openid: 'oUpF8uMEb4qRXf22hE3X68TekukE'
       },
    success(res) {
    },
    fail(res) {
              // 未成功跳转到车主小程序
    }
})

用户授权完成之后,会跳转回商户小程序。可通过onShow(OBJECT)所携带的参数判断返回结果,OBJECT返回参数请查看小程序开发文档onShow参数说明

示例:

App({
    onShow(res) {
        if (res.scene === 1038) { // 场景值1038:从被打开的小程序返回
            const { appId, extraData } = res.referrerInfo
            if (appId == 'wxbcad394b3d99dac9') { // appId为wxbcad394b3d99dac9:从车主小程序跳转回来
                    // TODO
                    // 需要发起‘用户状态查询接口’确认授权/开通结果
            }
        }
    }
})


2.H5跳转接口调用请求说明 (注意:参数之后需要拼接#wechat_redirect)

在用户状态查询接口返回的path参数通过GET请求的方式拼接以下参数:

字段含义 变量名 必填 类型 示例值 描述

公众账号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 高速场景;
5. BRIDGE 路桥场景;
该值会向微信用户进行展示

用户标识

openid

String(32)

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

此参数必传,用户在商户appid下的唯一标识。openid和sub_openid可以选传其中之一,如果选择传sub_openid,则必须传sub_appid

用户子标识

sub_openid

String(32)

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

此参数必传,用户在子商户appid下的唯一标识。openid和sub_openid可以选传其中之一,如果选择传sub_openid,则必须传sub_appid

车牌号

plate_number

String(32)

粤B888888

车牌号。仅包括省份+车牌,不包括特殊字符。当场景值为 HIGHWAY 时,plate_number必传

物料信息

material_info

String(64)

12365577|0_1_0_4

用户通过扫码进入商户小程序时所扫的物料码信息

当场景值为 HIGHWAY 高速场景时需传递下面参数

通道类型

channel_type

String(32)

ETC

高速通道类型,目前可选:ETC、MTC。用户车牌必须具有通道标识时,才允许扣费。


举例如下: (注意:生成跳转链接的时候,对所有参数urlconde再生成跳转链接)

path?appid=wxcbda96de0b165486&sub_appid=wxcbda96de0b165481&mch_id=10000098&sub_mch_id=10000096&openid=oUpF8uMEb4qRXf22hE3X68TekukE&plate_number=%E7%B2%A4B888888&sign=EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5&sign_type=HMAC-SHA256&nonce_str=5K8264ILTKCH16CQ2502SI8ZNMTM67VS&trade_scene=PARKING#wechat_redirect


用户授权完成之后,会跳转回商户H5页面。



3.APP跳转接口调用请求说明

字段含义 变量名 必填 类型 示例值 描述

公众账号id

appid

String(32)

wxcbda96de0b165486

微信支付分配的公众账号id

商户号

mch_id

String(32)

10000098

微信支付分配的商户号

子商户公众账号id sub_appid String(32) wxcbda96de0b165489 子商户号绑定的服务号,小程序,APP的appid(需要在服务商的商户平台为子商户绑定)
子商户号 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 高速场景;
5. BRIDGE 路桥场景;
该值会向微信用户进行展示

用户标识

openid

String(32)

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

此参数必传,用户在商户appid下的唯一标识。openid和sub_openid可以选传其中之一,如果选择传sub_openid,则必须传sub_appid

用户子标识

sub_openid

String(32)

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

此参数必传,用户在子商户appid下的唯一标识。openid和sub_openid可以选传其中之一,如果选择传sub_openid,则必须传sub_appid

车牌号

plate_number

String(32)

粤B888888

车牌号。仅包括省份+车牌,不包括特殊字符。当场景值为 HIGHWAY 时,plate_number必传

物料信息

material_info

String(64)

12365577|0_1_0_4

用户通过扫码进入商户小程序时所扫的物料码信息

当场景值为 HIGHWAY 高速场景时需传递下面参数

通道类型

channel_type

String(32)

ETC

高速通道类型,目前可选:ETC、MTC。用户车牌必须具有通道标识时,才允许扣费。


安卓举例如下(APP调起小程序详细说明):

String appId = "wxcdbdf056ad5fc1fb"; // 填应用AppId
IWXAPI api = WXAPIFactory.createWXAPI(context, appId);
WXLaunchMiniProgram.Req req = new WXLaunchMiniProgram.Req();
req.userName = "gh_518c42c65952"; // 填车主小程序原始id,取固定值gh_518c42c65952
req.path = "/pages/route/index?extraData={\"appid\":\" wxcbda96de0b165486\",\"mch_id\":\"10000098\",\"sub_appid\":\" wxcbda96de0b165486 \",\"sub_mch_id\":\"10000096\",\"nonce_str\":\"5K8264ILTKCH16CQ2502SI8ZNMTM67VS \",\"sign_type\":\"HMAC-SHA256\",\"trade_scene\":\"HIGHWAY\",\"sub_openid\":\" oUpF8uMEb4qRXf22hE3X68TekukE \",\"plate_number\":\"粤Z88888A \",\"sign\":\"C99D665499D169E97D6278868C06FB91E5DD87BCDA758FA4869669F12C27FEFC\"}";//拉起小程序页面的可带参路径,不填默认拉起小程序首页
req.miniprogramType = WXLaunchMiniProgram.Req.MINIPTOGRAM_TYPE_RELEASE;
api.sendReq(req);


用户开通/授权完成之后,会跳转回到商户的APP,暂时不返回参数。商户侧APP接收到客户端回调后再次调用用户状态查询接口获取用户的最新车主状态