1. Process Introduction
1.1 Workflow of Business Process
2. APIs in Weixin NTR Platform (Driver Service Backend)
2.1 Querying User Status
2.2 User Entry Notification
2.3 Applying for Deduction
2.4 Error Code
3. User Authorization/Activation
3.1 Mini Program Redirect API Request Format
3.2 H5 Redirect API Request Format
3.3 App Redirect API Request Format
4. APIs Provided by the Government Unit
4.1 Notification of License Plate Status Change
4.2 Payment Status Notification

# 1. Process Introduction

# 1.1 Workflow of Business Process

Note:
Step 3: Call the entry notification API (applicable to post-exit deductions. This API is not required for pre-exit deductions. To get the status of drivers who have entered, use the "Query User Status" API). This API is used for merchant registration to receive user status changes, and it returns user status.
Step 7: Applications for payments-on-behalf only returns the application acceptance result, and does not represent the final deduction status. If a system exception or network timeout is returned, retry with the original request parameters. A merchant order number corresponds to a payment order.
Step 10: Accepted orders may not be paid due to insufficient funds in the user's Balance or bank card. Here, the merchant can contact Weixin operations to apply for Weixin's capital advance. (For users with insufficient funds in their Balance or bank cards, Weixin will make the payments on their behalf first and then prompt the user to repay.)

# 2. APIs in Weixin NTR Platform (Driver Service Backend)

# 2.1 Querying User Status

Use Cases
In parking lots, highways, gas stations etc., merchants must obtain the user's driver service status or link the driver service. This API will query if the user has performed activation and authorization, if they are in arrears, or if they have been blacklisted, and then returns the corresponding user status.
Process introduction

Call the "Query User Status" API to get the current user's driver status. If the current user's driver status is abnormal (such as in arrears (OVERDUE) or unauthorized (UNAUTHORIZED)), the API will sync and return the redirect path (path field). The merchant side needs to guide users according to step 2 to access the driver service and perform related operations. If the current user's driver status is normal, the path field will not be returned and there is no need to guide the user to access the driver service again.
For Mini Program and app redirection, call the "User Authorization/Activation API" via the redirection path to access the relevant page of the driver Mini Program, where users can perform authorization/activation. For H5 redirection, call the "User Authorization/Activation API" via the redirection path to access the relevant page of the driver H5, where users can perform authorization/activation.
Return to merchant Mini Program, app, or H5 page before calling the "Query User Status" API to confirm the user's latest driver status and license plate information.

https://api.weixin.qq.com/nontax/vehicle/querystate?access_token=$AccessToken

Request parameters

Field	Type	Required	Description
appid	string	Yes	AppID
bank_id	string	No	Bank ID (the globally unique ID assigned by Weixin NTR Platform), which, if not specified, is selected randomly from the list of banks configured; it is left empty for the production environment while required for the test environment.
bank_account	string	No	Sorting bank account (left empty if sorting mechanism is not used)
mch_id	string	No	Specifies the mch_id to which the payment is settled. Only the mch_ids linked with bank_id are available. If not specified, the system will automatically choose one from those linked.
region_code	string	Yes	Code of the region
trade_scene	string	Yes	The scene value of a payments-on-behalf transaction, which will be displayed to Weixin users. PARKING: Parking lot; PARKING SPACE: Specific parking space; HIGHWAY: Highway; BRIDGE: Bridge.
jump_scene	string	No	The business scenario to which the merchant is redirected. If not passed, it defaults to a Mini Program. Redirection to H5 via apps and Official Accounts are also supported.
openid	string	No	Unique user identifier in the merchant appid. Either the openid or license plate number must be selected.
plate_number	string	No	License plate number. Only includes province + license plate, and does not include special characters. Either the openid or license plate number must be selected.
material_info	string	No	Material code information scanned by users to access merchant Mini Programs
channel_type	string	No	Highway channel type: ETC, MTC. Deduction only allowed when the user's license plate has a channel identifier. Fill in this field when the scene value is HIGHWAY.

