Skip to main content
Getz Hub

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.

Illustration

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 gatewayProjectionsCDR assuranceRouting engineTranslationDelivery queueAudit log

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 Co"
      },
      "party_id": "DMO",
      "country_code": "ZA"
    }
  ]
}
The standard OCPI 2.2.1 credentials object your back office sends in the handshake, with example values: your own token B, your versions URL and one entry per party you register. Hub answers with its own credentials object holding token C.
  • 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.

OCPP compared with OCPI, and which one Getz Hub uses
CapabilityOCPPOCPI
ConnectsCharger ↔ operator back office (CPMS)CPO ↔ hub ↔ eMSP (and hub ↔ hub)
Typical messagesBoot, status, start/stop transaction, meter values, firmwareLocations, tariffs, tokens, sessions, CDRs, commands
Used by Getz HubNoYes
Versions Hub servesNot applicable2.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.

OCPI modules Getz Hub serves in each version
Capability2.1.12.2.12.3.0
Locations (with EVSE and connector updates) YesYesYes
Tariffs YesYesYestax-inclusive model
Tokens and real-time authorisation YesYesYes
Sessions (incl. charging preferences from 2.2.1) YesYesYes
CDRs YesYesYes
Commands YesYesYes
Charging Profiles NoYesYes
Hub Client Info NoYesYes
Payments (card terminals) NoNoYes
Bookings NoNoYesbooking extension 1.1
Getz custom modules (optional) NoYesYes

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.

Which interface each party implements for each OCPI module when connected to Getz Hub
CapabilityCharge point operator (CPO)App (eMSP)What the module test does
LocationsSenderReceiverReads one object from the Sender
TariffsSenderReceiverReads one object from the Sender
Tokens (incl. real-time authorisation)ReceiverSenderReads one object from the Sender
SessionsSenderReceiverReads one object from the Sender
CDRsSenderReceiverReads one object from the Sender
CommandsReceiverSenderChecks it is advertised
Charging Profiles (2.2.1, 2.3.0)ReceiverSender, for its own sessionsChecks it is advertised
Hub Client Info (2.2.1, 2.3.0)ReceiverReceiverChecks it is advertised
Getz assurance notices (optional)ReceiverReceiverChecks it is advertised
Getz issue reports (optional)ReceiverSenderChecks 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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 Co"
      },
      "party_id": "DMO",
      "country_code": "ZA"
    }
  ]
}

# 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.
A synthetic OCPI 2.2.1 handshake with example values. Hub’s versions URL and your Token A come with your onboarding link; the angle-bracket values are placeholders. Every call carries the Authorization header, the versions call included.

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

  1. Step 1: Technical enquiry

    Tell us your OCPI role, version and modules. Our engineers reply by e-mail.

  2. Step 2: Onboarding link

    Register your parties (country code, party ID, role) and your public HTTPS versions URL.

  3. 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.

  4. Step 4: Tests and activation

    Connection and module tests pass before Hub staff activate you.

  5. Step 5: Agreements

    Accept roaming agreements per counterparty and module. Hub then backfills what you are owed, under visibility rules.

  6. 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.

Illustration

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.

Illustration

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.

Conditions
  1. No looppass
  2. Hop limitpass
  3. Sender activepass
  4. Agreement in forcepass
  5. Visibility allowspass
  6. Receiver supports the modulepass
  7. 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.

Illustration

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 gatewayProjectionsCDR assuranceRouting engineTranslationDelivery queueAudit log

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.

Illustration

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.

CPO back officeCPO on Getz NetworkForecourt networkGetz HubEV charging appFleet or brand appPeer roaming hubData customers

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.

Fields marked with an asterisk are required.

Hub translates between versions, so any of these can connect.