eMSP Integration Guide

This guide covers what eMSPs must call on Hub and implement as receivers on their platform.

Your reading path

Follow this order for a complete eMSP integration:

Getting Started → Onboarding → Authentication
Routing → Hub Receiver Identity
Tokens → Commands
Locations → Tariffs → Sessions → CDRs
Pagination → Session Lifecycle → Async Delivery → Connection Health → Certification → Support

Migrating from peer-to-peer OCPI? See eMSP migration.

Your responsibilities

As an eMSP, you offer drivers access to charging networks. The Hub routes your authorization and commands to CPOs, and delivers session/CDR updates asynchronously.

Call Hub (authenticated)

Module	Methods	Purpose
Tokens	`PUT .../authorize`	Realtime authorization before charging
Commands	`POST .../commands/{command}`	Start, stop, reserve, cancel
Locations	`GET`	Discover charge points (routing-filtered)
Tariffs	`GET`	Retrieve pricing (routing-filtered)

Token authorization

Before a driver starts charging, authorize their token:

PUT /ocpi/2.2.1/tokens/{country_code}/{party_id}/{token_uid}/authorize

The Hub forwards this to the owning CPO in realtime. Rate limit: 100 requests/minute per party.

Remote start

Send a start command with response_url for async results:

POST /ocpi/2.2.1/commands/START_SESSION
Content-Type: application/json

{
  "response_url": "https://your-platform.com/ocpi/callbacks/commands",
  "token": { "uid": "...", "type": "RFID", "contract_id": "..." },
  "location_id": "LOC001",
  "evse_uid": "EVSE001",
  "connector_id": "1"
}

For STOP_SESSION, include session_id instead of location fields.

Pull locations and tariffs (backfill)

GET /ocpi/2.2.1/locations?offset=0&limit=50
GET /ocpi/2.2.1/tariffs?offset=0&limit=50

Results are filtered by routing rules. See Pagination.

Use pull for initial catalog sync and recovery. For real-time EVSE status, rely on async push (below).

Receive from Hub (on your platform)

You must implement these receiver endpoints:

Module	Methods	Purpose
Locations	`PUT`, `PATCH` at location / EVSE / connector paths	Async catalog updates from Hub
Tariffs	`PUT .../tariffs/{cc}/{pid}/{id}`	Async tariff updates from Hub
Sessions	`PUT`, `PATCH .../sessions/{cc}/{pid}/{id}`	Async session updates from Hub
CDRs	`POST /ocpi/2.2.1/cdrs`	Async CDR delivery from Hub

Push + pull

Catalog, sessions, and CDRs are pushed to your RECEIVER endpoints when CPOs update the Hub. GET on the Hub remains available for backfill and incremental sync via date_from (/locations, /tariffs, /sessions, /cdrs).

Provide your receiver URLs during onboarding.

Receiver validation (Hub mode)

When Hub forwards catalog and session updates to your platform:

Authenticate with your Hub token (from credentials exchange)
Accept {country_code}/{party_id} in URL paths for owning CPOs, not Hub (CIH) and not your eMSP party
Do not require path parties to appear in credentials roles
Build an allow-list from GET /hubclientinfo intersected with your routing rules

Rejecting pushes because the path party is unknown to your credentials exchange causes errors such as Invalid CountryCode & PartyId combination. See Hub Receiver Identity (eMSP).

Command async results

Command results arrive at your response_url (forwarded by Hub from CPO callback). Handle ACCEPTED, REJECTED, TIMEOUT, and session-related result types per OCPI 2.2.1.

Integration checklist

[ ] Credentials exchange complete
[ ] Routing rules enabled for target CPOs
[ ] Token authorization flow tested
[ ] START_SESSION / STOP_SESSION tested end-to-end
[ ] Session receiver endpoint live
[ ] CDR receiver endpoint live
[ ] Location receiver endpoints live (PUT/PATCH)
[ ] Tariff receiver endpoint live (PUT)
[ ] Location/tariff/session/CDR pull integrated (backfill)
[ ] Location/tariff/session receivers accept CPO {country_code}/{party_id} in URL path
[ ] Receiver validation uses HubClientInfo + routing allow-list (not credentials roles only)
[ ] Test inbound location PATCH from Hub with a routed CPO party key
[ ] GET /ocpi/versions reachable for health checks