Skip to main content
Do online authorization of charging sessions started with charging keys.

​
Introduction

The Session pre-authorization API enables you to do real-time authorization of locally started sessions where the CPO sends a pre-athorization to Plugsurfing. For remote starts through your end user application you can do various checks of the user before sending the start request through to Plugsurfing. With the Authorization API, you will be able to do the same type of internal checks on your user prior to allowing a session to start, for example to do a pre-authorization on the user’s payment method and allow or deny the session start based on the result. Authorization requests will only be shared with you for charging keys that are enabled, if the charging key is disabled Plugsurfing will deny the session without asking you. Plugsurfing will also deny local start requests on CPOs or countries that you have filtered out, given that the authorization request from the CPO includes the location reference. Please note that not all CPOs support pre-authorization, and that CPO’s who do support pre-authorization do not always perform pre-authorization on all locally started sessions. In order to enable Authorization for you, you have to share the endpoint to which Plugsurfing should send the authorization request. You also have to provide the authorization header(s) that Plugsurfing should include when making the request, so that you can verify that the request comes from Plugsurfing. Since Plugsurfing does not always receive the location from the CPO when a local start is initiated, the authorization request will be sent with country code as an optional attribute. Plugsurfing expects the response from you to be ALLOWED / BLOCKED / EXPIRED / NO_CREDIT or NOT_ALLOWED. You can also add additional information about the authorization in the authorization response. If Plugsurfing does not get any response within 3 seconds, the session will be allowed.

​
Flow for remote charging sessions

For remotely started charging sessions, you can do validations of your user before sending through the session start request to Plugsurfing.

​
Flow for local charging sessions

For locally started charging sessions where the CPO shares a pre-authorization, the Session pre-authorization API allows you to do similar user validations before allowing the session to start.

​
Configurations

Session pre-authorization can be configured on stage environment directly from the Control Panel. For production setup you need to contact your account manager. Data needed for configuration:
  • Behavior in case of timeout or malformed response: Allow or deny session when communication fails or response times out
  • Timeout: Number of seconds (1-10) before the request times out
  • URL that will receive the pre-authorization request
  • Authorization headers that will be passed in the request to the mentioned URL.

​
Request

When a local start request is received, the following steps are executed by Plugsurfing:
  • Step 1: Internal Validation
    Perform standard checks:
    • Country filtering
    • Network filtering
    • Key enabled/disabled
  • Step 2: Forwarding to EMP
    If the internal checks passes, Plugsurfing forwards the request to you for pre-authorization. The call is constructed using:
    • The url, as mentioned under the ‘Data needed for configuration’ section
    • The keyId of the user starting the session, included in the request body
URL Example:https://www.your-domain.com/webhooks/plugsurfing/session-pre-auth Headers Example: headers=[Authorization:key=secret_key] Request Body :
  • keyId(string) mandatory: keyId of the user
  • contractId(string) optional: charging key contract id
  • referenceId(string) optional: referenceId of the charging key, referenceId is visual number for RFID keys, Plug and Charge identifier (PCID) for plug_and_charge keys
  • tokenType(string) optional: charging key type, possible values RFID or OTHER
  • countryCode(string) optional: location’s country code, follows the ISO 3166-1 alpha-3 format
  • locationId(string) optional: location id
  • sessionId(string) optional: session for which the authorization is sent, sessionId provided in pre-authorization only for remotely started sessions

​
Response

The response by you shall be a JSON object with the following fields: Possible values for the AllowedType enum: Example Response:

​
Response Handling

The timeout for the response is configured by your needs (1-10 seconds). In case of no response or technical failure, charging is allowed or denied based on your configuration.