EMSP troubleshooting: a roaming badge does not work

"I enabled the badge, but it doesn't work on the charger." This page helps you find the cause when one of your badges, used in roaming on a partner operator's (CPO) charger, does not start the charge.

It covers both connection modes:

through a roaming platform (roaming hub) such as Gireve (see Gireve EMSP connection) or Hubject;
through a direct OCPI peer-to-peer connection with the CPO (see Peer-to-peer connection).

The key principle

When your customer presents their badge on a partner's charger, Chargekeeper is not the one controlling the charger: the CPO's management system is. To find out whether the badge is allowed to charge, the CPO sends an OCPI authorization request (Authorize) to your platform. Chargekeeper answers "allowed" or "refused".

If this request never reaches us, Chargekeeper cannot authorize anything, whatever the badge, user or pricing settings.

A long chain, with Chargekeeper as the last link

For the authorization request to reach us through a roaming platform, every link must work:

the partner's charger is connected and communicates with its own management system, which is not Chargekeeper;
the CPO's management system communicates correctly over OCPI with the roaming platform (Gireve, Hubject…);
the roaming platform forwards the request to Chargekeeper.

In peer-to-peer, the chain is shorter: the CPO's management system calls us directly, with no intermediary.

The path of an authorization request: badge, partner's charger, CPO's management system, roaming platform, then Chargekeeper as EMSP, which answers allowed or refused

The diagnosis therefore always starts with the same question:

Did the authorization request for this badge reach us at the time of the attempt?

No → the problem lies upstream of Chargekeeper. See Step 1.
Yes, and it was refused → the problem comes from the settings in Chargekeeper. See Step 2.

Diagnostic tree: if the request does not appear in the logs, the problem is upstream; if it does, Chargekeeper refused and the settings must be fixed

Step 1: does the authorization request reach us?

Write down the exact time of the attempt, the badge identifier and the charger used (operator, address, EVSE identifier if possible).

What you can check in Chargekeeper

Open the Logs and search for the badge identifier around the time of the attempt. Roaming authorization requests are logged under the OcpiEmspAuthorizeToken action.

Every refusal is logged. A refusal looks like this:

Roaming authorization refused for Tag ID '<badge>' on Charging Station '<charger>': <reason>

or appears as an error on the same action (unknown badge, unknown charger, no applicable pricing…). If you find such a line, the request did arrive: go to Step 2.

If you find no line for this badge at the time of the attempt, and no session appears in Sessions › Sessions on partner CPO chargers, the request most likely never reached Chargekeeper.

An accepted authorization does not always produce a visible line in the logs. The absence of a line alone does not prove that nothing arrived: cross-check it with the list of sessions on partner chargers.

First step: ask your roaming platform

Through a roaming platform, it is rarely possible to reach the charger's operator directly. Your first point of contact is therefore your roaming platform (Gireve, Hubject…). Open a ticket with them (Mantis for Gireve) giving the time of the attempt, the badge identifier and the charger, and ask them to confirm:

that their link to your Chargekeeper platform works in the downstream direction, meaning they do forward authorization requests to us;
that they did receive an authorization request from the CPO for this badge, and what they did with it;
that your badges are known to the platform: after the import into Chargekeeper, Gireve has to integrate them on its side.

Are your badges known to the partner?

Chargekeeper can send the list of your badges to your CPO partners, both in peer-to-peer and through a roaming platform:

automatically, when the roaming connection is registered and its automatic update process is enabled;
on demand, with the Push Tokens action on the roaming connection.

Each badge is sent with its status: it is only declared valid if it is active, roaming is enabled on it and its user is active. Pushes are logged under the OcpiEmspUpdateTokens action.

This list lets the CPO recognize your badges, but does not exempt it from asking us: Chargekeeper sends its badges requesting a real-time authorization for every charge (OCPI whitelist NEVER). Every charge therefore still goes through an authorization request to Chargekeeper, and the principle of this page still holds.

If the partner does not recognize a badge, run Push Tokens again, then ask them to confirm they received it.

Second check: a roaming agreement signed with this CPO

A working technical connection is not enough. On a roaming platform, your customers can only charge on a CPO's chargers if a roaming agreement has been signed between you, as EMSP, and that specific CPO: the one operating the charger where the attempt took place. Depending on the platform, this agreement is called an offer, a contract, an agreement or an approval. At Gireve, these are the offers signed on the Connect Place.

So check, on the roaming platform or with them:

which operator (CPO) runs the charger used for the attempt;
that an agreement is signed and in force between you and this operator;
that this agreement does cover the charger used for the attempt.

A badge that works with one CPO but not with another is very often the sign of a missing agreement with the second one.

If nothing arrives anyway

If the roaming platform received no request from the CPO, the problem lies between the charger, its management system and the platform: it is up to the roaming platform to escalate it to the operator.

In peer-to-peer

The CPO is your direct point of contact:

