Guides
Start typing to search…

Sessions

Get charging session history, start and stop remote charging sessions and manage session payments.

The Sessions API allows you to:

  • Start and stop remote charging sessions
  • View charging session history
  • Get session details and receipts
  • Retry failed payments

Remote charging

To start a charging session remotely, use the endpoints described below.

After starting or stopping a session, you should listen to Session Events to get updates about:

  • session started
  • session failed to start
  • session stopped
  • session finished

A session can be started remotely (via the API) but stopped locally by the user, for example from the car itself or by plugging out the charging cable.
That means that you might receive events such as SESSION_STOPPED or SESSION_COMPLETED without calling the Drive API.

Remarks

  • The order of events doesn't always follow the sequence outlined in the Statuses section. Events can occur in any order or be skipped entirely. Always consider the most recent update for the accurate status of the session.
  • Only chargers with REMOTE_START_STOP_CAPABLE capability can be started and stopped remotely.
  • Do not limit the possibility to start charging only to chargers in the AVAILABLE status. There can be a delay between status updates, so a charger might be available even if it still shows "OCCUPIED".
  • A session might stay in a certain state (like WAITING_TO_START or STOP_FAILED) for a long time. Ensure your product handles this appropriately and doesn't block the user from starting a session again in such cases.
  • After starting a session, all subsequent tries within the next 60 seconds on the same connector are blocked to avoid spamming the CPO with requests. Consider this when designing your integration.
  • It is possible to have two or more ongoing sessions simultaneously.
  • Once a session is completed and priced, a CDR (Charge Detail Record) is sent.

Possible problems

Connections with chargers are not always reliable and stable. Therefore, some errors may occur when using remote start/stop:

  • Session Starting Delays:

    • Starting a session can take some time. Allow up to two minutes for the session to transition from WAITING_TO_START to STARTED. Some chargers only unlock the cable after starting, so it will stay in WAITING_TO_START until the user connects the cable to their car.
    • If a charger can't start a session due to connectivity problems or issues with connecting to the car, wait at least one minute before allowing the user to attempt starting a session again.
    • If a session stays in WAITING_TO_START for more than two minutes, consider it failed and allow starting another one.

  • Session Failures:

    • If the charger didn't receive the stop request and charging continues while the session is marked as failed, the user should be able to send a STOP request again.
    • If a session stays in STOP_FAILED status for a few minutes, the user should still be able to start another session.
    • If a charger received a stop request but a timeout occurred and the session is marked as STOP_FAILED, another event about the session being stopped or completed should follow.

  • Mixed Session Outcomes:

    • It is possible to receive a SESSION_FAILED event followed by a SESSION_COMPLETE event and have a successful charging session. This can happen if there are connection issues between the charging point operator (CPO) and the charger, but the charger was still able to charge.
    • If a session doesn't stop correctly after a few tries, allow the user to abandon the session so that it is possible to start another one.

Start remote session

API Reference

Start a remote charging session for a given user on a given connector id. The response from this endpoint will always include a session id regardless if the start was successful or not (all session attempts are stored).
You should store that session id to be able to check its status, stop charging, etc.

Stop remote session

API Reference

Stop a remote charging session given its session id. Only sessions started remotely can be remotely stopped.
Remotely started sessions have the chargingKeyType field set to virtual.

Calling this endpoint with a session id pointing to an already stopped session will not cause any harm, a 200 - OK response will be returned again.

Session statuses

The status Enum should be designed to accept unknown values. In case a new status is introduced, handle these unknown values as FAILED.

  • CREATED – transitive state that indicates that Plugsurfing created the session. It remains for a very short time
  • WAITING_TO_START – indicates that Plugsurfing asked the CPO to start a remote session (only for Remote Charging)
  • STARTED – indicates that the session is ongoing
  • WAITING_TO_STOP – indicates that Plugsurfing asked the CPO to stop a remote session (only for Remote Charging)
  • STOP_FAILED – indicates that stopping the remote session failed (only for Remote Charging). A new stop request can be retried.
  • STOPPED – indicates that the session has ended, but the CDR was not yet received
  • COMPLETE – indicates that the session is fully completed and priced. Use the balanceStatus and the balanceAmountMinor to assess if the payment is currently successful or not.
  • FAILED – indicates that the session couldn't be started
  • REFUNDED – indicates that the session payment was refunded to the user
  • UNKNOWN – indicates an unrecognized status. It should be treated the same as FAILED
Session statuses flow

Session statuses flow

Get Session history

API Reference

The session history API allows you to:

  • View all charging sessions of a given user
  • Filter by charging key, date range, and status
  • Get session details like energy consumed, duration and cost

Get session by id

API Reference

Retrieve a session details by its id. The response will indicate whether the session is starting, started, failed, or complete.

When a session is complete, you will also have an additional field called balanceStatus which will give you the payment state as one of 4 options (PROCESSING, PAID, DEBT, REFUND).

Example of session in STARTED state:

{
  "sessionStatus": "STARTED",
  "charger": {
    "chargingStationName": "ZzZ 220218114136937169",
    "connectorLabel": "1",
    "evseId": "NO*XXX*EZzZ220218114136937169*1"
  },
  "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
  "duration": "PT21.379S",
  "receiptAvailable": false,
  "sessionId": "LWO89J3mDJr",
  "site": "ZzZ 220218114135485264",
  "startTime": "2022-06-07T06:49:59.811Z"
}

