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:

1. Getting Started → Onboarding → Authentication
2. Routing → Hub Receiver Identity
3. Tokens → Commands
4. Locations → Tariffs → Sessions → CDRs
5. 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)

Remote start

Remote charging starts with a command (not Tokens authorize):

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 charger-initiated RFID/Autocharge, implement Tokens SENDER POST …/tokens/{uid}/authorize so Hub can forward CPO requests. See Tokens (eMSP).

For STOP_SESSION, include session_id instead of location fields.

Stuck / orphan sessions (soft-close UX)

Hub may detect stale ACTIVE sessions and pull the CPO to heal its store, but Hub does not push provisional session status to you. Implement local soft-close:

• After STOP_SESSION silence past data.timeout, fail the command UX locally and retry stop if needed
• If meter/last_updated is stale, or EVSE becomes AVAILABLE while your session is still charging, move the driver UX to “finalizing / bill pending” without inventing a final amount
• Prefer catch-up via GET /sessions and GET /cdrs rather than waiting only on push
• Suggested starting timers: stop grace ~5 minutes; DC meter stale ~10 minutes; AC ~30 minutes; hard max session ~24 hours (tune for your product)

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:

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
• [ ] Optional OCPI-from-* / OCPI-to-* on commands (Open Routing via location_id when to omitted)
• [ ] 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

Related docs

• eMSP Migration
• Hub Receiver Identity (eMSP)
• Session Lifecycle
• Async Delivery
• eMSP Certification
• API Reference