Charge Assist API

Intro

The Charge Assist API provides key API building blocks to develop EV charging features on top off:

  • Add / manage charge cards
  • Find locations & availability
  • Scan QR codes
  • Start / stop Session
  • Session & Cost information

Link to Charge Assist API

Below are screenshots from the Charge Assist App that can be reconstructed using the underlying APIs.

Use Cases

We see two/three main use cases to use APIs

Use case 1: Custom EV charging App for eMSPs

eMSPs wishing to create custom features on top of current functionality can develop their own Application using key APIs as building blocks. E.g. for Loyalty points, incentives etc.

Especially functionalities that would require bespoke integrations to the Customer's systems

Use case 2: Integrate into existing Apps:

Charge Assist is developed as a designated EV charging App. Some Customers might wish to integrate it into existing mobile or web applications e.g. Utility companies, Hotels, shopping malls.

A key difference might be the frequency of usage

  • The everyday way for Drivers to charge via mobile
    vs.
  • Sporadic charging based on locations

Sporadic charging could mean a Driver staying at a hotel and would be required to use the proprietary hotel app to use the EV chargers. Chargers can't be used by non-App users. This is a 'closed loop' implementation

They key difference in implementation is to use anonymous tokens vs. connecting Users to the GreenFlux CRM system

Technical details

High Level Sequence Diagram

1) Put Token

In ChargeAssist, the User is identified by an 'appToken'. In the mobile App, this is the mobile device token to create a unique identified linked to a mobile device.

This can be a random string or an identifier linked to a Customer's CRM system.

2) Adding ChargeCard or ExternalPaymentID

There are two options to authorise a charge session

  1. Charge card (i.e. RFID card)
  2. External payment method (e.g. Credit card)

Each of these payment methods is converted into a paymentMethodId ("id") that is required to start a session.
The payment methods are linked to the appToken and can be retrieved with the GET Wallet request.



2a) Add charge card

To add a ChargeCard, use the PUT ChargeCard endpoint.
Only the “visualNumber” is required in the body.

{
    "visualNumber": "770674109963002836"
}

The response will include a paymentMethodId, “id”.

{
    "id": "6e6a4130-bdb6-4375-ae3d-19edcd2849fc",
    "type": "CHARGE_CARD",
    "chargeCardIssuer": "name",
    "cardHint": "** **** **** **** 2836",
    "cardShortHint": "750674109943002836",
    "isVidMapped": false,
    "isAccountPaymentMethod": false,
    "verificationStatus": "PENDING"
}

2b) Add externalPaymentMethod
To add payment Methods, use the PUT externalPaymentMethod endpoint.

This can be a random string. We recommend that partners use a reference to their payment provider.

{
    "externalPaymentMethodId": "UFSedBQuyYajI25hy3Y6TsdeSF"
}

The ChargeAssist backend will create a 'virtual charge card' ("GF-App token"). This Token however is not returned, only the externalPaymentID 'id'.

{
   "id":"862f291f-2dta-46e5-8956-57e566c4ebff",
   "externalPaymentMethodId":"UFSedBQuyYajI25hy3Y6TsdeSF",
   "type":"EXTERNAL",
   "isVidMapped":false,
   "verificationStatus":"VALID"
}

🚧

Enable external Payment method

This option needs to be enabled by GreenFlux. Please contact the Customer Support Manager to direct technical contact to enable anonymised payments

3) GET Location

In order to start a session, the Location and EVSE-ID is required.

The GET Bounding box is best used for map applications and returns a condensed list of Charge stations.

{
    "boundingBox": {
        "bottomLeftLat": 52.362815,
        "bottomLeftLng": 4.9188916,
        "topRightLat": 53.362815,
        "topRightLng": 5.9188916
    },
    "data": [{
        "id": "nl-gfx-a2f2ce5a-8721-4077-9739-6d1a6dce20e0",
        "type": "ON_STREET",
        "name": "Marga",
        "add": "Margaklompehof 11",
        "city": "Almere",
        "country": "NLD",
        "lat": 52.37707,
        "lng": 5.21647,
        "conAvail": 2,
        "conTot": 3,
        "dp": true,
        "rfid": true,
        "branding": {
            "id": "greenflux",
            "displayName": "Demo Station",
            "primaryColorHex": "#50B748",
            "logoUrl": "https://gfxappa.blob.core.windows.net/logos/709aedda-0be9-4fec-9418-a227d4ef7c76.png",
            "supportPhone": "0201234567",
            "supportEmail": "[email protected]",
            "supportWebsite": "https://greenflux.com/this-is-acc"
        }
    }, {
        "id": "nl-gfx-40fa8af1-c3f0-45e2-ad72-59b0f384fd02",
        "type": "ON_STREET",
        "name": "Van der Valk Hotel Volendam",
        "add": "Wagenweg 1",
        "city": "Katwoude",
        "country": "NLD",
        "lat": 52.48745,
        "lng": 5.03248,
        "conAvail": 1,
        "conTot": 2,
        "dp": true,
        "rfid": true,
        "brandingId": "greenflux"
    }],
    "meta": {
        "count": 2,
        "hasMoreData": false
    }
}