Response

Field	Type	Required	Description
errcode	int	Yes	Error code
errmsg	string	No	Description of the error code
user_state	string	Yes	NORMAL: Normal users with driver service activated and access authorization granted. PAUSED: Driver service paused. OVERDUE: Driver service activated but in arrears. Prompt the user for payment and redirect to driver service. UNAUTHORIZED: The user is not authorized to use the current service, or has not activated the driver service. Redirect to the authorization API.
openid	string	No	Unique user identifier in the merchant appid. Return when user enters the driver platform.
path	string	No	The path to the driver Mini Program page. If this parameter does not return an empty string, the merchant side must call the "User Authorization/Activation API" to guide the user to access the driver Mini Program and perform authorization/activation. See below for details of the "User Authorization/Activation API". The same applies to the redirection to H5. Scenes that require redirection: User in normal status but without license; In arrears; Unauthorized; Service not activated or suspended.
plate_number_info	json	No	The license plate list. Only includes province + license plate, and does not include special characters. Note: no value is returned in PARKING SPACE scenario.
authorize_package	json	No	Authorization parameter information. Returns when path is not empty. This is used during user authorization/activation.

Example

{ 
  "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"
}

Response

{   
  "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 User Entry Notification
**Use Cases**
In a parking lot scenario, an entry notification will be made if the user has been added to the driver platform; if the user is in arrears, an entry notification about a user in arrears will be sent. This API queries if a user is in arrears or has been blacklisted, and returns the corresponding user status.
Note
This API is mainly used for post-exit deductions. Weixin will sync the user's driver status in real-time to the merchant side for maintenance of the driver whitelist. There is no need to call this API if the merchant side uses a pre-exit deduction scenario. When the user enters the parking lot, the "Query User Status" API can be used to get the current user's driver status.

https://api.weixin.qq.com/nontax/vehicle/entrancenotify?access_token=$AccessToken

Request parameters

Field	Type	Required	Description
appid	string	Yes	AppID
bank_id	string	No	Bank ID (the globally unique ID assigned by Weixin NTR Platform), which, if not specified, is selected randomly from the list of banks configured; it is left empty for the production environment while required for the test environment.
bank_account	string	No	Sorting bank account (left empty if sorting mechanism is not used)
mch_id	string	No	Specifies the mch_id to which the payment is settled. Only the mch_ids linked with bank_id are available. If not specified, the system will automatically choose one from those linked.
region_code	string	Yes	Code of the region
trade_scene	string	Yes	The scene value of a payments-on-behalf transaction, which will be displayed to Weixin users. PARKING: Parking lot; PARKING SPACE: Specific parking space; HIGHWAY: Highway; BRIDGE: Bridge.
scene_info	json	Yes	Scene information value in JSON format. Sets different values for different service scenarios. See the list below for more details.

The internal scene_info fields are as follows:
When the trade_scene scenario is PARKING (parking lot), pass the following values

Field	Type	Required	Description
start_time	int	Yes	The start time of the parking (timestamp, in seconds), displayed when Weixin users are asked for payment.
plate_number	string	Yes	License plate number. Only includes province + license plate, and does not include special characters.
notify_url	string	No	Receives notifications of license plate status changes
car_type	string	No	The type of the parked vehicle: large vehicle, small vehicle.
parking_name	string	Yes	Current parking lot name
free_time	int	Yes	Free parking time (in seconds)

Response

Field	Type	Required	Description
errcode	int	Yes	Error code
errmsg	string	No	Description of the error code
user_state	string	Yes	NORMAL: Normal status, indicating the user may use driver services. BLOCKED: Abnormal status, indicating the user may not use driver services.

Example

Request parameters
{
  "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": "Small vehicle",
  "parking_name": "test_parking_name",
  "free_time": 1200,
  "plate_number": "粤B888888",
  "openid": "ont-9vjAcIdSU-LgB7ubALAVJO9U"
}
Response
{
  "errcode": 0,
  "errmsg": "ok",
  "user_state": "NORMAL"
}

## 2.3 Applying for Deduction
**Use Cases**
Payments-on-behalf can be used in scenarios where regular deductions or post-event deductions are made to increase efficiency. For example, users can authorize merchants to perform payments-on-behalf in highway or parking lot scenarios.
Note: The deduction request is first made according to the preferred payment method noted in the agreement. Otherwise, the deduction method will be selected from available deduction methods.
Note
As the current driver service only supports blue, green, and black license plates, in parking lot or highway scenarios, merchants must identify the license plate type when the vehicle exits. Vehicles with license plates that are not blue, green, or black will not be able to make payment through the driver service.

https://api.weixin.qq.com/nontax/vehicle/payapply?access_token=$AccessToken

Request parameters

Field	Type	Required	Description
appid	string	Yes	AppID
bank_id	string	No	Bank ID (the globally unique ID assigned by Weixin NTR Platform), which, if not specified, is selected randomly from the list of banks configured; it is left empty for the production environment while required for the test environment.
bank_account	string	No	Sorting bank account (left empty if sorting mechanism is not used)
mch_id	string	No	Specifies the mch_id to which the payment is settled. Only the mch_ids linked with bank_id are available. If not specified, the system will automatically choose one from those linked.
desc	string	Yes	Description (service name)
fee	int	Yes	Total amount (in cents)
payment_notice_no	string	No	Payment notice No. (Either the payment notice No. or the order No. must be provided. If the payment notice No. is not specified, the order No. is required.)
order_no	string	No	Order No. (Either the payment notice No. or the order No. must be provided. If the payment notice No. is not specified, the order No. is required.)
department_code	string	Yes	Code of the collection entity
department_name	string	Yes	Name of the collection entity
payment_notice_type	int	No	Type of the payment notice
region_code	string	No	Code of the region
goods_tag	string	No	Parameters of product tags, vouchers or discounts. For details, see vouchers or discounts.
trade_scene	string	Yes	The scene value of a payments-on-behalf transaction, which will be displayed to Weixin users. PARKING: Parking lot; PARKING SPACE: Specific parking space; HIGHWAY: Highway; BRIDGE: Bridge.
scene_info	string	Yes	Scene information value in JSON format. Sets different values for different service scenarios. See the list below for more details.
order_id	string	No	Order number. If this field is entered, other parameters except appid are not required.

The internal scene_info fields are as follows:
When the trade_scene scenario is PARKING (parking lot), pass the following values:

Field	Type	Required	Description
start_time	int	Yes	The start time of the parking (timestamp, in seconds), displayed when Weixin users are asked for payment.
end_time	int	No	The end time of the parking time (timestamp, in seconds), displayed when Weixin users are asked for payment.
charging_time	int	Yes	Paid parking time (in seconds)
plate_number	string	Yes	License plate number. Only includes province + license plate, and does not include special characters.
car_type	string	No	The type of the parked vehicle: large vehicle, small vehicle.
parking_name	string	Yes	Current parking lot name

When the trade_scene scenario is PARKING SPACE (specific parking space), pass the following values:

Field	Type	Required	Description
start_time	int	Yes	The start time of the parking (timestamp, in seconds), displayed when Weixin users are asked for payment.
end_time	int	No	The end time of the parking time (timestamp, in seconds), displayed when Weixin users are asked for payment.
charging_time	int	Yes	Paid parking time (in seconds)
car_type	string	No	The type of the parked vehicle: large vehicle, small vehicle.
parking_name	string	No	Current parking lot name
openid	string	Yes	Unique user identifier in the merchant appid
space_number	string	Yes	User specific parking space number, only supports letters + numbers.

When the trade_scene scenario is HIGHWAY, pass the following values:

Field	Type	Required	Description
start_time	int	Yes	The time when a user enters the highway (timestamp, in seconds), displayed when Weixin users are asked for payment.
end_time	int	Yes	The time when a user exits the highway (timestamp, in seconds), displayed when Weixin users are asked for payment.
plate_number	string	Yes	License plate number. Only includes province + license plate, and does not include special characters.
car_type	string	No	The type of parked vehicle: coach, truck
entrance_name	string	Yes	The name of the Highway tollbooth entrance station
exit_name	string	Yes	The name of the highway tollbooth exit station
carrying_capacity	string	No	Current vehicle carrying capacity (numbers only)
carrying_range	string	No	Current vehicle carrying capacity range, format: number - number
channel_type	string	Yes	Highway channel type: ETC, MTC. The merchant must confirm the type of the current license plate before deducting the fee. The user license plate must have the channel identifier for the deduction to be permitted.

When the trade_scene scenario is BRIDGE, pass the following values:

Field	Type	Required	Description
start_time	int	Yes	The period in which the user passes through the bridge tollbooth (timestamp, in seconds), displayed when Weixin users are asked for payment.
plate_number	int	Yes	License plate number. Only includes province + license plate, and does not include special characters.
car_type	string	No	Vehicle type: large vehicle, small vehicle
exit_name	string	Yes	Exit tollbooth station name. Must be displayed to users, e.g. Humen Bridge

Response

Field	Type	Required	Description
errcode	int	Yes	Error code
errmsg	string	No	Description of the error code
order_id	string	Yes	Order No.

Example

Request parameters
{
  "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" : "Test collection entity name",
  "desc" : "Testdesc",
  "fee" : 1,
  "goods_tag" : "", 
  "trade_scene" : "PARKING SPACE",
  "scene_info" :
  {   
  "start_time": 1542351485,
  "charging_time": 3600,
  "car_type": "Small vehicle",
  "parking_name": "test_parking_name",
  "openid": "ont-9vjAcIdSU-LgB7ubALAVJO9U",
  "space_number": "D666666"
  }
 }
Response
{
  "errcode": 0,
  "errmsg": "ok",
  "order_id": "AQAAhNw2srPiUjMKDJ7fvb4AAAAA"
}

## 2.4 Error Code

Error Code	Description
9207028	This license plate is not linked to the driver platform.
9207029	User does not meet the requirements of charging without password. Use the "Query User Status" API to query user status and guide the user accordingly.
9207030	Authorization check failed. Call the authorization API to complete user authorization for the appid.
9207031	User payment exceeds the limit.
9207032	Payment confirmation failed. The user's Weixin ID has been flagged as risky or has been frozen.
9207033	Deduction request exceeded the stipulated operation time. In highway scenarios, ETC channels must deliver transactions within 48 hours.
9207034	Deduction request identifier is inconsistent with current license plate channel identifier. In highway scenarios, the license plate must have the corresponding (ETC or MTC) channel identifier for payment deduction.

# 3. User Authorization/Activation

##3.1 Mini Program Redirect API Request Format

|API |wx.navigateToMiniProgram(OBJECT)API |

Use the path and authorize_package parameters returned by the "Query User Status" API to fill the path and extraData parameters

Example:

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) {
  // Unable to redirect to the driver Mini Program
      }
  })

