Payment API

On this page

• Who this API is for
• How it works
• Integration flow
• Scope and operator boundaries
• Setup and onboarding
• Authentication
• Session lifecycle and states
• API reference
  • POST - Connect parking
  • POST - Manual stop
  • Callback POST - Successful end of parking
  • Callback POST - Cancel parking
• Currency and VAT
• Error handling
• Related APIs
• Support

Who this API is for

The Payment API is designed for pay-by-app payment providers — services where the driver registers a vehicle, parks in a participating facility and is charged automatically after the session ends.

Other use cases (fleet platforms, mobility-as-a-service apps, in-house operator wallets) can be supported, but the API's design and onboarding process assumes the pay-by-app model. If you are integrating with a different use case in mind, please contact your Autopay representative early in your planning.

How it works

A typical session has six steps.

1. The vehicle enters a facility. Autopay detects the entry and starts a parking session.
2. The integrator becomes aware of the session. This can happen in two ways:
   • Manual start. The driver opens the integrator's app and initiates a parking session for their vehicle. The integrator's system decides the session should be paid for via the Payment API.
   • Autostart. The integrator listens for entry events from Autopay's Parking API and triggers the Payment API automatically when a known vehicle is detected. Autostart functionality requires a separate agreement and is set up with Autopay; a separate Parking API integration is also needed in addition to the Payment API. For more information, please contact your Autopay representative.
3. The integrator calls POST /connect_parking. This claims the session for the integrator. Autopay returns a parking_id and the session start time. From this point on, the integrator is responsible for billing this session.
4. The vehicle exits the facility. Autopay detects the exit and finalises the session, including the total cost and applicable VAT.
5. Autopay calls the integrator's success callback URL. The callback contains the final cost broken down into net, VAT and gross amounts, in the local currency.
6. The integrator charges the customer using whatever payment method the customer has on file in the integrator's system.

If something prevents the normal flow — a missed exit event, or an internal error in Autopay — there are two alternative paths covered in Session lifecycle and states.

What you do and what Autopay does

You never calculate the parking fee yourself — Autopay tells you what to charge. You do need to handle multiple currencies and VAT rates correctly in your system if you operate across countries.

Integration flow

The diagram below shows a typical session from entry to charge, including both trigger paths and the exception flows.

Scope and operator boundaries

Integration with the Payment API is per operator. Each operator is a separate scope with its own credentials and its own setup process.

If you want to support payments across multiple operators, you will:

• Receive a distinct client_id and client_secret for each operator
• Send the correct credentials when making API calls for that operator's facilities
• Complete the setup process for each operator separately

There is no cross-operator credential or single integration point. The credentials you receive are bound to one operator only — using them against another operator's facilities will return an error.

This per-operator model exists because each operator manages their own facility configuration, pricing and zone structure in Autopay independently. Your area codes, zone mappings and contract terms are agreed per operator.

Setup and onboarding

Setup involves three parties, each with distinct responsibilities.

Setup steps

1. Request access. Contact your Autopay representative and request Payment API access for one or more operators. Each operator you want to support will be set up separately.
2. Provide the integration details Autopay needs:
   • Your success callback URL (called when a session ends successfully)
   • Your cancel callback URL (called when a session is cancelled)
   • Your preferred authentication method for those callbacks (see Authentication)
   • Credentials for Autopay to authenticate against your callback URLs
   • The area code format and list you want to use for the operator's zones
3. Agree on area code mappings. Area codes are defined by you and correspond to your internal facility, lot or zone identifiers. The operator configures these codes against the relevant zones in Autopay so that calls to connect_parking can be matched to the right physical zone. The format is yours to choose — agree it with Autopay during setup.
4. Receive your credentials. Autopay will provide a client_id and client_secret for each operator. Store them securely.
5. Verify your setup. Confirm that your callback URLs are reachable from Autopay, that authentication works in both directions, and that test calls return as expected.

Testing options

There is no formal staging environment for the Payment API at present. If you need to test your integration before going live, please contact your Autopay representative to discuss available options.

Authentication

Calls from you to Autopay

All Payment API requests must include a valid access token. Tokens are obtained via the Authentication API using the client_id and client_secret issued to you for a specific operator.

See the Authentication page for details on requesting and using access tokens.

Calls from Autopay to your callbacks

Autopay supports the following authentication methods for calling your callback URLs:

• Basic authentication — username and password
• Bearer token — used in the Authorization header
• API key — used in the X-API-Key header
• OAuth (token provider) — Client ID, secret and token URL; Autopay will reuse access tokens for as long as they are valid

All credentials you provide are encrypted and stored securely.

Retry policy