check that the connection is active with Test Connection in the roaming connection settings;
ask the CPO to confirm that its management system did send an authorization request to your platform, and what answer it got;
check with them that your badges are in their list.

Step 2: the request arrived but was refused

If an authorization request appears in the logs, that is good news: the whole communication chain works, from the partner's charger to Chargekeeper, through its management system and the roaming platform. What remains is to understand why Chargekeeper refused.

The three checks to do first

In the vast majority of cases, the refusal comes from one of these three points:

Does the badge have the roaming option enabled? In the badge form, the Roaming enabled (eMSP) option must be checked, and the badge must be active.
Is the user linked to the badge allowed to charge? The badge must be linked to a user whose account is active, and an EMSP pricing must allow this badge or this user at the time of the attempt.
Are the user's charges paid for? Either by a valid personal payment method, or by a B2B contract of their company. See below.

Personal payment method or B2B contract

When charge billing is enabled and the charge is not free for this user, Chargekeeper checks that the charge will be paid for. This does not necessarily go through the user's card: if their company is covered by a B2B contract, that contract pays for the charges.

"Monthly payment (bank transfer)" contract: no payment method is required from the user. The company is invoiced every month.
"Per charge payment (credit card)" contract: the card checked is the one of the company's billing user, not the user's.
No applicable B2B contract: the user must have their own valid payment method. A missing or expired card is enough for the charge to be refused.

For a B2B contract to cover a roaming charge, check that:

the user is linked to the customer company of the contract;
the contract is between this company and one of your operating companies (CPO): the partner's charger does not belong to your companies, so your own company acts as the supplier;
the contract includes charge billing;
the contract is in force on the date of the charge.

The logs show which contract was used for the charge, under the BillingTransaction action: User's company (…) has a Monthly (no credit card required) contract …, … has a PerRecharge (credit card required) contract … or … has no contract ….

All refusal reasons

The log line gives the exact reason for the refusal. Here are all possible reasons and what to fix.

Chargekeeper runs its checks in the order below; the first one that fails gives the reason for the refusal.

Chargekeeper's six checks in order: known charger, badge, user, restrictions, EMSP pricing, payment

Reason in the logs	What it means	What to do
`Unknown Tag ID '…'`	The badge does not exist in Chargekeeper.	Check the exact badge identifier (case, zeros, format) and that it was created in Badges.
`Charging Station with EVSE ID '…' and Location ID '…' does not exist`	The partner's charger is not known to Chargekeeper.	Retrieve the partner's sites: in the roaming connection settings, run Pull Locations, then try again.
`Roaming is not enabled for the tag '…'`	Roaming is not enabled on this badge.	In the badge form, check Roaming enabled (eMSP).
`Tag '…' is not active.`	The badge is deactivated.	Activate the badge in its form.
`Tag '…' is not owned by the EMSP`	The badge is not one of your badges, it is a partner's badge.	A partner badge cannot be authorized as EMSP: use one of your own badges.
`Unknown User for OCPI Token ID '…'`	The badge is not linked to any user.	Link the badge to a user.
`user account status is '…'`	The user's account is not active (pending, inactive, blocked…).	Activate the user's account. If it is blocked, first check why (unpaid invoice, manual block).
`charge point is located in blocked country '…'`	The roaming connection forbids the country where the charger is located.	Check the blocked countries in the connection settings. Depending on these settings, the attempt may also have blocked the user's account.
`… roaming session(s) already in progress, limit is 1`	The user already has a roaming session in progress.	Only one roaming session is allowed at a time per user. A session left open (the partner never sent its end) blocks the next ones: check Sessions on partner CPO chargers and contact the partner to close it.
`… no pricing applies at this time!`	No EMSP pricing covers this badge on this charger at this time.	Create or fix an EMSP pricing applicable to this badge or this user. Also check its validity dates and its day and time ranges.
`no valid payment method`	Neither the user nor a B2B contract of their company covers the payment.	First check whether the user should be covered by a B2B contract (see above). Otherwise, they must register a valid payment method. With "Per charge payment (credit card)", it is the card of the company's billing user that must be valid.

Summary

Before a roaming charge can be accepted:

the CPO's authorization request must reach Chargekeeper: charger connected to its management system, management system connected to the roaming platform, platform connected to Chargekeeper (or active peer-to-peer connection);
your badges must be known to the partner (badge push);
a roaming agreement must be signed between you and the CPO operating the charger (offer, contract, agreement or approval depending on the platform);
the partner's charger must be known to Chargekeeper (sites retrieved);
the badge must exist, be active and have roaming enabled;
the badge must be linked to an active user;
the charger's country must not be blocked on the connection;
the user must not already have a roaming session in progress;
an EMSP pricing must apply at that time;
the charge must be paid for: by a valid payment method of the user, or by a B2B contract of their company.

If everything is in order and the refusal persists, contact our support with the time of the attempt, the badge identifier, the charger, and the result of step 1.