CDR Forwarding

⚠️
CDR Forwarding is only available when external clearing is chosen as a payment option. When Plugsurfing is the acting payment provider, the session is used as a record of the charging session.

Introduction

A CDR (Charging Detail Record) contains information about a completed charging session.

Overall, they contain the following information:

Who: user or charging key information
What: details on the charging session, including cost details
Where: location details

CDRs are sent to you using webhooks.

CDRs on Drive API

Requests will be sent as HTTP POST
The client should return a 200 response when the request is accepted
The client should return a 400 response when the request is not valid
The client should return a 403 response if authorization failed (see Configuration section below)
The client should return a 500 response in case it fails
We expect a response within 5 seconds. Any processing that can lead to response times higher than 5 seconds should be done asynchronously
New fields might be added to the schema without prior notice. Ensure that unknown fields are ignored and do not result in errors.

Retry logic

If the client doesn't respond with 200 or doesn't respond in time, the request will be retried: the CDR will be resent every night for 7 days (both on stage and prod environments).

Idempotency Expectation

For reliability, each webhook request includes a unique requestId that remains the same across all retry attempts. Therefore, your system should handle webhook events idempotently. This means:

Ensure your system processes each event only once even if you receive the same requestId multiple times due to retries.
Return a200 response as soon as you have successfully processed the event or stored it for later processing.

Example Scenario:

We send a requet to your endpoint, your system experiences a delay and does not return a response in time so we mark it as failed, but your system eventually manages to process it.
We will resend the same event again later, including the same requestId. At that point, we expect your system to recognize that this event has already been processed, so you should return a 200 response.

Handling retries idempotently helps avoid duplicate processing, ensuring consistent behavior across webhook interactions.

Configuration

Here is what we need to configure the CDR webhook:

URL to which we will send the CDRs
Authorization headers that will be passed in the request to the mentioned URL

Please contact your account manager with this data, so that we can set it up.

CDR Data

field	type	mandatory	notes
requestId	String	yes	requestId will not change upon retry
timestamp	String ISO date format	yes	example: 2022-12-12T12:55:21Z (always UTC)
payer	Object (Payer)	yes	see Payer section below
type	String / Enum	yes	possible value: SESSION
item	Object (Item)	yes	see Item section below

Payer Model

There are two possible Payer models depending on the integration:

if you create users using the Users endpoints, it will be the User Model.
if you create charging keys directly using the EMP endpoints, it will be the Charging Key Model.

User Model

field	type	mandatory	notes
type	String / Enum	yes	USER
id	String	yes	User id (provided during user creation)
chargingKey	Object	yes
chargingKey.visualNumber	String	no
chargingKey.uid	String	yes
chargingKey.contractId	String	yes
chargingKey.identificationType	String	yes	Possible values: `rfid`, `virtual` or `plug_and_charge`

See User model example for a sample JSON payload.

Charging Key Model

field	type	mandatory	notes
type	String / Enum	yes	CHARGING_KEY
uid	String	yes	key identifier of the charging key paying
visualNumber	String	no	absent for virtual keys
contractId	String	yes
identificationType	String	yes	Possible values: `rfid`, `virtual` or `plug_and_charge`

See Charging key model example for a sample JSON payload.

Item

Session

field	type	mandatory	notes
sessionId	String	yes
externalSessionId	String	no	session id received from the CPO
startTime	String ISO date format	yes	session startTime, always UTC
stopTime	String ISO date format	yes	session stopTime, always UTC
energyConsumedInWh	Long	yes	total energy consumed during the session, in Wh
totalParkingTimeInSeconds	Long	no	total parking time in seconds (if available): duration during which the car was not charging. To calculate the total charging time:`stopTime - startTime - totalParkingTimeInSeconds`
empCost	Object (Cost)	yes	end-customer cost (“Cost” object described below)
cpoClaimedCost	Object (Cost)	yes	cost received from the CPO
location	Object (Location)	yes
homeCharging	Object (HomeCharging)	no	Only present in the case of homeCharging

Location

field	type	mandatory	notes
id	String	yes	locationId
evseId	String	yes	e.g. IT_TSL_EMIL*0001
cpoId	String	yes	operator's external id (e.g. "DE*ABC")
address	String	yes
city	String	yes
postalCode	String	no
country	String	yes	ISO code (3 letters) of the country
powerType	String	yes	Possible values: AC,DC,AC_1_PHASE,AC_3_PHASE
private	Boolean	yes	whether the location is private or not
coordinates	Object(GeoCoordinates)	yes	the location's geo coordinates

