Autopay Fleet - Beta

Autopay Fleet consists of two parts:
  1. share Autopay permits among all their vehicles
  2. to be invoiced for all their vehicle cost when its vehicles park in all Autopay facilities (one invoice for all vehicles)

With the fleet company profile you get access to the Fleet API where you can manage a fleet of vehicles in Autopay and the parking and toll road passings of those vehicles.

The fleet profile is autopay wide, meaning you will only need one profile across all operators and countries. To get the "fleet service" you need to enter into an agreement with each Autopay operator. We can help and facilitate the process.

Autopay Fleet is a paid service. Getting a fleet company profile is manually handled. Please contact your Autopay representative or sales@autopay.io for more information.

Fleet API

Resources to manage the fleet vehicles: Functionalities related to parking and toll road passings: Information on error handling is available under the paragraph Error handling.

Access requirements

A valid authentication token is required to access the API. How to authenticate your application

To acquire Fleet API access, please contact an Autopay representative.


GET - Get all vehicles

This endpoint gives you all vehicles currently registered to the fleet.

Endpoint

GET https://api.autopay.io/fleet/v2/vehicles

Request parameters

The HTTP headers must include a valid access token for Fleet API.

Success response

HTTP Code: 200 OK

Parameter Type Description
license_plate_number string The vehicle registration number
country_code string The plate country code in Alpha 2 code
subdivision string Region on the vehicle registration, if it exists
created_at datetime (ISO 8601) The time when the vehicle was added to the fleet

Example success response

[
    {
        "license_plate_number":"AA12345",
        "country_code":"NO",
        "created_at":"2022-06-15T12:30:00+0200"
    },
    {
        "license_plate_number":"HDBB56789",
        "country_code":"DE",
        "subdivision":"HD",
        "created_at":"2022-07-30T20:30:00+0200"
    }
]

POST - Add a vehicle

This method allows adding vehicles to the fleet.

Endpoint

POST https://api.autopay.io/fleet/v2/vehicles

Request parameters

  • The HTTP headers must include a valid access token for Fleet API.
  • The request body must be in JSON format and HTTP headers must include Content-Type: application/json.
Parameter Type Mandatory Description
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists 
{
    "license_plate_number":"AA12345",
    "country_code":"NO"
}
{
    "license_plate_number":"BB12345",
    "country_code":"DE",
    "subdivision": "HD"
}

Success response

HTTP Code: 200 OK

Parameter Type Description
license_plate_number string The vehicle registration number
country_code string The plate country code in Alpha 2 code
subdivision string? Region of the vehicle registration, if it exists
created_at datetime (ISO 8601) The time when the vehicle was added to the fleet

Example success responses

{
    "license_plate_number":"AA12345",
    "country_code":"NO",
    "created_at":"2022-12-12T12:12:12+0000"
}
{
    "license_plate_number":"HDBB12345",
    "country_code":"DE",
    "subdivision":"HD",
    "created_at":"2022-11-05T09:15:02+0000"
}

DELETE - Remove a vehicle

This method allows removing vehicles from the fleet.

Endpoint

DELETE https://api.autopay.io/fleet/v2/vehicles

Request parameters

  • The HTTP headers must include a valid access token for Fleet API.

Parameter Type Mandatory Description
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists

Request example

DELETE https://api.autopay.io/fleet/v2/vehicles?license_plate_number=AA12345&country_code=NO

Success response

HTTP Code: 200 OK


Getting notified when a vehicle parks, passes through a toll road or has parked longer than preconfigured periods

Fleet API offers functionality to get HTTP POST requests to a configured Webhook endpoint to create a notification about a new service for a vehicle in the fleet.

The webhook endpoint requires HTTPS support, and the endpoint URLs must be provided when requesting access to the Fleet API.

It's possible to use different URLs and access tokens for entry notification webhook and periodical notification webhook.

Webhook Authentication

When configured, access token will be sent using Authorization header in the form of Bearer Yo!8lWDaGfZy.

Webhook POST JSON

Request body

Parameter Type Mandatory Description
id string yes A unique id of the service
vehicle
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists
created_at datetime (ISO 8601) yes The time when the vehicle was added to the fleet
facility
code string yes Facility's code
name string yes Facility's name
zone
code string yes Zone's code
name string yes Zone's name
start_time datetime (ISO 8601) yes Start time of the service in UTC
operator_id string yes ID of the operator
type string yes Type of the service. Possible types: PARKING, TOLL_ROAD
notification_period string no Amount of time in seconds between entry event and this notification. This field is only present on periodical notification webhook's request.
service_data map no Any additional data of the service