If your callback endpoint does not respond with a 2xx or 404 status, Autopay will retry the call. Retries follow exponential backoff starting at 1 second and doubling each time (1s, 2s, 4s, 8s, …) up to a maximum interval of 1 hour. Retries then continue once per hour until one week has passed, after which the callback is abandoned.

Because the same callback may be delivered more than once, your endpoint should be prepared to handle duplicate deliveries safely — typically by treating the parking_id as an idempotency key.

Session lifecycle and states

A parking session goes through one of three terminal states from the integrator's perspective:

• Ended — the vehicle exited normally and Autopay finalised the session. You charge the customer.
• Cancelled — the session went into an error state in Autopay and should not be charged.
• Manually stopped — you requested a manual stop because an exit event was missed. This eventually leads to an Ended state (with a success callback) for the manually stopped session.

About manual stops and follow-up sessions

The manual_stop endpoint exists to handle the case where an exit event is missed by Autopay — for example, when the operator's ANPR equipment fails to detect an exit. It is not intended to let customers end their parking voluntarily through your app.

When you request a manual stop:

1. Autopay closes the current session and sends you a success callback with the cost calculated up to the end_time you provided.
2. Internally, Autopay creates a follow-up session in case the vehicle is still actually on site. This is a safeguard against misuse.
3. If the vehicle later genuinely exits, Autopay handles the follow-up session through its regular mechanism. You will not receive further callbacks for it and you should not charge the customer again.

In other words, from your side: one manual_stop request leads to exactly one success callback, and you are done.

API reference

POST - Connect parking

This method allows you to register an external payment and connect it to the parking.

Endpoint

POST https://api.autopay.io/payment/v1/connect_parking

Request parameters

• The request body must be in JSON format and HTTP headers must include Content-Type: application/json.
• The headers must include a valid access token.

Example request

{
    "parking_area_code": "area1",
    "reference": "ref1",
    "vehicle_reg": "123ABC",
    "plate_issuer": "NOR",
    "plate_subdivision": null
}

Success response

HTTP Code: 200 OK

Example success response

{
    "parking_id": "1234567890",
    "reference": "ref1",
    "start_time": "2019-02-26T11:52:16+0000"
}

POST - Manual stop

This method allows the payment provider to request a manual stop for a parking session in Autopay — for example, when an exit event is missed in the Autopay system.

After a successful manual stop, Autopay sends a Successful end of parking callback with the final cost. See Session lifecycle and states for the full behaviour, including how Autopay handles a follow-up session internally.

Note: The manual stop method should only be used if there is a missed exit event or some other issue with the parking. It should not be used to allow customers to finish their parking using the external payment application.

Endpoint

POST https://api.autopay.io/payment/v1/manual_stop

Request parameters

• The request body must be in JSON format and HTTP headers must include Content-Type: application/json.
• The headers must include a valid access token.
• Please see the table below for post parameters.

Example request

{
    "parking_id": "1234567890",
    "reference": "ref1",
    "end_time": "2019-02-28T11:52:16+0000"
}

Success response

HTTP Code: 200 OK. A success callback with the final cost will follow.

Callback POST - Successful end of parking

When a session ends successfully — either through a normal exit or as the result of a manual stop — Autopay sends a POST request with the parking details to the provided success callback URL.

Request body

Example request body

{
    "parking_id": "1234567890",
    "reference": "ref1",
    "end_time": "2019-02-28T11:52:16+0000",
    "cost": {
        "currency": "NOK",
        "vat_percent": 20.0,
        "net_amount": 100.0,
        "vat_amount": 20.0,
        "gross_amount": 120.0
    }
}

Expected response from your callback

Respond with HTTP Code 200 OK to acknowledge receipt.

Callback POST - Cancel parking

If the parking goes into an error state in Autopay and shouldn't be charged to the customer, Autopay sends a cancellation message to the provided cancel callback URL. When you receive this callback, do not charge the customer for the session.

Request body

Example request body

{
    "parking_id": "1234567890",
    "reference": "ref1"
}

Expected response from your callback

Respond with HTTP Code 200 OK to acknowledge receipt.

Currency and VAT

Cost amounts are denominated in the local currency of the country where the parking takes place. VAT is calculated according to local rules for that country.

If you operate across multiple countries, your system needs to handle multiple currencies and VAT rates. The success callback always provides the breakdown, so you do not need to calculate VAT yourself — but you do need to store and charge in the right currency.

Error handling

Errors returned by the API follow a common shape.

Example error response

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

Possible error id-s

Related APIs

• Authentication — required for all Payment API calls. Issues the access tokens you will use as bearer tokens.
• Parking API — required if you want to implement autostart by reacting to entry events. Not required for manual-start integrations.

Support

For access requests, integration questions or issues with a live integration, please contact your Autopay representative. If you do not yet have a contact at Autopay, reach out via autopay.io.