📘

Location ID 'nl-gfx'

The location ids of Location that are originating from the GreenFlux platform will start with 'nl-gfx'. Location originating from roaming partners might start with e.g. 'de-ewe'.

For CPOs on the GreenFlux platform, all locations will start with 'nl-gfx', regarless of the physical location. The EVSE will have the correct country code of the country it is in.

conAvail

Connectors available (at location)

conTotal

Connectors total (at location)

dp

rfid

whether charge station has RFID readers

Limit
Currently there is a limit of 25 locations for the 'Nearby' search and 50 locations for 'boundary box' search.

We do provide a continuation token, but have not yet implemented a functionality to call further locations.

"meta": {
        "count": 50,
        "hasMoreData": true,
        "continuationToken": "+RID:~wfVqAOCNFQlQBAAAAAAAAA==#RT:1#TRC:50#RTD:+i8v60xxMSd9tu58dbvzBIAA#ISV:2#IEO:65551#QCF:7#FPC:AgEAAACEAIuACoAHwKIEIAAQpjKMgNQCAAAIIgAA4gfAMQCMBzqAAcBYDhOAEgAAMB8AKIABwMwHMQCA8EEAxgMxAADxPIABwB8AMQDTAzEAwHgyAADMBwAxAPgAXoABwJG/T4ADwNEBAABEAEIAEQCAAHICAEwJACWAC4AagFeADKLdgjKAlYGWjQ=="
    }

To get specific details, use the GET Location

{
    "id": "nl-gfx-a2f2ce5a-8721-4077-9739-6d1a6dce20e0",
    "type": "UNKNOWN",
    "name": "Marga",
    "address": "Margaklompehof 11",
    "city": "Almere",
    "postalCode": "1314 WL",
    "country": "NLD",
    "coordinates": {
        "latitude": 52.37707,
        "longitude": 5.21647
    },
    "evses": [{
        "uid": "NL-GFX-EAddCS123-1",
        "displayName": "AddCS123-1",
        "status": "CHARGING",
        "capabilities": [],
        "connectors": [{
            "id": "1",
            "standard": "IEC_62196_T2",
            "format": "SOCKET",
            "powerType": "AC_3_PHASE",
            "phases": 3,
            "kw": 11,
            "voltage": 230,
            "amperage": 16,
            "tariffId": "A1"
        }],
        "chargingNotAllowed": false,
        "directions": [{
            "language": "en",
            "text": "the directions to the EVSE"
        }],
        "restrictedAccess": false
    }, {
        "uid": "NL-GFX-EChargestation-1",
        "displayName": "Chargestation-1",
        "status": "AVAILABLE",
        "capabilities": [],
        "connectors": [{
            "id": "1",
            "standard": "IEC_62196_T2",
            "format": "SOCKET",
            "powerType": "AC_1_PHASE",
            "phases": 1,
            "kw": 7,
            "voltage": 230,
            "amperage": 32,
            "tariffId": "A1"
        }],
        "chargingNotAllowed": false,
        "directions": [{
            "language": "en",
            "text": "text"
        }],
        "restrictedAccess": false
    }, {
        "uid": "NL-GFX-ENL-GFX-Ramya-TEST01-1",
        "displayName": "TEST01-1",
        "status": "AVAILABLE",
        "capabilities": [],
        "connectors": [{
            "id": "1",
            "standard": "IEC_62196_T2",
            "format": "CABLE",
            "powerType": "AC_1_PHASE",
            "phases": 1,
            "kw": 7,
            "voltage": 230,
            "amperage": 32,
            "tariffId": "A1"
        }],
        "floorLevel": "3",
        "chargingNotAllowed": false,
        "directions": [{
            "language": "en",
            "text": "text"
        }],
        "restrictedAccess": false
    }, {
        "uid": "NL-GFX-EExternalID123-1",
        "displayName": "xternalID123-1",
        "status": "UNKNOWN",
        "capabilities": [],
        "connectors": [{
            "id": "1",
            "standard": "IEC_62196_T2",
            "format": "SOCKET",
            "powerType": "AC_3_PHASE",
            "phases": 3,
            "kw": 11,
            "voltage": 230,
            "amperage": 16,
            "tariffId": "A5"
        }],
        "chargingNotAllowed": false,
        "directions": [],
        "restrictedAccess": false
    }],
    "directions": [{
        "language": "en",
        "text": "The directions to the location"
    }],
    "operator": {
        "name": "GreenFlux",
        "website": "https://www.greenflux.com",
        "logo": {
            "url": "https://gfxrevoltt.blob.core.windows.net/logos/2ddfb149-a53a-4d92-a9d3-e43035d5ce5f.png",
            "thumbnail": "https://gfxrevoltt.blob.core.windows.net/logos/2ddfb149-a53a-4d92-a9d3-e43035d5ce5f.png",
            "category": "OPERATOR",
            "type": "png",
            "width": 0,
            "height": 0
        }
    },
    "facilities": ["MALL"],
    "branding": {
        "id": "greenflux",
        "displayName": "Total Demo",
        "primaryColorHex": "#50B748",
        "logoUrl": "https://gfxappa.blob.core.windows.net/logos/709aedda-0be9-4fec-9418-a227d4ef7c76.png",
        "supportPhone": "0201234567",
        "supportEmail": "[email protected]",
        "supportWebsite": "https://greenflux.com/this-is-acc"
    },
    "smartChargingEnabled": false,
    "reservationEnabled": false,
    "dp": true,
    "rfid": true,
    "pms": ["CHARGE_CARD", "MASTER_CARD", "VISA", "AMEX", "APPLE_PAY", "GOOGLE_PAY"],
    "issuers": [],
    "availability": "NONE"
}