Request examples

{
    "id":"7cfb0be0-35eb-4afe-90cc-bb1c091a4231",
    "vehicle":{
        "license_plate_number":"AA12345",
        "country_code":"NO",
        "created_at":"2022-12-12T12:12:12+0000"
    },
    "facility": {
        "code": "TEST_FACILITY_1"
        "name": "Test Facility 1"
    },
    "zone": {
        "code": "TEST_ZONE_1"
        "name": "Test Zone 1"
    },
    "start_time":"2022-12-12T12:12:12+0000",
    "operator_id":"operator_id",
    "type":"PARKING",
    "serviceData":{
        "key":"value"
    }
}
{
    "id":"fb58c8b1-eb76-405e-99de-2a1a339a8222",
    "vehicle":{
        "license_plate_number":"HDBB12345",
        "country_code":"DE",
        "subdivision": "HD",
        "created_at":"2022-12-13T13:00:00+0000"
    },
    "facility": {
        "code": "TEST_FACILITY_1"
        "name": "Test Facility 1"
    },
    "zone": {
        "code": "TEST_ZONE_1"
        "name": "Test Zone 1"
    },
    "start_time":"2022-12-14T16:00:00+0000",
    "operator_id":"operator_id",
    "type":"PARKING",
    "notification_period": "900",
    "serviceData":{
        "key":"value"
    }
}

POST - Decline to pay for the vehicle

In some cases Fleet companies may wish to not take payment responsibility for a parking or toll road passings. Meaning the cost will not be invoice to the fleet company profile.

By calling this endpoint you can decline the payment responsibility for a specific parking or toll road passing. In doing so the normal invoice process will kick in and the owner of the vehicle will be invoiced instead.

The default behaviour is that all cost for a fleet vehicle are invoiced to the fleet company.

Most companies do not wish to use this endpoint.

Endpoint

POST https://api.autopay.io/fleet/v2/services/{service_id}/decline

Request parameters

  • The HTTP headers must include a valid access token for Fleet API.

Success response

HTTP Code: 200 OK


GET - Get all unpaid parkings and toll road passings

This method allows you to get a list of unpaid parkings and toll road passings for all of your vehicles in the fleet. Note that only finished sessions will be included in the results when using this endpoint.

Endpoint

GET https://api.autopay.io/fleet/v2/services

Request parameters

  • The HTTP headers must include a valid access token for Fleet API.

Parameter Type Mandatory Description
cursor string no Use the cursor string returned with response to get the next set of results

Request example

GET https://api.autopay.io/fleet/v2/services?cursor=ClQSTmoTaH5hdXRvcGF5LXRlc3QtY29yZXI3CxINZmxlZXRfc2VydmljZSIkMjc0Y2M2NGYtOTk5Yi00OTY0LThhZDQtZDEzYWY4MjMwNDY0DBgAIAA=

Success response

HTTP Code: 200 OK

Parameter Type Mandatory Description
services array of Services yes
summary Summary yes
Service
id string yes A unique id for the service.
vehicle Vehicle yes
start_time datetime (ISO 8601) yes Start time of the service in UTC
end_time datetime (ISO 8601) no End time of the service in UTC
cost Cost no
operator_id string yes ID of the service operator
type string yes Type of the service. Possible types: PARKING, TOLL_ROAD
service_data map no Any additional data of the service
invoicing_status string yes Status of invoice: NOT_INVOICED, NOT_INVOICEABLE, IN_INVOICING, INVOICED
Vehicle
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists
created_at datetime (ISO 8601) yes The time when the vehicle was added to the fleet
Cost
currency string yes Currency in Alpha 3 code
vat_percent double yes VAT percentage
net_amount double yes Net amount
vat_amount double yes VAT amount
gross_amount double yes Gross amount
Summary
total results integer yes Total number of results returned
more_results boolean yes Is there more results matching the path parameters
cursor string no Cursor string to fetch the next batch of results if more_results is true

Example response:

