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
- Charge card (i.e. RFID card)
- 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' or 'hub-de'
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"
}
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
Updated about 1 year ago