GeoCoordinates

field	type	mandatory
latitude	Double	yes
longitude	Double	yes

Cost

field	type	mandatory	notes
totalCostMinorUnitsInclVat	Long	yes	total cost including VAT in minor units
totalCostMinorUnitsExclVat	Long	yes	total cost excluding VAT in minor units
currency	String	yes	Currency ISO code (3 letters)
costSegments	Array of CostSegment	yes

CostSegment

field	type	mandatory	notes
type	String / Enum	yes	Possible values: TIME, ENERGY, FLAT, CAPPED, PARKING_TIME
quantity	Double	yes	amount of unit objects
vatRate	Double	yes
pricePerUnitMinorUnitsInclVat	Long	yes	price per unit including VAT in minor units
segmentCostMinorUnitsExclVat	Long	yes	segment cost excluding VAT in minor units
segmentCostMinorUnitsInclVat	Long	yes	segment cost including VAT in minor units
unit	Object Unit	yes	`min` or `h` for TIME and PARKING_TIME, `Wh` or `kWh` for ENERGY, `session` for FLAT and CAPPED
from	String ISO date format	no*	`2022-12-12T12:55:21Z` always UTC * - mandatory for TIME, PARKING_TIME and ENERGY types
to	String ISO date format	no*	`2022-12-12T12:55:21Z` always UTC * - mandatory for TIME, PARKING_TIME and ENERGY types

Minor units

Minor units are the smallest subdivisions of each currency.
Here are the specifications for handling costs in various currencies:

Currency Code	Currency Name	Minor Unit	Example Cost
EUR	Euro	Cents	`100` cents → €1.00
SEK	Swedish Krona	Öre	`100` öre → 1 SEK
DKK	Danish Krone	Øre	`100` øre → 1 DKK
NOK	Norwegian Krone	Øre	`100` öre → 1 NOK
GBP	British Pound	Pence	`100` pence → £1.00

For more information, check minor units explanation.

HomeCharging

field	type	mandatory	notes
exemptVat	Boolean	yes	if true, this Home Charging session is exempt from VAT.

Unit

Describes what quantity in PriceElement refers to. For ENERGY, FLAT and CAPPED the Unit doesn’t change, but for TIME and PARKING_TIME it can differ.

field	type	mandatory	notes
type	String	yes	`session`, `kWh` or `min`
amount	number(integer)	yes	Always `1` for `session` and `kWh`. Might be different (1 / 15 / 60 or other) for minutes.

segmentPriceMinorUnitsInclVat contains the total price for this segment.
It’s calculated as quantity * pricePerUnitMinorUnitsInclVat.

In the example below, the user charged over one hour. With a step size of one hour (60 minutes), this results in a quantity of two ‘steps’. See Prices for more details on how step size works.

Example PriceElement

{
  "type": "TIME",
  "quantity": 2,
  "pricePerUnitMinorUnitsInclVat": 12600,
  "segmentPriceMinorUnitsInclVat": 25200,
  "unit": {
    "type": "min",
    "amount": 60
  },
  "from": "2023-06-13T12:55:21Z",
  "to": "2023-06-13T14:22:33Z"
}

In priceElements array the same type might show up multiple times (example: the price is 1€/min from 00:00 to 12:00 and 0.5€/min from 12:00 to 00:00, session lasted from 11:30 till 13:00. CDR will contain two TIME price elements).

Examples

User model example

{
  "requestId": "ej4KDd2kKdj",
  "timestamp": "2024-09-25T13:44:27Z",
  "payer": {
    "id": "FJEDK34KSJ9WD",
    "chargingKey": {
      "uid": "NR9348593",
      "contractId": "DE-8PS-C1Z3R5KZI-8",
      "visualNumber": "2340-1254-6543-5655",
      "identificationType": "rfid",
      "type": "CHARGING_KEY"
    },
    "type": "USER"
  },
  "type": "SESSION",
  "item": {
    "sessionId": "BpK64y1z1QA",
    "externalSessionId": "89111162",
    "startTime": "2024-09-25T13:17:57Z",
    "stopTime": "2024-09-25T13:44:18Z",
    "empCost": {
      "totalCostMinorUnitsInclVat": 26594,
      "totalCostMinorUnitsExclVat": 21275,
      "currency": "NOK",
      "costSegments": [
        {
          "type": "ENERGY",
          "quantity": 44.416,
          "pricePerUnitMinorUnitsInclVat": 599,
          "segmentCostMinorUnitsExclVat": 21275,
          "segmentCostMinorUnitsInclVat": 26594,
          "unit": {
            "type": "kWh",
            "amount": 1
          },
          "vatRate": 25.0,
          "from": "2024-09-25T13:17:57Z",
          "to": "2024-09-25T13:44:18Z"
        }
      ]
    },
    "cpoClaimedCost": {
      "totalCostMinorUnitsInclVat": 25275,
      "totalCostMinorUnitsExclVat": 20220,
      "currency": "NOK",
      "costSegments": [
        {
          "type": "FLAT",
          "quantity": 1.0,
          "pricePerUnitMinorUnitsInclVat": 25275,
          "segmentCostMinorUnitsExclVat": 20220,
          "segmentCostMinorUnitsInclVat": 25275,
          "unit": {
            "type": "session",
            "amount": 1
          },
          "vatRate": 25.0
        }
      ]
    },
    "energyConsumedInWh": 44416,
    "totalParkingTimeInSeconds": 0,
    "location": {
      "id": "1ih2FfSRddmxioJEmsyDcv9a2h+e83m568C3LyoNkIs=",
      "evseId": "NO*CHA*E2496*A",
      "cpoId": "NO*REC",
      "address": "Hardangervegen 697",
      "city": "Haukeland",
      "postalCode": "5268",
      "country": "NOR",
      "powerType": "DC",
      "private": false
    }
  }
}

Charging key model example

{
  "requestId": "fjei9pw0c",
  "timestamp": "2024-09-25T15:00:51Z",
  "payer": {
    "uid": "93042D4B7AD96280",
    "contractId": "GB-ALS-EF90LT13L-O",
    "visualNumber": "RFID34957483933",
    "identificationType": "rfid",
    "type": "CHARGING_KEY"
  },
  "type": "SESSION",
  "item": {
    "sessionId": "mezoOeWGdmpa",
    "externalSessionId": "GBKR40G9F92JDKS",
    "startTime": "2024-09-25T13:54:42Z",
    "stopTime": "2024-09-25T15:00:46Z",
    "empCost": {
      "totalCostMinorUnitsInclVat": 2380,
      "totalCostMinorUnitsExclVat": 1983,
      "currency": "GBP",
      "costSegments": [
        {
          "type": "ENERGY",
          "quantity": 30.131,
          "pricePerUnitMinorUnitsInclVat": 79,
          "segmentCostMinorUnitsExclVat": 1983,
          "segmentCostMinorUnitsInclVat": 2380,
          "unit": {
            "type": "kWh",
            "amount": 1
          },
          "vatRate": 20.0,
          "from": "2024-09-25T13:54:42Z",
          "to": "2024-09-25T15:00:41Z"
        }
      ]
    },
    "cpoClaimedCost": {
      "totalCostMinorUnitsInclVat": 2380,
      "totalCostMinorUnitsExclVat": 1984,
      "currency": "GBP",
      "costSegments": [
        {
          "type": "FLAT",
          "quantity": 1.0,
          "pricePerUnitMinorUnitsInclVat": 2380,
          "segmentCostMinorUnitsExclVat": 1984,
          "segmentCostMinorUnitsInclVat": 2380,
          "unit": {
            "type": "session",
            "amount": 1
          },
          "vatRate": 20.0
        }
      ]
    },
    "energyConsumedInWh": 30131,
    "totalParkingTimeInSeconds": 4,
    "location": {
      "id": "pdM9JM8qNtM3MX761qOGUlhljKJ/n6l1lfXMU2w0AivH5+3bUvPdMZyqaUV98hyfgaLCza2kwLfKutDcynXGpQ==",
      "evseId": "GB*OSP*EOSP20191*2",
      "cpoId": "GB*OSP",
      "address": "Weedon Bec",
      "city": "Northampton",
      "postalCode": "NN7 4QD",
      "country": "GBR",
      "powerType": "DC",
      "private": false
    }
  }
}

Security

If you want to be sure that CDRs you receive are emitted by Plugsurfing, please check the Verify HMAC Signatures guide.