{
    "services": [
        {
            "id": "7cfb0be0-35eb-4afe-90cc-bb1c091a4231",
            "vehicle": {
                "license_plate_number": "AA12345",
                "country_code": "NO",
                "created_at": "2023-01-05T12:12:12+0000"
            },
            "start_time": "2023-01-12T12:14:12+0000",
            "end_time": "2023-01-12T13:55:04+0000",
            "cost": {
                "currency": "NOK",
                "vat_percent": 20,
                "net_amount": 20.20,
                "vat_amount": 4.04,
                "gross_amount": 24.24
            },
            "operator_id": "operator-id",
            "type": "PARKING",
            "service_data": {
                "key": "value"
            },
            "invoicing_status": "NOT_INVOICED"
        },
        {
            "id": "70b4746b-62fa-49a8-a445-878b35e560f0",
            "vehicle": {
                "license_plate_number": "HDBB12345",
                "country_code": "DE",
                "subdivision": "HD",
                "created_at": "2022-12-12T12:12:12+0000"
            },
            "start_time": "2022-12-12T12:12:12+0000",
            "end_time": "2020-12-12T12:12:12+0000",
            "cost": {
                "currency": "NOK",
                "vat_percent": 20,
                "net_amount": 20.20,
                "vat_amount": 4.04,
                "gross_amount": 24.24
            },
            "operator_id": "operator-id",
            "type": "PARKING",
            "service_data": {
                "key": "value"
            },
            "invoicing_status": "NOT_INVOICED"
        }
    ],
    "summary": {
        "total_results": 2,
        "more_results": false
    }
}

GET - Get unpaid parkings and toll road passings for a vehicle

This method allows you to get a list of parkings and toll road passings for a vehicle in the fleet.

Endpoint

GET https://api.autopay.io/fleet/v2/vehicles/services

Request parameters

  • The HTTP headers must include a valid access token for Fleet API.
  • The specified period in the from and to parameters cannot exceed the maximum limit of 50 days.

Parameter Type Mandatory Description
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists
type string no Type of service. Possible types: PARKING, TOLL_ROAD
from datetime (ISO 8601) no Filters out the services where the end_time is before from. The default value is to minus 50 days.
to datetime (ISO 8601) no Filters out the services where the end_time is after to. The default value is the current datetime.
include_running_services boolean no If set true, the response will include services that are still in progress

Request example

GET https://api.autopay.io/fleet/v2/vehicles/services?license_plate_number=AA12345&country_code=NO&type=PARKING&from=2022-06-06T19%3A34%3A40%2B0300&to=2022-07-06T19%3A40%3A40%2B0300&include_running_services=true

Success response

HTTP Code: 200 OK

Response body is a list of unpaid services.

Service object attributes

Parameter Type Mandatory Description
id string yes A unique id for the service.
vehicle yes
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists
created_at datetime (ISO 8601) yes The time when the vehicle was added to the fleet
start_time datetime (ISO 8601) yes Start time of the service in UTC
end_time datetime (ISO 8601) no End time of the service in UTC
cost no
currency string yes Currency in Alpha 3 code
vat_percent double yes VAT percentage
net_amount double yes Net amount
vat_amount double yes VAT amount
gross_amount double yes Gross amount
operator_id string yes ID of the service operator
type string yes Type of the service. Possible types: PARKING, TOLL_ROAD
service_data map no Any additional data of the service
invoicing_status string yes Status of invoice: NOT_INVOICED, NOT_INVOICEABLE, IN_INVOICING, INVOICED

Example response:

[
    {
        "id":"7cfb0be0-35eb-4afe-90cc-bb1c091a4231",
        "vehicle":{
            "license_plate_number":"AA12345",
            "country_code":"NO",
            "subdivision":null,
            "created_at":"2022-12-12T12:12:12+0000"
        },
        "start_time":"2022-12-12T12:12:12+0000"
        "end_time":"2020-12-12T12:12:12+0000",
        "cost": {
            "currency": "NOK",
            "vat_percent": 20,
            "net_amount": 20.20,
            "vat_amount": 4.04,
            "gross_amount": 24.24
        },
        "operator_id":"operator_id",
        "type":"PARKING",
        "serviceData":{
            "key":"value"
        },
        "invoicing_status": "INVOICED"
    }
]

POST - Lock/disable payment of parkings and toll road passing for users in Autopay

By default all payment options except invoice are enabled for fleet vehicles. So when someone is driving a fleet vehicle they can use Autopay like normal e.g. pay in the kiosk, automatically on exit or online within 48 hours. To avoid the situation where the customer pays twice, both in Autopay and to the fleet company when the vehicle is returned use this endpoint to stop Autopay from taking payment.

