Session pre-authorization

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.

sequenceDiagram
    participant User
    participant Your backend
    participant Plugsurfing backend
    participant CPO

    User->>Your backend: Remote session start request
    Your backend->>Your backend: Pre-authorization
    Your backend->>Plugsurfing backend: Session start request
    Plugsurfing backend->>CPO: Session start request

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.

sequenceDiagram
    participant User
    participant Your backend
    participant Plugsurfing backend
    participant CPO

    User->>CPO: Local session start request
    CPO->>Plugsurfing backend: Session pre-authorization request
    Plugsurfing backend->>Plugsurfing backend: Internal validation
    Plugsurfing backend->>Your backend: Session pre-authorization request
    Your backend->>Your backend: Pre-authorization
    Your backend->>Plugsurfing backend: Session start response: Accept or deny
    Plugsurfing backend->>CPO: Session start response: Accept or deny

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

• 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 of the user (mandatory)
• countryCode (optional)

  {
    "keyId": "123456",
    "countryCode": "DEU"
  }

The countryCode follows the ISO 3166-1 alpha-3 format.

Response

The response by you shall be a JSON object with the following fields:

Possible values for the AllowedType enum:

Example Response:

  {
    "allowed": "ALLOWED",
    "authorizationReference": "550e8400-e29b-41d4-a716-446655440000",
    "info": "Session allowed"
  }

Response Handling

The timeout for the response is 3 seconds. In cases of no response or technical failure, charging is allowed by default to ensure a good user experience.