Plugsurfing EMP Sessions API

openapi: 3.2.0
info:
  title: Drive EMP Sessions API
  version: 1.0.0
  description: The Drive API provides comprehensive access to Plugsurfing's charging infrastructure network. It enables you to manage users, charging keys, search for charging locations, handle payments, and control charging sessions.
servers:
- url: https://{environment}.plugsurfing.com
  variables:
    environment:
      enum:
      - drive-api-stage
      default: drive-api-stage
      description: API environment - use drive-api-stage for testing and drive-api for production
tags:
- name: EMP Sessions
  description: E-Mobility Provider specific endpoints for managing charging sessions
paths:
  /emp/v1/sessions/start:
    post:
      tags:
      - EMP Sessions
      summary: Start a remote session
      operationId: startRemoteSessionEmp
      description: 'Starts a remote charging session with the given charging key on the given connector.


        If a user has `CREDIT_CARD` payment method, and 3DS challenge mode is set to `CHALLENGE`, then `threeDSClientSecret` might be present instead of `sessionId`, which your frontend needs to prompt the user to sign. After the user successfully signs the challenge, do a second start request!'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmpSessionStartRequest'
            example:
              connectorId: aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==
              keyIdentifier: BnZd3qp87z
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStartResponse'
              example:
                sessionId: AAdmD55q8Vz
                threeDSClientSecret: pi_3MtwBwLkdIwHu8ix28v3tqPa_secret_YrKJUkribcBjcG7HVhfZluoGH
        '400':
          description: The provided query parameters, route parameters or body is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestErrorResponse'
              example:
                message: Invalid request payload
                details:
                - field X is required
        '403':
          description: Forbidden. The charging key is not allowed to charge, or the connector won't allow remote charging.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
        '404':
          description: Charging key or connector is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
      security:
      - ApiKeyAuth: []
  /emp/v1/sessions/{sessionId}/stop:
    post:
      tags:
      - EMP Sessions
      summary: Stop a remote session
      operationId: stopRemoteSessionEmp
      description: Stops the given remote charging session. Only sessions started remotely can be remotely stopped.
      parameters:
      - name: sessionId
        in: path
        description: session id
        example: AAdmD55q8Vz
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
      security:
      - ApiKeyAuth: []
  /emp/v1/sessions/{sessionId}/receipt:
    get:
      tags:
      - EMP Sessions
      summary: Get a session receipt by session id
      operationId: getSessionReceiptEmp
      description: Get session receipt. The response includes a time-limited URL to access the receipt. A new URL is required after expiration. Receipts are not available for sessions with a price of 0, and a 404 error will be returned if requested. The receipt will be in PDF format.
      parameters:
      - name: sessionId
        in: path
        description: Session id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              example:
                url: string
        '404':
          description: Receipt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
      security:
      - ApiKeyAuth: []
  /emp/v1/sessions/{sessionId}:
    get:
      tags:
      - EMP Sessions
      summary: Get session by id
      operationId: getSessionByIdEmp
      description: Returns charging session details
      parameters:
      - name: sessionId
        in: path
        description: Session id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              example:
                balanceStatus: PROCESSING
                sessionStatus: CREATED
                charger:
                  chargingStationName: Drive_API_Test1_Station1
                  city: Solna
                  connectorLabel: '1'
                  evseId: SE*CND*EC1*1
                  streetName: Rättarvägen
                balanceAmountMinor: '-2160'
                chargingKeyType: virtual
                connectorId: O9UXK+YI5Q6i0FoI4qHwcA==
                duration: PT28.913S
                energy:
                  unit: WH
                  value: 57
                paymentMethod: CREDIT_CARD
                price:
                  currencyCode: EUR
                  minorExclVat: 2785
                  minorInclVat: 1
                  vat: '17.5'
                receiptAvailable: true
                sessionId: AAdmD55q8Vz
                site: Drive_API_Test1
                startTime: '2021-01-30T10:00:00.111111111Z'
                transactions:
                - paymentMethod: CREDIT_CARD
                  paymentOutcome: CHARGE
                  amount:
                    currencyCode: EUR
                    minorExclVat: 2785
                    minorInclVat: 1
                    vat: '17.5'
                  time: '2021-01-30T10:00:00.111111111Z'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Resource not found
      security:
      - ApiKeyAuth: []
