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 external payment providers. In most cases, this means 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 external payment provider becomes aware of the session. This can happen in two ways:
   • Manual start. The driver opens the payment app and initiates a parking session for their vehicle. The external payment provider's system decides the session should be paid for via the Payment API.
   • Autostart. The external payment provider 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 external payment provider calls POST /connect_parking. This claims the session for the external payment provider. Autopay returns a parking_id and the session start time. From this point on, the session is marked as paid in Autopay, and the external payment provider is responsible for charging the customer. If the parking session is linked to an external payment provider, Autopay returns an error The parking session is already linked to an external payment provider with error id server_communication_error.
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 external payment provider's success callback URL. The callback contains the final cost broken down into net, VAT and gross amounts, in the local currency.
6. The external payment provider charges the customer using whatever payment method the customer has on file in the external payment provider'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 external payment provider does and what Autopay does

External payment provider never calculates the parking fee - Autopay tells what to charge. The external payment provider needs to handle multiple currencies and VAT rates correctly in their system if they 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 the external payment provider wants to support payments across multiple operators, they 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 the external payment provider receives 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. External payment provider's 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. External payment provider charges the customer.
• Cancelled — the session went into an error state in Autopay and should not be charged.
• Manually stopped — external payment provider 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 a manual stop is requested by the external payment provider:

1. Autopay closes the current session and sends a success callback with the cost calculated up to the end_time provided in the request.
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. The external payment provider will not receive further callbacks for it and should not charge the customer again.

API reference

POST - Connect parking

This method allows 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"
}

Error response

HTTP Code: 400

Example error response

{
    "error_id": "server_communication_error",
    "message": "Payment provider already registered"
}

POST - Manual stop

This method allows the external 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 receiving 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 operating across multiple countries, external payment provider's system needs to handle multiple currencies and VAT rates. The success callback always provides the breakdown, so there is no need to calculate VAT — 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.