After the user completes authorization, they will be redirected back to the merchant Mini Program. The response can be determined by the parameters carried by the onShow(OBJECT). For the OBJECT response parameters, see the onShow parameter description in the Mini Program Developer Guide.
The referrerInfo or the referrerInfo. extraData is null (or undefined) when the user abandons the operation. When the driver platform Mini Program succeeds or fails to return to the merchant Mini Program, the referrerInfo.extraData field is as follows:

User authorization results: 
  true:Authorized 
  false:Authorization failed

Example:

App({
      onShow(res) {
          if (res.scene === 1038) { // Scene value 1038: return from the open Mini Program
              const { appId, extraData } = res.referrerInfo
              if (appId == 'wxbcad394b3d99dac9') { // appId is wxbcad394b3d99dac9: redirected from the driver Mini Program
                  if (typeof extraData == 'undefined'){
                      // TODO
                      // Unknown authorization result. The "Query User Status" API must be called.
                      return;
                  }
                  if(extraData.auth == 'true'){
                      // TODO
                      // Authorization successful
                      return;
                  } else {
                      // TODO
                      // Authorization failed
                      return;
                  }
              }
          }
      }
  })

## 3.2 H5 Redirect API Request Format
Join the path and authorize_package parameters returned by the "Query User Status" API via the GET request. (Note: #wechat_redirect must be joined after the parameters.)

For example:

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

After the user completes authorization, they will be redirected to the merchant's H5 page.

# 3.3 App Redirect API Request Format

Join the path and authorize_package parameters returned by the query user status API with the path parameter of WXLaunchMiniProgram.Req.

The following example shows how the app calls the Mini Program on Android:

String appId =
"wxcdbdf056ad5fc1fb"; // Enter the app AppId
IWXAPI api = WXAPIFactory.createWXAPI(context, appId);
WXLaunchMiniProgram.Req req = new WXLaunchMiniProgram.Req();
req.userName = "gh_518c42c65952"; // Enter the original driver Mini Program ID, which is always 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\"}";// Path that can contain parameters, used to launch a page of the Mini Program. If it is not specified, the homepage of the Mini Program is launched by default.
req.miniprogramType = WXLaunchMiniProgram.Req.MINIPTOGRAM_TYPE_RELEASE;
api.sendReq(req);

After user activation/authorization, they will be redirected back to the merchant's app and no parameters will be returned. After the merchant-side app receives the client callback, it will call the "Query User Status" API again to get the latest driver status of the user.

# 4. APIs Provided by the Government Unit

All data for the following API must be encrypted before transmission. For details, refer to data encryption and decryption instructions in the Weixin NTR Payment Documentation.

# 4.1 Notification of License Plate Status Change

Request parameters

Field	Type	Required	Description
plate_number	string	Yes	License plate number
event_type	string	Yes	Type of the license plate status: NORMAL: The license plate is available; BLOCKED: The license plate is not available. Note that it's the status of license plates, not users.
event_createtime	int	Yes	The time when the license plate status changes (timestamp, in seconds), based on which merchants can determine whether to update the current license plate status.

**Response**

Field	Type	Required	Description
errcode	int	Yes	Error code
errmsg	string	No	Description of the error code

Example

Request parameters
{
"plate_number":"粤B888888",
"event_type":"BLOCKED",
"event_createtime":1543497810
}
Response
{
"errcode":0,
"errmsg":"Successful"
}

## 4.2 Payment Status Notification
**Request parameters**

Field	Type	Required	Description
order_id	string	Yes	Order No. in the Weixin NTR Platform
status	int	Yes	Status. 3 or 4: Paid; 5: Refunded; 101: Payment Failed.
pay_channel	string	Yes	Payment channel, and "wx_nontax" represents Weixin NTR Platform.
pay_finish_time	int	No	Finish time of order payment (timestamp, in sec), only available when the status is Paid.
refund_finish_time	int	No	Finish time of order refund (timestamp, in sec), only available when the status is Refunded.
refund_fee	int	No	Refund amount. It is required for partial refund.
refund_order_id	string	No	Refund order No. It is required for partial refund.

Response

Field	Type	Required	Description
errcode	int	Yes	0 - Successful; 210 - Invalid data format; 298 - Decryption failed; 299 - System error; 300 - Invalid signature
errmsg	string	No	Error message. A non-NULL value indicates the error cause.

Example

Request parameters
{
"order_id":"AQCAXCfypa-dC8EKDD96k7NeiEFb",
"status":3,
"pay_channel":"wx_nontax",
"pay_finish_time":1508806792
}

Response
{
"errcode":0,
"errmsg":"Successful"
}