POST Parse QR code to Get Location ID

{
    "valid": true,
    "id": "d17c60e1-655f-4ff7-a802-15ccb2e7eb7f",
    "datasource": "gsop",
    "operator": "greenflux",
    "locationId": "nl-gfx-a2f2ce5a-8721-4077-9739-6d1a6dce20e0",
    "ocpiLocationId": "a2f2ce5a-8721-4077-9739-6d1a6dce20e0",
    "evseUid": "NL-GFX-EAddCS123-1",
    "url": "https://chart.googleapis.com/chart?cht=qr&chl=https%3A%2F%2Fa.greenflux.app%2Fqr%2Fgsop%2Fgreenflux%2Fd17c60e1-655f-4ff7-a802-15ccb2e7eb7f&chs=400x400&choe=UTF-8&chld=L|0",
    "createdDate": "2021-01-15T10:41:35.7386493+00:00"
}

🚧

Opening Hours not supported

Please note, that currently Opening Hours are not returned via Charge Assist.
This means that any published location is shown in its current status (available, charging etc).

4) Get Tariff

Use the GET Tariff endpoint to retrieve the tariff and expose this to the Driver beforehand.

It will also return the available payment methods linked to the appToken

{
    "data": [{
        "tariff": {
            "tariffType": "RETAIL",
            "vatPercentage": 13.00,
            "currency": "EUR",
            "isVatIncluded": true,
            "elements": [{
                "priceComponents": [{
                    "price": 1.64,
                    "type": "FLAT",
                    "stepSize": 1,
                    "vat": 13.00
                }, {
                    "price": 2.106,
                    "type": "ENERGY",
                    "stepSize": 1,
                    "vat": 13.00
                }, {
                    "price": 0.351,
                    "type": "TIME",
                    "stepSize": 60,
                    "vat": 13.00
                }]
            }]
        },
        "validity": "VALID",
        "paymentMethod": {
            "id": "112f291f-2dda-46e5-9956-57e566b4ebff",
            "externalPaymentMethodId": "UFSedBQuyYajI25hy3Y6TsdeSF",
            "type": "EXTERNAL",
            "isCompatible": false,
            "isVidMapped": false,
            "isAccountPaymentMethod": false,
            "verificationStatus": "VALID"
        }
    }, {
        "validity": "UNKNOWN",
        "paymentMethod": {
            "id": "6e6a4130-bdb6-4375-ae3d-19edcd2849fc",
            "type": "CHARGE_CARD",
            "chargeCardIssuer": "name",
            "cardHint": "** **** **** **** 2836",
            "cardShortHint": "750674108943002836",
            "isCompatible": true,
            "isVidMapped": false,
            "isAccountPaymentMethod": false,
            "verificationStatus": "PENDING"
        }
    }],
    "meta": {
        "count": 2,
        "hasMoreData": false
    }
}

