Guides

Charging Keys

The Charging Keys API enables the management of physical and virtual charging keys associated with users for EV charging authentication. This API allows you to:

  • Assign and activate a charging key for a user.
  • Disable or re-enable charging keys in case of loss or deactivation needs.
  • Retrieve a list of all activated charging keys for a specific user.

Charging key types

Physical charging key (RFID)

These are tangible cards or tags equipped with an RFID chip used to authenticate at charging stations.

  • The identifier flashed on the chip is called uid. The uid is required in the reservation flow (which is unique to that type of key).
  • For physical charging keys, the uid is also the keyId.
  • The identifier printed on the card/tag is called visualNumber in the reservation flow, and referenceId later on.
  • When reserving a charging key, you can set the type field to either TAG or CARD. This has no practical implications.

Virtual charging keys

When creating a user, a charging key is automatically created and assigned to that user: it is what we call a virtual charging key.

  • The keyId of a virtual charging key is automatically generated when the key is created.
  • Virtual charging keys do not have referenceId.
  • They should not be displayed to users. A good practice is to filter them out by using the type field.

Reservation and Activation Flow

The Charging Key API is specific for Physical charging keys and uses a two-step process: Reservation and Activation.

Charging Keys Reservation - POST

  • Pre-registers a physical charging key (RFID) in the system by pairing the chip's unique identifier (uid) with a human-readable identifier (visualNumber).
  • This step prepares the key for future assignment, but the key is not yet usable.
  • The uid should be in hexadecimal, little endian format.

Endpoint: /v1/charging-keys/reservations

API Reference

Request body:

  • uid (string, required) - physical chip id, encoding is hexadecimal, little-endian
  • visualNumber (string, required) - human-readable identifier printed on the physical charging key
  • validFrom (iso datetime string) - default - current date
  • validTo (iso datetime string) - default - 10 years from 'validFrom' date
  • type (string, enum) - the value can be either TAG or CARD - this is just for reference, there are no practical implications

Example body:

{
  "uid": "7d009d67181896",
  "visualNumber": "ES*BA*4321EU*1",
  "validFrom": "2022-01-24T11:25:54.210Z",
  "validTo": "2022-01-24T11:25:54.210Z",
  "type": "CARD"
}

Example response:

201 - OK

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid.
  • 500 - Internal Server Error

Charging Key Activation - POST

  • Links the reserved charging key to a specific user (userId), enabling it for authentication at charging stations.
  • Once activated, the key is fully functional and can be used for charging sessions.
  • A user can have multiple active keys, and keys can be enabled or disabled as needed.

Endpoint: /v1/users/{userId}/charging-keys/{referenceId}/activate

API Reference

Parameters:

  • userId - path parameter, string - the user to which assign the charging key
  • referenceId - path parameter, string - the visualNumber from the charging key reservation

Response fields:

  • name (string) - key name (usually used by end-users to name their keys when they have multiple)
  • enabled (boolean, required) - indicates if the key is enabled or not
  • keyId (string, required) - identifier used for this charging key (uid in the case of a physical charging key)
  • referenceId (string) - human-readable identifier printed on the physical charging key
  • contractId (string) - identifier used in the context of roaming
  • type (string, required) - possible values are tag, card or virtual
  • validFrom (iso datetime string, required)
  • validTo (iso datetime string, required)
  • created (iso datetime string, required)
  • updated (iso datetime string, required)

Example response:

200 - OK

{
  "name": "key 4390b827",
  "enabled": true,
  "keyId": "27b89043",
  "referenceId": "DE*8PS*CD0C00*2",
  "contractId": "DE-8PS-C0CD0C002-Q",
  "type": "tag",
  "validFrom": "2021-12-08T00:00:00.000Z",
  "validTo": "2031-12-08T23:59:59.000Z",
  "created": "2021-12-08T10:33:01.000Z",
  "updated": "2021-12-08T10:33:01.000Z"
}

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid.
  • 404 - User or charging key not found
  • 409 - Key already in use
  • 500 - Internal Server Error

Charging Key - PATCH

