Technical integration
Technical integration: connect to Getz Hub over OCPI
Hub is a standard OCPI hub. If your back office or app speaks OCPI 2.1.1, 2.2.1 or 2.3.0, that implementation is your integration: no SDK, no proprietary API. Start with the prerequisites and the module table below.
Inside Hub: from an incoming OCPI message to a delivery
What happens between a partner sending an object and another partner receiving it. Select a stage to read what it does.
OCPI gateway
Serves every OCPI module for 2.1.1, 2.2.1 and 2.3.0. Checks the partner’s token, that it speaks only for its own parties (OCPI-from), and the OCPI transport headers.
Use Tab to reach the diagram, then the arrow keys to move between parts.
Quickstart
Before you start
What your integration lead needs before asking for an onboarding link. Send them this section.
- Your OCPI role (CPO, eMSP, hub or payment terminal provider) and the version you run: 2.1.1, 2.2.1 or 2.3.0
- Each OCPI party you will register: country code, party ID and role
- A public HTTPS versions URL for your OCPI endpoint (no private addresses; Hub follows no redirects)
- A back office that can complete the credentials handshake: Token A opens it, you register Token B, Hub returns Token C
- The modules you plan to use, and their direction for your role (sender, receiver or both)
- A technical contact, and whoever will accept roaming agreements for you
- Time for the connection and module tests against your endpoint: Hub activates you only once they pass (see how test access works below)
Then check your modules against the module table by version, read the credentials handshake and the transport details, and request technical onboarding. Integrating the read-only data API instead? See the charging data API. A car brand working through a charging-service provider can leave this to the provider: automotive options.
{
"token": "<your token B>",
"url": "https://ocpi.example.invalid/ocpi/versions",
"roles": [
{
"role": "CPO",
"business_details": {
"name": "Demo Charging Zimbabwe"
},
"party_id": "DCZ",
"country_code": "ZW"
}
]
}- OCPI 2.1.1Still run by many back offices. Connect without upgrading first.
- OCPI 2.2.1Hub’s internal pivot: hub routing headers, Charging Profiles, Hub Client Info.
- OCPI 2.3.0Tax-inclusive tariffs, Payments for card terminals and Bookings.
OCPP and OCPI
Where Hub sits: OCPI, not OCPP
OCPP connects a charger to its operator’s back office. OCPI connects back offices, apps and hubs to each other. Hub speaks only OCPI; it never talks to chargers directly.
| Capability | OCPP | OCPI |
|---|---|---|
| Connects | Charger ↔ operator back office (CPMS) | CPO ↔ hub ↔ eMSP (and hub ↔ hub) |
| Typical messages | Boot, status, start/stop transaction, meter values, firmware | Locations, tariffs, tokens, sessions, CDRs, commands |
| Used by Getz Hub | No | Yes |
| Versions Hub serves | Not applicable | 2.1.1, 2.2.1 and 2.3.0 |
Supported modules
OCPI modules by version
Every module Hub serves, by OCPI version. Configuration modules (Versions, Credentials) exist in every version.
| Capability | 2.1.1 | 2.2.1 | 2.3.0 |
|---|---|---|---|
| Locations (with EVSE and connector updates) | Yes | Yes | Yes |
| Tariffs | Yes | Yes | Yestax-inclusive model |
| Tokens and real-time authorisation | Yes | Yes | Yes |
| Sessions (incl. charging preferences from 2.2.1) | Yes | Yes | Yes |
| CDRs | Yes | Yes | Yes |
| Commands | Yes | Yes | Yes |
| Charging Profiles | No | Yes | Yes |
| Hub Client Info | No | Yes | Yes |
| Payments (card terminals) | No | No | Yes |
| Bookings | No | No | Yesbooking extension 1.1 |
| Getz custom modules (optional) | No | Yes | Yes |
Module directions
Which side of each module you implement
For each module Hub routes: the OCPI interface a charge point operator and an app implement, and what the onboarding module test does with it.
| Capability | Charge point operator (CPO) | App (eMSP) | What the module test does |
|---|---|---|---|
| Locations | Sender | Receiver | Reads one object from the Sender |
| Tariffs | Sender | Receiver | Reads one object from the Sender |
| Tokens (incl. real-time authorisation) | Receiver | Sender | Reads one object from the Sender |
| Sessions | Sender | Receiver | Reads one object from the Sender |
| CDRs | Sender | Receiver | Reads one object from the Sender |
| Commands | Receiver | Sender | Checks it is advertised |
| Charging Profiles (2.2.1, 2.3.0) | Receiver | Sender, for its own sessions | Checks it is advertised |
| Hub Client Info (2.2.1, 2.3.0) | Receiver | Receiver | Checks it is advertised |
| Getz assurance notices (optional) | Receiver | Receiver | Checks it is advertised |
| Getz issue reports (optional) | Receiver | Sender | Checks it is advertised |
Peer hubs exchange the modules agreed for each party they speak for. The tests are described below.
Onboarding tests
What the tests check, and what a failure tells you
Connection test
- Credential: Hub holds the token you gave it (Token B).
- Versions: Hub reads your versions URL with that token (Base64 for 2.2.1 and 2.3.0, plain for 2.1.1) and picks the newest version you both speak.
- Version details: Hub reads that version’s endpoints and records your modules. Passing also ticks “Negotiate versions” and “Detect capabilities”.
Could not read <your versions URL>: HTTP 401, OCPI 2001 (…)- Hub’s call was refused: check that your platform accepts the token Hub was given, in the encoding of your version.
No OCPI version in common: the partner offers …- Offer 2.1.1, 2.2.1 or 2.3.0 in your versions list.
Could not read OCPI 2.2.1 details at …- Your version details must answer with OCPI 1000 and list your endpoints.
Module test
- For each module you send (Locations, Tariffs, Tokens, Sessions, CDRs): one read of the first page (offset=0, limit=1), with OCPI-from set to Hub and OCPI-to to your party. It must answer OCPI 1000 with a list, even an empty one.
- For each module you receive: Hub checks that it is advertised. Hub never writes test data into your platform.
sessions (Sender): Read failed: HTTP 404- The URL you advertise for the module does not answer a list request; fix the endpoint or stop advertising it.
The partner advertises no functional module.- Your version details list only Credentials: add the modules for your role.
Test access
How you get a test connection
The concrete steps from your first message to an active connection.
Step 1: Technical enquiry
Send the form on this page with your role, version and modules, and say if you want a test connection. An integration engineer replies by e-mail.
Step 2: Onboarding link
Hub staff send you a single-use link that expires after 24 hours to 30 days. On it you enter your organisation, technical contact, OCPI parties and your public HTTPS versions URL.
Step 3: Token A
Submitting shows Token A once, with Hub’s versions URL and the handshake instructions. Token A opens only the registration calls (versions, version details and credentials) and expires with the link.
Step 4: Handshake
Your platform POSTs its credentials (Token B) with Token A, as in the example; Hub answers with Token C. Your onboarding page shows each step as it completes.
Step 5: Tests
Hub staff run the connection and module tests against your endpoint and share each check’s result. Fix what fails and ask for a re-run.
Step 6: Activation and agreements
Hub staff activate you once both tests pass. Nothing is routed to or from you until an agreement for the module is in force.
# 1. Read Hub’s versions with Token A (Base64-encoded for 2.2.1 and 2.3.0; 2.1.1 sends it as-is).
# The versions endpoint needs the token like every other module; without it Hub refuses the call.
GET <Hub versions URL>
Authorization: Token <base64 of Token A>
# 2. Read the 2.2.1 endpoints, with the same token
GET <Hub versions URL>/2.2.1 (use the url Hub returns for 2.2.1)
Authorization: Token <base64 of Token A>
# 3. Register: send your credentials with Token A
POST <credentials endpoint from step 2>
Authorization: Token <base64 of Token A>
Content-Type: application/json
{
"token": "<your token B>",
"url": "https://ocpi.example.invalid/ocpi/versions",
"roles": [
{
"role": "CPO",
"business_details": {
"name": "Demo Charging Zimbabwe"
},
"party_id": "DCZ",
"country_code": "ZW"
}
]
}
# Hub now reads your versions URL with token B, then answers:
{
"data": {
"token": "<token C: use it for every call from now on>",
"url": "<Hub versions URL>",
"roles": [
{
"role": "HUB",
"country_code": "<Hub country code>",
"party_id": "<Hub party id>",
"business_details": {
"name": "Getz Hub"
}
}
]
},
"status_code": 1000,
"status_message": "Success",
"timestamp": "2026-11-21T09:00:03Z"
}
# Expected next: Token A is spent. A second POST is refused (405: use PUT to rotate).
# If Hub cannot read your versions URL it answers OCPI 3001 and nothing is registered.There is no self-serve sandbox. For your onboarding, Getz sets up a test connection with synthetic data on request: ask for it in the technical onboarding form below, with your OCPI role, version and modules.
Integration journey
From enquiry to live traffic
Step 1: Technical enquiry
Tell us your OCPI role, version and modules. Our engineers reply by e-mail.
Step 2: Onboarding link
Register your parties (country code, party ID, role) and your public HTTPS versions URL.
Step 3: Credentials handshake
Token A opens the versions, version details and credentials calls; your back office registers Token B; Hub returns Token C. Versions are negotiated and modules detected automatically.
Step 4: Tests and activation
Connection and module tests pass before Hub staff activate you.
Step 5: Agreements
Accept roaming agreements per counterparty and module. Hub then backfills what you are owed, under visibility rules.
Step 6: Live traffic
Watch deliveries, connection health and assurance results in the partner portal; retry failures yourself.
Credentials handshake
The OCPI integration flow
Step through the credentials handshake between your back office and Hub.
The OCPI credentials handshake with Hub
How a new partner’s back office and Hub exchange credentials and agree on a version. Step through it.
You receive a registration token (Token A)
After you submit your details from your onboarding link, Hub issues a Token A bound to your partner record. It is shown once, works only for the registration calls (versions, version details and credentials), and expires with the link.
Illustration of the OCPI 2.2.1 / 2.3.0 credentials module as Hub implements it. In 2.1.1 the token is sent unencoded; in 2.2 and later it is Base64-encoded.
Routing workflow
A routing decision, explained
Change the conditions and read the decision trace Hub records.
Why did this charge record go where it went?
A CPO sends a charge record for a driver of another app. Change the conditions and read the decision trace Hub records.
- No looppass
- Hop limitpass
- Sender activepass
- Agreement in forcepass
- Visibility allowspass
- Receiver supports the modulepass
- Receiver connectedpass
Routed to the app
loop check passed hop limit ok source active agreement in force visibility allows capability present destination connected routed
Illustration of the routing engine’s fixed order of checks. Each live decision keeps its trace and correlation id so it can be explained later.
Data exchange architecture
Inside Hub, from an incoming message to a delivery
Select a stage to read what it does.
Inside Hub: from an incoming OCPI message to a delivery
What happens between a partner sending an object and another partner receiving it. Select a stage to read what it does.
OCPI gateway
Serves every OCPI module for 2.1.1, 2.2.1 and 2.3.0. Checks the partner’s token, that it speaks only for its own parties (OCPI-from), and the OCPI transport headers.
Use Tab to reach the diagram, then the arrow keys to move between parts.
API capabilities
Transport details your engineers will ask about
Routing headers
OCPI-from and OCPI-to on every functional hop; Hub checks that a partner sends only as its own parties.
Request and correlation ids
A new X-Request-ID per hop and the same X-Correlation-ID end to end, echoed on responses.
A token on every call
/ocpi/versions and version details need Authorization: Token <token> like every other module: Token A during registration, Token C after. Base64-encoded from 2.2, unencoded in 2.1.1, as OCPI 2.1.1, 2.2.1 and 2.3.0 specify.
Idempotent ingest
Objects are ordered by last_updated; a duplicate is skipped and an older update never overwrites a newer one. CDRs are immutable.
PATCH or PUT
Partial updates go as PATCH to receivers that can apply them, otherwise as a full PUT; retries always go as PUT.
Asynchronous commands
Hub substitutes its own response URL, relays the result to the original requester once, and reports timeouts.
Hub error codes
Unknown receiver, offline receiver and similar hub conditions are answered with the OCPI 4xxx hub status codes.
Custom modules
Getz additions (sync reconciliation, assurance notices, issue reports) are declared OCPI custom modules in 2.2.1 and 2.3.0, advertised in version details. All are optional.
Public read API
Separate from OCPI roaming: scoped, rate-limited, read-only keys for public locations, availability and tariffs.
Example integration
Example: an operator and two apps on different versions
Select a participant to see how it connects.
How Getz Hub connects charge point operators and mobility apps
Operators publish once to Hub over OCPI. Hub applies agreements and visibility rules, then delivers to each participating app in the OCPI version it speaks.
Getz Hub: the neutral roaming layer
Hub checks every message against roaming agreements, visibility rules and each partner’s capabilities, records why it routed it, translates between OCPI versions and checks roamed charge records against the agreed tariff.
Use Tab to reach the diagram, then the arrow keys to move between parts.
Questions
Integration questions
Is there an SDK or a developer portal?
No. Hub is integrated through standard OCPI, so your existing OCPI implementation is what connects. A written note on the optional Getz custom modules is shared during technical onboarding.
Is there a test environment?
There is no self-serve sandbox. For your onboarding, Getz sets up a test connection with synthetic data on request: ask for it in the technical onboarding form. Your own connection is also tested before it carries traffic: after the handshake, Hub staff run the connection and module tests against your endpoint, and nothing is routed until you are activated and an agreement is in force. How test access works.
Can we connect from a private network address?
No. Partner endpoints must be public HTTPS addresses. Hub does not follow redirects to partner URLs.
What has to pass before we go live?
The connection test and the module tests for the modules you declared, run during onboarding; Hub staff activate you only once they pass. Your onboarding page shows each step, and the tests section lists every check and what a failure means.
Who do we contact when something fails in production?
Start in your partner portal: failed deliveries show their reason and you can retry them yourself. For anything on Hub’s side, e-mail support@getzcharging.com with the X-Correlation-ID of the message concerned. Security issues go to the same address, with “Security report” in the subject.
We are a car brand. Do we have to run OCPI ourselves?
No. A charging-service provider can run the eMSP connection for your owner app. Automotive options.
We are integrating the read-only data API, not roaming.
This page is about OCPI roaming. The charging data API and data feeds pages describe the data path, with a sample feed payload.
We serve many operators from one back office. How do we connect?
Connect once and list every party you serve in your credentials roles. Each party gets its own agreements; Hub reconciles the list on every credentials update.
Technical onboarding
Request technical onboarding
Talk to our integration engineers
Tell us your OCPI role, version and the modules you plan to use. An engineer replies by e-mail.
We will prepare an onboarding link and share the specification note for the optional Getz custom modules.