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

VersionDateWhat changed
2.1.18 June 2017The version many older connections still run
2.230 September 2019Hub support, platform roles, charging profiles, many clarifications
2.2.16 October 2021Final release of 2.2.1; the version most rules name
2.2.1-d27 September 2023Documentation update, tariff text rewritten
2.3.0Tagged 21 February 2025Extensibility, 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.0In developmentWorked 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

ModuleOwner of the dataWhat it carries
versions and credentialsBoth (configuration)Which versions and endpoints a party offers, and the exchange of tokens that registers two parties with each other
locationsCPOLocations, their EVSEs and connectors, with status, opening hours and capabilities
sessionsCPORunning sessions: energy so far, cost so far, status
cdrsCPOThe charge detail record after a session: the final energy, time, tariff and price the eMSP bills
tariffsCPOPrices per kWh, per time, per session, with restrictions such as time of day or power
tokenseMSPThe 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
commandseMSP sends, CPO answersSTART_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION and UNLOCK_CONNECTOR; the result comes back asynchronously
chargingprofilesSmart charging service providerCharging limits for a running session, passed on to OCPP
hubclientinfoHubWhich parties behind a hub are connected
payments (2.3.0)Payment terminal providerPayment 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