Hub
How the hub works: from handshake to settlement
A partner connection establishes identity in four calls, opens scope with one acceptance decision and carries every session into a settlement window. The protocol call, the data direction and the evidence record behind each step are on this page.
Handshake
Four steps
The first three steps are the standard flow of the OCPI 2.2.1 credentials module and run in the sandbox first. The fourth step is not in the protocol: both sides accept the relationship in the portal, and only then does data flow.
- 01 OCPI
Discover versions
GET /ocpi/versions · Authorization: Token <TOKEN_A>
With the Token A issued at onboarding you read which OCPI versions the hub offers (2.2.1 and 2.3.0) and the version-details URL of each.
- 02 OCPI
Read module endpoints
GET /ocpi/2.2.1 · Authorization: Token <TOKEN_A>
The version details list every module endpoint with its role; tr-cdradditionals appears here for Türkiye partners.
- 03 OCPI
Exchange credentials
POST /ocpi/2.2.1/credentials · body: your credentials + TOKEN_B
You send your versions URL and Token B; the hub answers with its credentials and Token C. From here the hub calls you with Token B and you call the hub with Token C. Token A is retired.
- 04 portal
Accept relationships
hub portal · partner relationship · both sides accept
A completed handshake creates no data flow. Each partner relationship is accepted explicitly by both parties and points at a sharing set; only then do locations, tariffs, sessions and CDRs move.
Prerequisites for every role
- Versions endpoint (GET /ocpi/versions) and version details (GET /ocpi/2.2.1 or /ocpi/2.3.0)
- Credentials module, sender and receiver interfaces
- HTTPS with TLS 1.2 or newer; endpoints reachable from the hub without allow-listing
Network and behaviour
- Responses within 10 seconds (connection timeout)
- Idempotent handling of retried pushes
- A sandbox round before production: handshake, then each module against the charger simulator
Inspect evidence
OCPI 2.2.1 route table· Source code review
The OCPI adapter mounts controllers for credentials, locations, sessions, cdrs, tariffs, tokens, commands, chargingprofiles and hubclientinfo under the 2.2.1 version endpoint, with auth, idempotency, rate-limit and audit middleware.
Supports:That the nine 2.2.1 modules are implemented and routed in the hub.
Does not show:Interoperability with a specific partner’s implementation; that is established per partner in the sandbox and the acceptance checklist.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Fail-closed partner relationships· Source code review
No location, tariff, session, CDR or token flows unless an explicitly accepted, active partner relationship exists between the two parties; publish scope defaults to deny and changes are written to an audit ledger.
Supports:That a completed credentials handshake does not open data flow and that scope is an explicit, auditable decision.
Does not show:Contractual data-sharing permissions; those come from the signed agreement and DPA.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Partner sandbox· Source code review
Sandbox routes in the OCPI adapter and a mock partner and charger simulator let a partner complete the handshake and exercise each module against test data before onboarding.
Supports:That a test environment is part of onboarding.
Does not show:Self-service sign-up; sandbox credentials are issued after the application is reviewed.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Scope
Scope is a decision, not a default
Sharing sets
The CPO groups its locations into sharing sets; a relationship with an eMSP or NSP points at a set. Tariff visibility follows the same scope. A location that is in no set is invisible to every partner.
Relationships accepted by both sides
A completed handshake does not by itself open data flow. Unless an explicitly accepted, active partner relationship exists between the two parties, no location, tariff, session, CDR or token flows. The default is closed.
Audit ledger
Narrowing or widening scope is one operation and every change is written to the audit ledger: who, when, which set, which partner. A permission never written is a permission never granted.
Inspect evidence
Fail-closed partner relationships· Source code review
No location, tariff, session, CDR or token flows unless an explicitly accepted, active partner relationship exists between the two parties; publish scope defaults to deny and changes are written to an audit ledger.
Supports:That a completed credentials handshake does not open data flow and that scope is an explicit, auditable decision.
Does not show:Contractual data-sharing permissions; those come from the signed agreement and DPA.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Data flow
What flows, in which direction
From CPO to eMSP: locations, live status, tariffs, sessions and CDRs. From eMSP to CPO: tokens, real-time authorization and commands. Every row is routed along accepted relationships and verified against the route tables in the hub source.
| Module | Version | CPO | eMSP | What it carries | Status |
|---|---|---|---|---|---|
| credentials | 2.2.1 | Sender and receiver | Sender and receiver | Registration handshake and token lifecycle between a partner and the hub. | Offered |
| locations | 2.2.1 | Sender | Receiver | Locations, EVSEs and connectors with live status. | Offered |
| sessions | 2.2.1 | Sender | Receiver | Charging sessions in progress, from start to end. | Offered |
| cdrs | 2.2.1 | Sender | Receiver | Charge detail records: the billable record of a session. | Offered |
| tariffs | 2.2.1 | Sender | Receiver | Tariff definitions with price components and restrictions. | Offered |
| tokens | 2.2.1 | Receiver | Sender | Driver tokens (RFID, app) and real-time authorization. | Offered |
| commands | 2.2.1 | Receiver | Sender | Remote start, stop, reserve and unlock, relayed through the hub. | Offered |
| chargingprofiles | 2.2.1 | Receiver | Sender | Smart-charging profiles set and read through the hub. | Offered |
| hubclientinfo | 2.2.1 | Receiver | Receiver | The hub tells each partner which other parties are connected and in which role. | Offered |
| bookings | 2.3.0 | Receiver | Sender | Reservation of a charger for a time window, create and cancel. | Offered |
| parking | 2.3.0 | Sender | Receiver | Parking-bay information attached to locations. | Offered |
| payment | 2.3.0 | Sender | Receiver | Payment-session objects for ad-hoc (card) charging as defined in OCPI 2.3.0. | Offered |
| tokens (groups) | 2.3.0 | Receiver | Sender | Grouping of tokens for fleet and shared-account scenarios. | Offered |
| tr-cdr-additionals | TR ext. | Sender | Receiver | Türkiye profile: the CDR fields local regulation and tax rules need, carried as an OCPI extension. | Offered |
Scope text, verification date and evidence level for every module on OCPI modules →
Money
Session → CDR → settlement window
The session in progress is relayed with its status transitions; when it ends the CPO sends the CDR. The CDR is validated against tariff and session, taken in idempotently and enters the open settlement window for that partner pair. When the window closes, a hub-signed netting statement comes out.
Inspect evidence
OCPI 2.2.1 route table· Source code review
The OCPI adapter mounts controllers for credentials, locations, sessions, cdrs, tariffs, tokens, commands, chargingprofiles and hubclientinfo under the 2.2.1 version endpoint, with auth, idempotency, rate-limit and audit middleware.
Supports:That the nine 2.2.1 modules are implemented and routed in the hub.
Does not show:Interoperability with a specific partner’s implementation; that is established per partner in the sandbox and the acceptance checklist.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Settlement window state machine· Source code review
The clearing platform moves each settlement window through OPEN, GRACE_PERIOD, RECONCILING and CLOSED; late CDRs enter during the grace period and disputes surface before close.
Supports:That settlement periods, netting statements and payment obligations are produced by the platform.
Does not show:That money has moved between partners through the hub: settlement runs in dry-run until the financial go-live gate closes, and invoicing is fenced until then.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Hash-chained settlement ledger· Source code review
Ledger entries are chained by hash so a statement can be re-verified against its inputs; hub fees are booked as separate lines for each party and never netted against roaming amounts.
Supports:Tamper-evidence of the ledger and the “hub fee outside netting” rule.
Does not show:Fee rates or splits; those are in the participation agreement, not on this site.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Fail-closed partner relationships· Source code review
No location, tariff, session, CDR or token flows unless an explicitly accepted, active partner relationship exists between the two parties; publish scope defaults to deny and changes are written to an audit ledger.
Supports:That a completed credentials handshake does not open data flow and that scope is an explicit, auditable decision.
Does not show:Contractual data-sharing permissions; those come from the signed agreement and DPA.
Source: ChargeBridge hub source repository (private), reviewed on the date given · Verified4 October 2026
Settlement architecture: agreements, windows, statements, obligations· Document
Bilateral, versioned agreements define cycle, grace period, dispute window, fee allocation, payment automation and FX policy; windows move OPEN → GRACE_PERIOD → RECONCILING → CLOSED; statements move GENERATED → PUBLISHED → ACKNOWLEDGED and are hub-signed; obligations carry debtor, creditor, amount and due date.
Supports:The structure described on the settlement page.
Does not show:Any rate, amount or that real money has moved; payment automation beyond manual mode is configured per partner after the financial go-live gate.
Source: Hub repository, docs/architecture/settlement (domain model, state machines, cycle computation) · Verified4 October 2026
- 01sessions
Session relayed
Status transitions and charging periods, only along an accepted relationship.
- 02cdrs
CDR validated
Checked against tariff and session; a retried push is taken in idempotently.
- 03tr-cdradditionals
TR fields matched
A Türkiye-scope CDR meets its additional record on the CDR key.
- 04OPEN → CLOSED
Enters the window
Into the partner pair’s open window; a hub-signed statement at close.
Boundaries
What the hub does not do
Each sentence comes from the scope text of the module it refers to; stated so nobody assumes otherwise.
- 01
Does not compute charging schedules: it relays smart-charging profiles, it does not calculate them.
chargingprofiles → - 02
Is not a payment institution and does not process cardholder data; money moves between the parties’ own payment providers.
payment → - 03
Does not poll chargers: status updates are relayed as fresh as the CPO publishes them.
locations → - 04
Moves no data without an accepted relationship, even when the handshake is complete.
credentials →
Frequently asked questions
I completed the handshake; why does my partner not see my locations?
Because the handshake establishes identity, not scope. The relationship with that partner has to be accepted by both sides and point at a sharing set. A location that is in no set is invisible to every partner.
My partner is on a different OCPI version; what do I have to do?
Nothing. The hub negotiates the version with each partner separately and translates between 2.2.1 and 2.3.0 where objects differ. You choose your version and leave your partner’s to the hub.
When does a session enter settlement?
When the CPO sends the CDR. The CDR is validated against the tariff and the session and enters the open window for that partner pair. Late CDRs are taken in during the grace period; disputes surface before close. Details on the settlement page.
How it proceeds
- 01Apply with your role and versions endpoint
- 02Sign the participation agreement and DPA
- 03Handshake in the sandbox, then accept relationships