This endpoint allows to change the key name and disable / re-enable it.
When a charging key is disabled, it will immediately stop working on chargers.

Endpoint: /v1/users/{userId}/charging-keys/{identifier}

API Reference

Parameters:

  • userId - path parameter, string
  • identifier - path parameter, string - keyId or contractId returned from either activation or "get charging key" endpoints

Request body:

  • name - string, optional
  • enabled - boolean, optional

Example body:

{
  "name": "string",
  "enabled": true
}

Response fields:

  • name (string) - key name (usually used by end-users to name their keys when they have multiple)
  • enabled (boolean, required) - shows if key is enabled or not
  • keyId (string, required) - identifier used for this charging key (uid in the case of a physical charging key)
  • referenceId (string) - human-readable identifier printed on the physical charging key
  • contractId (string) - identifier used in the context of roaming
  • type (string, required) - possible values are tag, card or virtual
  • validFrom (iso datetime string, required)
  • validTo (iso datetime string, required)
  • created (iso datetime string, required)
  • updated (iso datetime string, required)

Response example:

200 - OK

{
  "name": "key 4390b827",
  "enabled": true,
  "keyId": "27b89043",
  "referenceId": "DE*8PS*CD0C00*2",
  "contractId": "DE-8PS-C0CD0C002-Q",
  "type": "tag",
  "validFrom": "2021-12-08T00:00:00.000Z",
  "validTo": "2031-12-08T23:59:59.000Z",
  "created": "2021-12-08T10:33:01.000Z",
  "updated": "2021-12-08T10:33:01.000Z"
}

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User or charging key not found
  • 500 - Internal Server Error

Get Charging Keys - GET

Returns a list of all activated charging keys of a given user.

Endpoint: /v1/users/{userId}/charging-keys

API Reference

Parameters:

  • userId - path parameter, string

Response fields:

  • keys (array) - contains all keys the user has
    • name (string) - key name (usually used by end-users to name their keys when they have multiple)
    • enabled (boolean, required) - shows if key is enabled or not
    • keyId (string, required) - identifier used for this charging key (uid in the case of a physical charging key)
    • referenceId (string) - human-readable identifier printed on the physical charging key
    • contractId (string) - identifier used in the context of roaming
    • type (string, required) - possible values are tag, card or virtual
    • validFrom (iso datetime string, required)
    • validTo (iso datetime string, required)
    • created (iso datetime string, required)
    • updated (iso datetime string, required)

Response example:

200 - OK

{
  "keys": [
    {
      "name": "key 4390b827",
      "enabled": true,
      "keyId": "27b89043",
      "referenceId": "DE*8PS*CD0C00*2",
      "contractId": "DE-8PS-C0CD0C002-Q",
      "type": "tag",
      "validFrom": "2021-12-08T00:00:00.000Z",
      "validTo": "2031-12-08T23:59:59.000Z",
      "created": "2021-12-08T10:33:01.000Z",
      "updated": "2021-12-08T10:33:01.000Z"
    }
  ]
}

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User or charging key not found
  • 500 - Internal Server Error

Order Charging Key - POST

This endpoint allows you to order a charging key for a specific user.

🚧

Before using this endpoint, a manual configuration is required on the Plugsurfing side.

Therefore, we ask you to reach out to us before using it.

📘

To prevent duplicate orders, ordering charging keys for a single user is throttled to 1 order every 5 minutes. This is a safety measure to avoid accidental double-clicks on the order button, preventing the user from being charged twice.
If the user exceeds this limit, a 429 - Too Many Requests HTTP response will be returned.

Endpoint: /v1/users/{userId}/charging-keys/order

API Reference

Parameters:

  • userId - (path parameter, string)

Body fields

  • addrress (object)
    • addressLine1 (string)
    • addressLine2 (string, optional)
    • postalCode (string)
    • city (string)
    • country (string)
    • firstName (string, optional)
    • lastName (string, optional)
    • companyName (string, optional)
  • taxationCountry (string) - Two letter taxation country code
  • paymentOptionId (string, optional) - Stripe payment option id. If not passed, a default one is used.

Example body:

{
  "address": {
    "companyName": "Smith Consulting",
    "firstName": "John",
    "lastName": "Smith",
    "addressLine1": "Driver road 1",
    "addressLine2": "Apartment 5",
    "postalCode": "11122",
    "city": "Berlin",
    "country": "Germany"
  },
  "taxationCountry": "DE",
  "paymentOptionId": "STRIPE-6738556949187507"
}

Response fields:

  • id (string)
  • state (string) - ["ORDER_FILLED", "ORDER_CANCELLED", "ORDER_PROCESSING", "ORDER_PAYMENT_FAILED", "ORDER_REFUND_FAILED", "ORDER_REFUNDED", "ORDER_PLACED", "ORDER_PAID"]

Response example:

200 - OK

{
  "id": "xXXx11",
  "state": "ORDER_PLACED"
}

Error responses:

  • 400 - The provided query parameters, route parameters or body is invalid
  • 404 - User not found
  • 429 - Too many requests (>1 order placed by the same user within 5 minutes)
  • 500 - Internal Server Error

Get List of Ordered Charging Keys - GET

This endpoint returns the list of ordered charging keys for a given user.

Endpoint: /v1/users/{userId}/charging-keys/orders

API Reference

Parameters:

  • userId - (path parameter, string)

Response fields:

  • Array []
    • id (string) - order id
    • created (iso datetime string) - creation date and time of the order
    • updated (iso datetime string) - date and time of last status update
    • address (object)
      • companyName (string)
      • firstName (string)
      • lastName (string)
      • addressLine1 (string)
      • addressLine2 (string)
      • postalCode (string)
      • city (string)
      • country (string)
    • quantity (number) - amount of keys in order
    • state (string/enum) - one of ORDER_FILLED, ORDER_CANCELLED, ORDER_PROCESSING, ORDER_PAYMENT_FAILED, ORDER_REFUND_FAILED, ORDER_REFUNDED, ORDER_PLACED, ORDER_PAID, UNKNOWN (map unknown values to UNKNOWN)
    • hasReceipt (boolean) - indicates if a receipt was generated for the order or not

Response example:

200 - OK

[
  {
    "id": "vrj82A9EpJ",
    "created": "2022-04-07T11:30:57.000Z",
    "updated": "2022-04-07T11:30:57.000Z",
    "address": {
      "companyName": "Smith Consulting",
      "firstName": "John",
      "lastName": "Smith",
      "addressLine1": "Rättarvägen 3",
      "postalCode": "12345",
      "city": "Solna",
      "country": "Sweden"
    },
    "quantity": 1,
    "state": "ORDER_FREE_OF_CHARGE",
    "hasReceipt": true
  }
]

Error responses:

  • 500 - Internal Server Error

Get URL to Charging Keys Order Receipt - POST

Returns an absolute URL to the receipt. You can check if the order has a receipt or not with the endpoint above.

Endpoint: /v1/users/{userId}/charging-keys/orders/{orderId}/receipt

API Reference

Response example:

200 - OK

{
  "url": "https://test-fortum-product-receipts.s3.eu-west-1.amazonaws.com/4381089-47759"
}

Error responses:

  • 400 - The provided path parameters are invalid
  • 404 - Receipt not found
  • 500 - Internal Server Error

Charging Keys Orders Configuration - GET

Returns the pricing information for ordering charging keys per country. Each country has to be set up manually for your organization in order for it to show up here.

Endpoint /v1/charging-keys/orders/configuration

API Reference

Response fields:

  • countries (array)
    • country (string) - The two-letter code of the country.
    • currency (string) - The three-letter currency code.
    • priceMinorInclVat (number, integer) - The price in the currency. The example below defines 10 euros and 0 cents.
    • vat (number, integer) - The percent of VAT. The example below shows 25% VAT.

Response example:

200 - OK

{
  "countries": [
    {
      "country": "FI",
      "currency": "EUR",
      "priceMinorInclVat": 10,
      "vat": 25
    }
  ]
}

Error responses

  • 404 - No pricing found for organization
  • 500 - Internal Server Error

Updated 3 months ago