Example of session in COMPLETED state:

{
  "sessionStatus": "COMPLETE",
  "balanceStatus": "PAID",
  "charger": {
    "chargingStationName": "ZzZ 220218114136937169",
    "connectorLabel": "1",
    "evseId": "NO*XXX*EZzZ220218114136937169*1"
  },
  "connectorId": "abcJd/vR5fvzBa0X/gxaXA==",
  "duration": "PT15M",
  "energy": {
    "unit": "WH",
    "value": 1840
  },
  "price": {
    "currencyCode": "NOK",
    "minorExclVat": 0,
    "minorInclVat": 0,
    "vat": "25"
  },
  "receiptAvailable": false,
  "sessionId": "LWO89J3mDJr",
  "site": "ZzZ 220218114135485264",
  "startTime": "2022-02-18T10:41:39.148Z"
}

Get a session receipt by sessionId

API Reference

Retrieve a session receipt signed url by using the sessionId.

Testing remote charging

To test remote charging, you should start charging sessions on specific connectors in our the stage environment. Here are the steps required to test remote charging:

  1. Find a charger via geosearch
  2. Select an available charger and get its connector id
  3. Start the session
  4. Wait a desired amount of time
  5. Stop the session

Here are details on how to test a successful session and how to simulate error scenarios.

Successful session

Firstly, search for available locations around the following coordinates with the Geosearch radius endpoint:

Latitude: 52.290056
Longitude: 20.907028
Distance: 500
curl --request POST \
     --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.290056&longitude=20.907028&distance=500&limit=300&aggregate=false' \
     --header 'X-API-Key: YourApiKey' \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "filters": {
    "locationStatuses": [
      "AVAILABLE"
    ]
  }
}
'

Pick any connector with the AVAILABLE status and start a session:

curl -X POST --location "https://drive-api-stage.plugsurfing.com/drive/v1/users/<userId>/sessions/start" \
    -H "x-api-key: <apiKey>" \
    -H "Content-Type: application/json" \
    -d "{
          \"connectorId\": \"RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsawwqypdT1Qwa3ck8cchZpEH2JGytmok239REYlPWleVQ==\"
        }"

A session id will be returned. You can use this session id in the Get session by id endpoint. That should indicate that the session in "STARTED" state:

{
  "sessionStatus": "STARTED",
  "charger": {
    "chargingStationName": "Charge at the castle",
    "city": "Stockholm",
    "evseId": "SE*REM*E1000",
    "streetName": "Kungliga slottet"
  },
  "connectorId": "+YePNZexUkx8U9fCUoBEmu8EVhBUn1TWdxjd5Ky1ly1Tm3r2MApUUkDIzO4IqizV3l4XTQ87QmotRFvUW1SCWA==",
  "duration": "PT12.333S",
  "receiptAvailable": false,
  "sessionId": "NbmNQa80MwR",
  "site": "Charge at the castle",
  "startTime": "2023-02-24T13:14:14Z"
}

Error case

There is one location designated for simulating errors, it is located at:

Latitude: 52.334242
Longitude: 20.899305

Below are 4 specific error scenarios which can be tested. Each are assigned on a different charger (EVSE):

  • Waiting to start hanging: DE*DRV*E6mayTt
  • Stop ignored (rejected): DE*DRV*E4JanRe
  • Start fails: DE*DRV*E9svnVs
  • Stop fails: DE*DRV*E8vsnVn

Below the error scenarios are described in more detail:

1. Waiting to start hanging:
  1. Select any connector id from evse_id DE*DRV*E6mayTt and initiate a charging session
  2. Obtain the session id from the response and get session details using session API request
  3. Status of charging should be WAITING_TO_START
Example request
 curl -X 'POST' \
  'https://drive-api-stage.plugsurfing.com/drive/v1/users/<userId>/sessions/start' \
  -H 'X-API-Key: <apiKey>' \
  -d '{
  "connectorId": "RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsYcqfRqeQ1Z/hmFFk/Lu+ZjAmz+8p9htX8Wmh0rzSdKGQ=="
}'
2. Stop ignored (rejected):
  1. Select any connector id from evse_id DE*DRV*E4JanRe and initiate a charging session
  2. Obtain the session id from the response and trigger a stop session
  3. Enter the same session id in the Get session by ID endpoint request and check the status
  4. Status of charging should still be STARTED as stop request is ignored
3. Start fails:
  1. Select any connector id from evse_id DE*DRV*E9svnVs and initiate a charging session
  2. Obtain the session id from the response and get session details using session API request
  3. Status of charging should be FAILED as starting a charging session failed
4. Stop fails:
  1. Select any connector id from evse_id DE*DRV*E8vsnVn and initiate a charging session
  2. Obtain the session id from the response and trigger a stop session
  3. Enter the same session id in get session API request and check the status
  4. Status of charging should be STOP_FAILED as stop request fails

Testing local charging

Local charging cannot be tested in the staging environment. To perform local charging tests, you need to use physical charging keys on actual chargers.

Updated 24 days ago