OCPI: roaming between charging networks
How the Open Charge Point Interface of the EVRoaming Foundation connects charge point operators and mobility service providers: roles, versions up to 2.3.0 and the 3.0 work, the modules from credentials to CDRs, and what goes wrong between operators.
Roaming in one paragraph
A driver has a card or app from one company (the eMSP, e-mobility service provider) and charges at a station run by another (the CPO, charge point operator). The charger talks OCPP to the CPO backend (OCPP: the charger's link to its backend). The two backends talk OCPI: the CPO publishes its locations and prices, the eMSP publishes its tokens, and after the session the CPO sends a charge detail record (CDR) that the eMSP bills to the driver. Both can connect directly, peer to peer, or through a hub.
Versions
| Version | Date | What changed |
|---|---|---|
| 2.1.1 | 8 June 2017 | The version many older connections still run |
| 2.2 | 30 September 2019 | Hub support, platform roles, charging profiles, many clarifications |
| 2.2.1 | 6 October 2021 | Final release of 2.2.1; the version most rules name |
| 2.2.1-d2 | 7 September 2023 | Documentation update, tariff text rewritten |
| 2.3.0 | Tagged 21 February 2025 | Extensibility, parking objects on EVSEs, accepted eMSPs per EVSE, information for people with disabilities, North American taxes, ISO 15118 Plug and Charge flags on connectors, a Payments module for payment terminals |
| 3.0 | In development | Worked on in a repository open only to contributors of the EVRoaming Foundation |
The specification is published by the EVRoaming Foundation under CC BY-ND 4.0. Public rules name versions: the US NEVI standards and the UK open data duty point to OCPI 2.2.1 (North America: J1772, CCS1, J3400 and the NEVI standards, United Kingdom: smart charge points, the Public Charge Point Regulations and Type 2 with CCS2).
The dates are from the version history and the tags of the OCPI repository. What OCPI 3.0 will contain is only known from secondary sources, and the summary of what 2.2 added is this page's own.
The modules
| Module | Owner of the data | What it carries |
|---|---|---|
| versions and credentials | Both (configuration) | Which versions and endpoints a party offers, and the exchange of tokens that registers two parties with each other |
| locations | CPO | Locations, their EVSEs and connectors, with status, opening hours and capabilities |
| sessions | CPO | Running sessions: energy so far, cost so far, status |
| cdrs | CPO | The charge detail record after a session: the final energy, time, tariff and price the eMSP bills |
| tariffs | CPO | Prices per kWh, per time, per session, with restrictions such as time of day or power |
| tokens | eMSP | The eMSP's cards and app tokens, each with a whitelist setting (ALWAYS, ALLOWED, ALLOWED_OFFLINE, NEVER) that decides whether the CPO may accept it from its copy or must ask the eMSP in real time |
| commands | eMSP sends, CPO answers | START_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION and UNLOCK_CONNECTOR; the result comes back asynchronously |
| chargingprofiles | Smart charging service provider | Charging limits for a running session, passed on to OCPP |
| hubclientinfo | Hub | Which parties behind a hub are connected |
| payments (2.3.0) | Payment terminal provider | Payment terminals at the charger and the financial result of a session |
What goes wrong between operators
- Stale locations: a status update that arrives late or never, so the app shows a free charger that is occupied or broken.
- Tariffs that do not match: the price shown before charging differs from the CDR, because of step sizes, minimum prices, taxes or a tariff the eMSP never received.
- CDRs: missing or late, carrying the CPO's internal session ID instead of the roaming ID, sent twice, or with implausible values such as more energy than the connector can deliver in the time.
- Tokens: an eMSP that sets NEVER for its tokens makes every start wait for a real-time answer; the specification itself notes the longer delay at the charger. A token the CPO copy does not know yet fails at the charger.
- Commands: a remote start that the CPO accepts but whose asynchronous result never arrives, so the app keeps waiting.
- Registration: credentials tokens that were rotated on one side only, or endpoints registered with the wrong role, so one direction of the connection fails silently.
Most of these show up as a payment or support problem (Payment, roaming and Plug and Charge). The energy in the CDR starts in the charger's OCPP meter values, so a CDR that looks wrong can often be traced back to the OCPP log of the session.
In this tool
Drop the CDR or the OCPI session of a charging with its capture: as JSON, as the response of the OCPI API, or as a log with one JSON body per line; OCPI 2.1.1 and 2.2.x are both read. The OCPI tab lists the records beside the session they overlap in time, and four checks hold them against the object definitions and against the session. The demo ac-ok carries a CDR.
- CDR-01: the fields each version requires are there, and a CDR uses no dimension OCPI keeps for Sessions.
- CDR-02: total_time fits start and end, the charging periods lie inside the record, the parking time fits in the session, total_energy is the sum of the ENERGY dimensions, and the cost parts and VAT add up.
- CDR-03: the record covers the energy transfer on the cable, and bills the energy of the OCPP transaction.
- CDR-04: signed values in signed_data verify when they are OCMF records, with the key the CDR carries.
Sources
- EVRoaming Foundation: OCPI specification repository, README, version history, changelog, copyright (CC BY-ND 4.0), module descriptions; tags 2.2.1 and v2.3.0
- OCPI 2.2.1 (PDF)
- EVRoaming Foundation
- Solidstudio: OCPI 3.0 key updates, secondary source on the 3.0 draft
- Digital Charging Solutions: What are the most common reasons an invoice gets disputed or rejected
- Digital Charging Solutions: What makes a CDR invalid
- ChargeX Consortium: OCPI recommendations, June 2025, listed for further reading; not read for this page