Once a parking or toll road passings is marked and payed externally Autopay will block all payment options making it impossible for a customer to pay twice for the same service.

The response to the request includes a list of successfully locked services with the relevant details.

Endpoint

POST https://api.autopay.io/fleet/v2/vehicles/disable_payments

Request parameters

  • The HTTP headers must include a valid access token for Fleet API.
  • The request body must be in JSON format and HTTP headers must include Content-Type: application/json.
  • The specified period in the from and to parameters cannot exceed the maximum limit of 50 days.

Parameter Type Mandatory Description
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region of the vehicle registration, if it exists
type string no Type of service. Possible types: PARKING, TOLL_ROAD
from datetime (ISO 8601) no Filters out the services where the end_time is before from. The default value is to minus 50 days.
to datetime (ISO 8601) no Filters out the services where the end_time is after to. The default value is the current datetime.
include_running_services boolean no If set true, the response will include services that are still in progress

Request examples

{
    "country_code": "NO",
    "license_plate_number": "AA12345",
    "type": "PARKING",
    "from": "2022-09-02T00:00:00+0200",
    "to": "2022-09-02T23:59:59+0200",
    "include_running_services": true
}
{
    "country_code": "DE",
    "license_plate_number": "BB12345",
    "subdivision": "HD",
    "type": "PARKING",
    "from": "2023-03-02T00:00:00+0200",
    "to": "2023-03-02T23:59:59+0200",
    "include_running_services": true
}

Success response

HTTP Code: 200 OK

Response body is list of unpaid and locked services.

Service object attributes

Parameter Type Mandatory Description
id string yes A unique id for the service.
vehicle yes
license_plate_number string yes The vehicle registration number
country_code string yes The plate country code in Alpha 2 code
subdivision string no Region the vehicle registration, if it exists
created_at datetime (ISO 8601) yes The time when the vehicle was added to the fleet
start_time datetime (ISO 8601) yes Start time of the service in UTC
end_time datetime (ISO 8601) no End time of the service in UTC
cost no
currency string yes Currency in Alpha 3 code
vat_percent double yes VAT percentage
net_amount double yes Net amount
vat_amount double yes VAT amount
gross_amount double yes Gross amount
operator_id string yes ID of the service operator
type string yes Type of the service. Possible types: PARKING, TOLL_ROAD
service_data map no Any additional data of the service
invoicing_status string yes Status of invoice: NOT_INVOICED, NOT_INVOICEABLE, IN_INVOICING, INVOICED

Example responses

[
    {
        "id":"7cfb0be0-35eb-4afe-90cc-bb1c091a4231",
        "vehicle":{
            "license_plate_number":"AA12345",
            "country_code":"NO",
            "created_at":"2022-12-12T12:12:12+0000"
        },
        "start_time":"2022-09-02T12:00:55+0000"
        "end_time":"2022-09-02T14:10:12+0000",
        "cost": {
            "currency": "NOK",
            "vat_percent": 20,
            "net_amount": 20.20,
            "vat_amount": 4.04,
            "gross_amount": 24.24
        },
        "operator_id":"operator_id",
        "type":"PARKING",
        "serviceData":{
            "key":"value"
        },
        "invoicing_status": "INVOICED"
    }
]
[
    {
        "id":"f6ed099c-63ba-4ddb-9a03-0a5b7229fff4",
        "vehicle":{
            "license_plate_number":"HDBB12345",
            "country_code":"DE",
            "subdivision":"HD",
            "created_at":"2022-12-12T12:12:12+0000"
        },
        "start_time":"2023-03-02T12:12:12+0000"
        "end_time":"2023-03-02T15:10:12+0000",
        "cost": {
            "currency": "NOK",
            "vat_percent": 20,
            "net_amount": 20.20,
            "vat_amount": 4.04,
            "gross_amount": 24.24
        },
        "operator_id":"operator_id",
        "type":"PARKING",
        "serviceData":{
            "key":"value"
        },
        "invoicing_status": "INVOICED"
    }
]

Error handling

Example error response

{
    "error_id": "authentication_error",
    "message": "No access token present in header!"
}

Possible error ids

Error id Explanation
forbidden Unauthorized
internal_server_error Internal server error
fleet_vehicle_get_error Failed to get vehicles
fleet_vehicle_save_error Failed to save vehicles
fleet_vehicle_delete_error Failed to delete vehicle
vehicle_services_invalid_date_range The specified period exceeds the maximum limit
cursor_decoding_error Failed to decode cursor