components:
  schemas:
    SessionAmount:
      required:
      - currencyCode
      - minorExclVat
      - minorInclVat
      - vat
      type: object
      properties:
        currencyCode:
          type: string
          description: 3-letter currency code
          example: EUR
        minorExclVat:
          type: integer
          description: 'Minor units amount. Example: 2785 = 27.85€.'
          example: 2785
        minorInclVat:
          type: integer
          description: Minor units amount
        vat:
          type: string
          description: VAT percentage
          example: '17.5'
      description: Monetary amount with currency and VAT breakdown.
    Receipt:
      required:
      - url
      type: object
      properties:
        url:
          type: string
    Session:
      required:
      - sessionStatus
      - connectorId
      - sessionId
      - transactions
      type: object
      properties:
        balanceStatus:
          $ref: '#/components/schemas/SessionBalanceStatus'
          description: Balance state after applying session costs.
        sessionStatus:
          $ref: '#/components/schemas/SessionStatus'
          description: Current lifecycle status of the session.
        charger:
          $ref: '#/components/schemas/SessionCharger'
          description: Charger location and connector metadata.
        balanceAmountMinor:
          type: number
          example: '-2160'
          description: Type "Long". This field is not relevant for External Clearing (only used when using Plugsurfing's Payment Service Provider). Represents the remaining amount to be paid, expressed as a negative number. A value of 0 indicates the balance is fully paid. -2160 means there is an outstanding amount of 21.60 in the currency of the session.
        chargingKeyType:
          type: string
          example: virtual
          description: Only available after a session has successfully started. Possible values are "tag", "card", "virtual" or "plug_and_charge".
        connectorId:
          type: string
          example: O9UXK+YI5Q6i0FoI4qHwcA==
          description: Only available after a session has successfully started.
        duration:
          type: string
          format: duration
          description: The value is in ISO 8601 duration format
          example: PT28.913S
        energy:
          $ref: '#/components/schemas/SessionEnergy'
          description: Energy consumed during the session.
        paymentMethod:
          type: string
          enum:
          - CREDIT_CARD
          - EXTERNAL
          - PREPAID
          - WRITE_OFF
          deprecated: true
          description: 'Returns the `paymentMethod` of the transaction with the earliest timestamp. This field is `DEPRECATED` and will be removed in future versions. Use `session.transactions[].paymentMethod` instead. Migration note: `WRITE_OFF` was renamed to `NONE`, where `session.transactions[].paymentOutcome=WRITE_OFF` is the replacement'
        price:
          $ref: '#/components/schemas/SessionAmount'
          description: Total session price.
        receiptAvailable:
          type: boolean
          description: Indicates whether a receipt can be downloaded.
        sessionId:
          type: string
          example: AAdmD55q8Vz
          description: Unique identifier of the charging session.
        site:
          type: string
          example: Drive_API_Test1
          description: Human-readable charging site name.
        startTime:
          $ref: '#/components/schemas/Time'
          description: UTC timestamp when the session started.
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          description: Transactions linked to this charging session.
      description: Detailed charging session information.
    EmpSessionStartRequest:
      required:
      - connectorId
      - keyIdentifier
      type: object
      properties:
        connectorId:
          type: string
          example: aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==
          description: Connector identifier to start charging on.
        keyIdentifier:
          type: string
          example: BnZd3qp87z
          description: Charging key identifier used for authorization.
      description: EMP session start request identifying connector and charging key.
    SessionStatus:
      type: string
      description: IMPORTANT - when handling this enum other unknown values should be handled.
      enum:
      - CREATED
      - WAITING_TO_START
      - STARTED
      - WAITING_TO_STOP
      - STOPPED
      - COMPLETE
      - FAILED
      - UNKNOWN
      - STOP_FAILED
    SessionCharger:
      type: object
      properties:
        chargingStationName:
          type: string
          example: Drive_API_Test1_Station1
          description: Display name of the charging station.
        city:
          type: string
          example: Solna
          description: City where the charger is located.
        connectorLabel:
          type: string
          example: '1'
          description: Connector label reported by the charge point operator.
        evseId:
          type: string
          example: SE*CND*EC1*1
          description: EVSE identifier for the charging point.
        streetName:
          type: string
          example: Rättarvägen
          description: Street address of the charger.
      description: Location and connector information for the charger used in a session.
    SessionEnergy:
      required:
      - unit
      - value
      type: object
      properties:
        unit:
          type: string
          example: WH
          description: Energy unit, typically kWh.
        value:
          type: number
          example: 57
          description: Measured energy value for the session.
      description: Energy measurement data for a charging session.
    InvalidRequestErrorResponse:
      title: InvalidRequestErrorResponse
      type: object
      required:
      - message
      - fields
      properties:
        message:
          type: string
        fields:
          type: array
          items:
            title: InvalidField
            type: object
            required:
            - name
            - message
            - rejectedValue
            properties:
              name:
                type: string
              message:
                type: string
                example: UserId is not correct
              rejectedValue:
                type: string
    SessionBalanceStatus:
      type: string
      enum:
      - PROCESSING
      - PAID
      - DEBT
      - REFUND
      description: 'Note: this field is not relevant when using External Clearing.'
    Time:
      type: string
      format: date-time
      description: Timestamp in ISO 8601 UTC format with up to nanosecond precision.
      example: '2021-01-30T10:00:00.111111111Z'
    ErrorResponse:
      title: ErrorResponse
      type: object
      properties:
        message:
          type: string
    Transaction:
      type: object
      description: Represents a transaction with payment details and time.
      properties:
        paymentMethod:
          type: string
          enum:
          - CREDIT_CARD
          - EXTERNAL
          - PREPAID
          - NONE
          description: The payment method used for the transaction. Can be `NONE` for outcome `WRITE_OFF`
        paymentOutcome:
          type: string
          enum:
          - CHARGE
          - WRITE_OFF
          - REFUND
          description: The outcome of the payment process.
        amount:
          $ref: '#/components/schemas/SessionAmount'
        time:
          $ref: '#/components/schemas/Time'
      required:
      - paymentMethod
      - paymentOutcome
      - amount
      - time
    SessionStartResponse:
      type: object
      description: SessionId will always be present, unless CREDIT_CARD reservation for a user is required during authentication, then either sessionId or threeDSClientSecret will be present.
      properties:
        sessionId:
          type: string
          description: This session id should be stored and used in other endpoints.
          example: AAdmD55q8Vz
        threeDSClientSecret:
          type: string
          description: Will only be available for users with CREDIT_CARD payment methods, when CHALLENGE mode has been enabled for 3DS challenges. The 3DS client secret can be used to complete a payment from your frontend. If not present, no user authentication is required to start the session.
          example: pi_3MtwBwLkdIwHu8ix28v3tqPa_secret_YrKJUkribcBjcG7HVhfZluoGH
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication