Build consistent vocabulary across product, engineering, and partner teams. Covers roles, data objects, and common naming pitfalls. OCPI Explained · Message Flows · OCPI Testing Tool
Core OCPI Concepts
Entity Roles & Responsibilities
OCPI Module Types
Communication Patterns
Best Practices & Guidelines
OCPI works on some simple ideas that make charging your electric car easier. Think of it like teaching different companies to speak the same language!
Working Together
Just like how you can call anyone no matter which phone company they use, OCPI lets different charging companies work together so you can charge anywhere.
Two-Way Talking
Companies can both send information and ask for information, making it easy to keep everything up-to-date, like when stations are available or busy.
Always Up-to-Date
All companies have the latest information about charging stations, prices, and your charging history - like how your contacts sync across your devices.
Keeping Things Safe
Uses special keys (tokens) to make sure only authorized companies can access information, keeping your charging and payment details secure.
What defines OCPI 2.2.1
Modules in this version
A sending side and a receiving side
Each module now has two sides: the one that pushes data out and the one that takes it in.
The trust token is encoded
The shared secret is Base64-encoded before it is sent, rather than sent in plain form.
Billing records name the party
A charge record now says which country and company the driver token belongs to.
Key Terms:
OCPI
A common language that lets different charging companies talk to each other
Context: Helps you charge at any station with just one appInteroperability
Different companies' systems work together without a custom integration for every pair.
Context: Makes charging your electric car smooth and easyPush
One company sends an update the moment it happens, without being asked.
Context: Like when a station tells your app it's availablePull
Your app asks another company for what it needs, when it needs it.
Context: Like checking station locations and pricesThe vocabulary an OCPI integration argues in
Most OCPI misunderstandings are vocabulary problems wearing a technical costume. Two teams say "session" and mean different things, or one says "token" meaning the driver credential and the other means the auth header, and the disagreement only surfaces as a bug days later. The terms below are the ones a roaming conversation is conducted in.
The pairs worth being careful about: a CPO owns the charger, an eMSP owns the driver relationship, and a hub sits between many of each so they do not have to integrate pairwise. An EVSE is the thing that actually delivers power, and a Location can hold several. A Session is a charge in progress. A CDR is the record of one that finished, and it is the document that money moves on, which is why a partner will reject it over a missing field rather than accept it and sort it out later.
Where to go next
Common questions
What is the difference between a Session and a CDR?
A Session describes a charge that is happening: it is live, it updates, and it can change. A CDR describes a charge that has finished: it is final, it is what the two parties settle on, and it is what gets billed. A session that never becomes a CDR is one of the classic silent roaming failures.
What does a hub do?
It saves everyone from integrating with everyone. Without a hub, twenty CPOs and twenty eMSPs need four hundred integrations. With one, each party integrates once. The hub forwards messages and, depending on the setup, may also hold client information about who is reachable.
What is a token, exactly?
The credential that says a driver is allowed to charge, issued by their eMSP and presented at a CPO charger. It is not the Authorization header on the HTTP request, which is a separate thing entirely and is what the credentials handshake establishes between two servers.