5) POST Start session

To start a Session via the API, use the POST Session Start endpoint
The Location and EVSE-ID need to have the Country and Party-id inserted at the beginning, e.g. nl-gfx. Note: location & EVSE ID are case sensitive,

The intended paymentMethodId to authorise the transaction should be used. This could be the charge Card or the external payment method created in step 2 above.

Request:

{
    "locationId": "nl-gfx-3889ee184-33fd-464f-a18c-e96r5479b7b3",
    "evseUid": "NL-GFX-ECentralTrain-Station-1",
    "connectorId": "1",
    "paymentMethodId": "6e6a4130-bdb6-4375-ae3d-19edcd2849fc"
}

(note: the country and party id 'nl-gfx' in location ID is caps sensitive)

Response:

{
    "chargeSessionId": "38ac4790-c7e0-4b55-95a9-a7fe590081fc",
    "nextStatusCall": "2021-06-14T08:57:20.0231712+00:00"
}

6) GET session

The chargeSessionId from the Response in the Session Start can be used to get updates on the Session.

{
    "locationId": "nl-gfx-3889ee184-33fd-464f-a18c-e96r5479b7b3",
    "evseUid": "NL-GFX-ECentralTrain-Station-1",
    "connectorId": "1",
    "status": "CHARGING",
    "canRateSession": false,
    "energyInKwh": 10.15,
    "currentPowerInKw": 213.02,
    "currency": "EUR",
    "startTime": "2021-06-14T10:59:20+02:00",
    "endTime": null,
    "nextStatusCall": "2021-06-14T09:04:03.853177+00:00",
    "smartChargingEnabled": false,
    "prioritySessionStatus": "NOT_APPLICABLE",
    "vidStatus": "VID_NOT_AVAILABLE",
    "chargingNotAllowed": false
}

The session information is near real time

7) Session stop

Use the chargeSessionId to stop the session.

The response will include an update Session response.

{
    "locationId": "nl-gfx-3889ee184-33fd-464f-a18c-e96r5479b7b3",
    "evseUid": "NL-GFX-ECentralTrain-Station-1",
    "connectorId": "1",
    "status": "CDR_AVAILABLE",
    "canRateSession": false,
    "energyInKwh": 20.86,
    "currentPowerInKw": 0.0,
    "totalCosts": 20.45,
    "totalVat": 2.35,
    "vatPercentage": 13.0,
    "currency": "EUR",
    "startTime": "2021-06-14T11:56:56+02:00",
    "endTime": null,
    "nextStatusCall": "2021-06-14T09:59:58.5063223+00:00",
    "smartChargingEnabled": false,
    "prioritySessionStatus": "NOT_APPLICABLE",
    "vidStatus": "VID_NOT_AVAILABLE",
    "chargingNotAllowed": false
}

Further details

Payment

  • App Developer needs to use their own PSP if mobile payments should be enabled
  • Developer fully responsible for pricing & payments, enabling:
    • Any kind of payment method via mobile
    • RFID / charge card
    • Coupons, Vouchers
    • Discounts
    • Loyalty points, etc.

Locations, Tariffs & Access

  • Create a ‘closed loop’ of chargers with access only to App users
  • Set default tariffs and/or tariffs for specific User groups (via CRM API)

Users

  • Customer is fully in control of Users and access
  • Anonymised Users & access tokens
  • Link customers to GreenFlux CRM for management of Tokens

AppToken

  • it is possible to start multiple sessions with the same App token and the same ChargeCard or externalPaymentId

Considerations & Limitations

UX/UI

  • No UI components or SDK available
  • Push notifications, warnings or webhooks not available

BI and analytics

  • For larger scale BI and analytics, access to the Platform API is necessary

Charge Assist App features not yet in API

  • Some functionalities are currently only available in the App due to custom UX and logic:
  • Plug n Charge registration
  • Priority Smart Charging

Non-supported features

  • Reservations is not recommended given current Charge station technology
  • Stop or unlock when parking is not available

Did this page help you?