Guide on how to Send OCPI CDRs to Hubject Financial Services

This documentation will provide a guide on how you can begin sending OCPI CDRs for Financial Services.

Please check the PreRequisites section carefully to make sure you are ready to proceed with this step.

PreRequisites

Enable Financial Services:

Update the Invoice Settings (ALL Tabs) :

Pushing EVSEs via OICP

Process for pushing CDRs to Hubject:

Credentials Endpoints:

Version Endpoints:

CDR Endpoints:

Creating and Sending a CDR:

Response and Error Handling:

Limitations and restrictions:

PreRequisites

Enable Financial Services:

• Active Agreement with Hubject Financial Services: you must have an active agreement with Hubject to use Financial Services. This is required before sending any CDRs.
• Onboarding as an Intercharge CPO: you need to complete the onboarding process as an Intercharge CPO through Hubject's platform. This includes activating Financial Services on the Hubject Portal.

Update the Invoice Settings (ALL Tabs) :

All of the Settings tabs must be completed:

• Invoice Organization
• Payout accounts
• EVSE Assignment
• Invoice templates
• VAT Configuration
• CDR Rules (Optional)

Pushing EVSEs via OICP

You must push EVSEs via OICP to the Hubject system to push OCPI CDRs to HFS.

• List key data elements that must be included when pushing EVSEs, such as; EVSE ID, Location information, Status, Connector details, etc.
• Reference OICP eRoamingPushEvse Data documentation here.

Process for pushing CDRs to Hubject:

You will need to establish an initial authentication handshake, and then have a Hubject endpoint to push CDRs. This next section will describe the process.

Credentials Endpoints:

These endpoints are used for the initial authentication handshake between you and Hubject. You send a request with your credentials (token, unique identifiers) to authenticate your connection with Hubject's system.

Version Endpoints:

These endpoints are used to retrieve the supported OCPI versions available on the Hubject platform ( OCPI 2.2.1).

CDR Endpoints:

Description: These endpoints are used to retrieve the supported OCPI versions available on the Hubject platform ( OCPI 2.2.1). From the handshake, the URL will be provided for the specific environment.

Important Note: Only CDRs will be accepted via OCPI, any other requests will be rejected.

Creating and Sending a CDR:

1. CDR Creation: After authentication, you push the CDR which must include the structure in the CDR Request Body example below.
2. Limitations and Restrictions (More details in section at end of article)

• Total cost of charging session: total_cost
• Total reservation cost: total_reservation_cost
• Credit CDRs
• Home charging compensation
• Restriction on the total cost of each pricing component including VAT. The HFS system will only require the total cost for each pricing component to be populated with the net amount (excl_VAT). The incl_VAT value(s) will be ignored.

Fields required for Rating a CDR

1. Header

• Authorization token
• OCPI-to-party-id (EMP)
• OCPI-to-country-code (EMP)

2. Request Body

• ID
• Currency
• party_id (CPO)
• country_code
• Location (City, Address, Country, evse_id, postal_code)
• end_date_time
• start_date_time
•  total_energy

3. Pricing Component Total Net Cost (minimum 1 field must be sent)

• total_energy_cost (excl_VAT)
• total_time_cost (excl_VAT)
• total_fixed_cost (excl_VAT)
• total_parking_cost (excl_VAT)

Please note that duplicate CDRs will be accepted by the system but will be rejected when the Rating is processing.

POST Request: Send a POST request with the CDR object to the Hubject CDR endpoint. The request body must follow the OCPI 2.2.1 format.

Header example:

Validation and Processing:

1. Validation: The Hubject backend validates the CDR for:

• OCPI version (only 2.2.1 is supported).
• The ID field must be unique so that the Hubject BE can process the CDR in the Rating engine.

2. Processing: Once validated, Hubject processes the CDR:

• Stores it in the database.
• Initiates the Rating Engine for financial calculation.

Response and Error Handling:

• Response: Hubject responds to your backend with the status of the CDR submission, indicating whether it was successful or rejected.
• Error Handling: For rejected CDRs (due to version mismatch, non-CDR request, or missing data), an error response is returned.

Limitations and restrictions:

1. total_cost field restriction:

• We do not use OCPI 2.2.1’s total cost in our calculations even if you provide it in the CDR. We apply VAT to the price components individually and then calculate the total. Since different price components (e.g., parking, session, kWh, time) can have differing VAT values that need to be applied to them, we cannot just apply one VAT value to the total.
• The field name is total_cost, and as previously stated will not be included in the rating calculation even if provided in the CDR.
• The Rating engine will use the total_parking_cost, total_time_cost, total_energy_cost, and total_fixed_cost excluding VAT (excl_VAT) to rate the CDR.

2. total_reservation_cost:

• We do not use OCPI 2.2.1’s reservation price component in our calculations even if you provide it in the CDR. We consider four price components (parking, session, kWh, time) which we are also using for NGP. OCPI 2.2.1 knows a fifth one: reserveration. We do not use any reservation prices and ignore them in both the VAT and total price calculations.
• When the CDR is received, the HFS backend will ignore the total_reservation_cost field if it's present. This means it will not be taken into account for, either calculating the total cost of the charging session or displaying the cost to any internal systems or external interfaces.

Credit CDRs:

• The HFS system will reject any Credit CDRs received.

Home charging compensation:

• HFS does not support home_charging_compensation.

In the next section, you will learn how to deal with Invoices.