微信非税车主平台接入文档
1 流程介绍
1.1 业务流程时序图
2 微信非税平台提供的接口(车主服务后台)
2.1 用户状态查询
2.2 用户入场通知
2.3 申请扣款
2.4 返回码说明
3 用户授权/开通
3.1 小程序跳转接口调用请求说明
3.2 H5跳转接口调用请求说明
3.3 APP跳转接口调用请求说明
4 委办局提供的接口
4.1 车牌状态变更通知
4.2 支付结果通知
# 1 流程介绍
# 1.1 业务流程时序图
注:
步骤3:调用入场通知接口(针对先出场后扣费场景使用,如果是先扣款后出场的场景不需要调用该接口,如想获取入场车主的状态,可通过用户状态查询接口获取 ),该接口用于商户注册接收场内用户状态变化,该接口同时返回用户状态。
步骤7:代扣申请仅返回受理结果,不代表最终扣款状态。如受理返回系统异常或网络超时,则用原请求参数重试即可,一个商户订单号对应一笔支付单。
步骤10:受理成功的订单,由于用户零钱和银行卡没钱会导致最终扣款失败,这里商户侧可联系微信的运营同学去申请微信的垫资能力(针对用户零钱和银行卡没钱这种情况,微信侧先行垫资并催缴用户还款)
# 2 微信非税平台提供的接口(车主服务后台)
# 2.1 用户状态查询
应用场景
在停车场、高速、加油等场景下,商户需获取用户车主服务状态/需要关联车主服务。本接口,会查询用户是否开通、授权、有欠费或黑名单用户情况,并将对应的用户状态进行返回。
流程介绍
- 调用用户状态查询api获取当前用户车主状态,如果当前用户车主状态异常(如有欠费(OVERDUE),未授权(UNAUTHORIZED)),接口同步返回跳转路径(path字段),商户侧需根据步骤2引导用户进入车主服务进行相关操作;如果当前用户车主状态正常,不会返回path字段,不需要再引导用户进入车主服务
- --小程序,APP跳转,通过跳转路径(path)调用 ‘用户授权/开通接口api’进入车主小程序的对应页面,用户进行授权/开通的操作
--H5跳转,通过跳转路径(path)调用 ‘用户授权/开通接口api’进入车主H5对应的页面,用户进行授权/开通操作
- 返回商户小程序,APP或H5页面后再次调用用户状态查询api确认用户最新车主状态及车牌信息
https://api.weixin.qq.com/nontax/vehicle/querystate?access_token=$AccessToken
请求参数
返回结果
示例
{
"appid": "wx5f6e43071809a9dd",
"bank_id": "test_bank_id",
"bank_account": "",
"mch_id": "1900016021",
"region_code" : "440000",
"trade_scene": "PARKING",
"jump_scene": "H5",
"openid": "ont-9vjAcIdSU-LgB7ubALAVJO9U",
"plate_number": "粤B888888",
"material_info": "test_material_info",
"channel_type": "ETC"
}
返回结果
{
"errcode": 0,
"errmsg": "ok",
"user_state": "NORMAL",
"openid": "ont-9vjAcIdSU-LgB7ubALAVJO9U",
"path":
"https:\/\/payapp.weixin.qq.com\/vehicle\/plat\/indextemplate",
"plate_number_info": [
],
"authorize_package": {
"mch_id": "1800004561",
"sub_mch_id": "1900016021",
"appid": "wxc971985892358997",
"sub_appid":
"wx6cc9648de104270d",
"nonce_str": "SwwVkZWoXlIWX7AG2c3ItkklTo138PEO",
"sign_type": "HMAC-SHA256",
"sign":
"67D1B1232C9837E5885216DA349632AD9CE080BBD2D54DF13314260F4CD5D9C8",
"trade_scene": "PARKING",
"openid": "ooaLEwgrB9PRsx-IdsJxEQiKgjbQ",
"sub_openid": "oFkLxtyJswfbex9crZWHGDYG5NIw",
"plate_number": "粤B888888",
"material_info": "test_material_info",
"channel_type": "ETC"
}
}
## 2.2 用户入场通知
**应用场景**
在停车场场景下,如用户已加入车主平台,则进行入场通知;如用户已经欠费,会发送用户欠费入场通知。本接口,会查询用户是否有欠费或黑名单用户情况,并将对应的用户状态进行返回。
说明
本接口主要用于先出场后扣费场景下,微信侧实时同步用户车主状态给商户侧,用于维护车主用户白名单。如商户侧是先扣费后出场场景,不需要调用该接口,用户入场时可通过用户状态查询接口获取当前用户的车主状态即可
https://api.weixin.qq.com/nontax/vehicle/entrancenotify?access_token=$AccessToken
请求参数
其中scene_info内部字段如下:
当trade_scene场景为:PARKING(车场停车)时,传如下值
返回结果
示例
请求参数
{
"appid": "wx5f6e43071809a9dd",
"bank_id": "test_bank_id",
"mch_id": "1900016021",
"region_code" : "440000",
"notify_url": "https://weixin.qq.com",
"trade_scene": "PARKING",
"start_time": 1542351485,
"car_type": "小型车",
"parking_name": "test_parking_name",
"free_time": 1200,
"plate_number": "粤B888888",
"openid": "ont-9vjAcIdSU-LgB7ubALAVJO9U"
}
返回结果
{
"errcode": 0,
"errmsg": "ok",
"user_state": "NORMAL"
}
## 2.3 申请扣款
**应用场景**
委托代扣可应用于定期扣款或需事后扣款以期提高效率的场景。例如高速,停车场等通过用户授权给商户,进行委托扣款的场景。
注:扣费请求首先按签约协议中记录的优先支付方式扣费,否则从可用扣款方式中依次选择扣款。
说明
由于目前车主服务只支持蓝牌,绿牌和黑牌。停车场和高速场景下,商户侧必须在车辆出场时识别车牌类型,非蓝牌,绿牌和黑牌的车辆不能进行车主服务的扣款
https://api.weixin.qq.com/nontax/vehicle/payapply?access_token=$AccessToken
请求参数
高速场景 BRIDGE 路桥场景该值催缴时会向微信用户进行展示 |scene_info|string|是|场景信息值,格式为json,不同业务场景设置不同的值,具体如后面所列。| |order_id|string|否|订单号,若填了此字段,除appid外其它参数都不用填|
其中scene_info内部字段如下:
当trade_scene场景为:PARKING(车场停车)时,传如下值
当trade_scene场景为:PARKING SPACE 时(车位停车),传如下值
当trade_scene场景为:HIGHWAY 时,传如下值
当trade_scene场景为:BRIDGE 时,传如下值
返回结果
示例
请求参数
{
"appid" : "wx5f6e43071809a9dd",
"bank_id" : "test_bank_id",
"bank_account" : "",
"mch_id" : "1900016021",
"payment_notice_no" : "1111111111",
"department_code" : "222222",
"payment_notice_type" : 1,
"region_code" : "440000",
"department_name" : "测试执收单位名称",
"desc" : "测试desc",
"fee" : 1,
"goods_tag" : "",
"trade_scene" : "PARKING SPACE",
"scene_info" :
{
"start_time": 1542351485,
"charging_time": 3600,
"car_type": "小型车",
"parking_name": "test_parking_name",
"openid": "ont-9vjAcIdSU-LgB7ubALAVJO9U",
"space_number": "D666666"
}
}
返回结果
{
"errcode": 0,
"errmsg": "ok",
"order_id": "AQAAhNw2srPiUjMKDJ7fvb4AAAAA"
}
## 2.4 返回码说明
# 3 用户授权/开通
# 3.1 小程序跳转接口调用请求说明
|接口|wx.navigateToMiniProgram(OBJECT)接口|
使用用户状态查询接口返回的path和authorize_package参数填充path和extraData参数
示例:
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参数说明
当用户放弃操作时,referrerInfo或referrerInfo. extraData为null(或undefined),当车主平台小程序成功或失败返回商户小程序时,referrerInfo.extraData字段说明如下
用户授权结果:
true:已授权
false:授权失败
示例:
App({
onShow(res) {
if (res.scene === 1038) { // 场景值1038:从被打开的小程序返回
const { appId, extraData } = res.referrerInfo
if (appId == 'wxbcad394b3d99dac9') { // appId为wxbcad394b3d99dac9:从车主小程序跳转回来
if (typeof extraData == 'undefined'){
// TODO
// 客户端小程序不确定授权结果,需要发起‘用户状态查询接口’确认授权结果
return;
}
if(extraData.auth == 'true'){
// TODO
// 客户端小程序授权成功
return;
} else {
// TODO
// 授权失败
return;
}
}
}
}
})
## 3.2 H5跳转接口调用请求说明
使用用户状态查询接口返回的path和authorize_package参数通过GET请求的方式拼接参数(注意:参数之后需要拼接#wechat_redirect)
举例如下:
path?appid=wxcbda96de0b165486&sub_appid=wxcbda96de0b165481&mch_id=10000098&sub_mch_id=10000096&openid=oUpF8uMEb4qRXf22hE3X68TekukE&plate_number=粤B888888&sign=EE088059BBC9141264F8D14293AD6C4BB94CEA8C08AA98FBF93E262D445F8FF5&sign_type=HMAC-SHA256&nonce_str=5K8264ILTKCH16CQ2502SI8ZNMTM67VS&trade_scene=PARKING#wechat_redirect
用户授权完成之后,会跳转回商户H5页面。
# 3.3 APP跳转接口调用请求说明
使用用户状态查询接口返回的path和authorize_package参数拼接WXLaunchMiniProgram.Req的path参数
安卓举例如下(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接收到客户端回调后再次调用用户状态查询接口获取用户的最新车主状态
# 4 委办局提供的接口
以下接口的数据都要经过加密传输,具体方法请查看《微信非税缴费文档》的数据加解密说明
# 4.1 车牌状态变更通知
请求参数
**返回结果**
示例
请求参数
{
"plate_number":"粤B888888",
"event_type":"BLOCKED",
"event_createtime":1543497810
}
返回结果
{
"errcode":0,
"errmsg":"成功"
}
## 4.2 支付结果通知
**请求参数**
返回结果
示例
请求参数
{
"order_id":"AQCAXCfypa-dC8EKDD96k7NeiEFb",
"status":3,
"pay_channel":"wx_nontax",
"pay_finish_time":1508806792
}
返回结果
{
"errcode":0,
"errmsg":"成功"
}