Skip to main content

Technical requirements

Mohammed Mohammed Assim
Updated
  • Plugsurfing officially support version 2.2 and 2.2.1 alongside version 2.1.1 of the OCPI protocol (Github link)
  • from this point onwards, to simplify the article. versions 2.2 and 2.2.1 will be referred to as 2.2.x 
  • These Technical Requirements are subject to change. The CPO shall check these technical requirements regularly for updates. If major updates are done, Plugsurfing will inform the CPOs with one month's notice.

  •  

  • Registration / Credentials Module (Required):

  • Initiation of registration can be done by any of the parties

  • Issuing party Commands Status
    CPO POST credentials Supported
    PUT credentials Supported
    DELETE credentials Supported
    GET versions Supported
    GET endpoints (for a specific version) Supported
    EMP POST credentials Supported
    PUT credentials Supported
    DELETE credentials Supported
    GET versions Supported
    GET endpoints (for a specific version) Supported

  • Plugsurfing expects all CPOs (sub-CPOs, if they exist) that communicate over the OCPI connection to be represented with an unique set of role + party_id + country_code.

  •  

  • Locations Module (Required):

  • The Charging Infrastructure Data shall contain all information required in accordance with the Protocol.
  • The Charging Infrastructure Data submitted by the CPO to Plugsurfing must be accurate, valid, complete, unique and consistent.
  • The Charging Infrastructure must be located within the operating Territories.
  • The Charging Infrastructure Data for a Charging Station must be submitted prior to any Charging Session at this Charging Station.
  • Request Issuing party Commands Status
    Push CPO PUT locations Supported

    PUT EVSE

    		 Supported

    PUT locations

    		 Supported
    PATCH locations (Patch call will only patch properties on the Location, child EVSEs and connectors will not be updated.) Supported
    PATCH locations (Patch calls will only patch properties of the EVSE, child connectors will not be updated.) Supported
    PATCH locations (connector) Supported
    Pull CPO GET locations (i.e., CPO gets location from our platform) Not supported
    EMP GET locations (location) (i.e. our platform gets location from CPO) Supported

  • Differences in 2.2.x

  • The ‘publish’ property

  • Plugsurfing supports the publish property introduced in OCPI 2.2.x.

  • If publish=false, the location will not be published/visible on the map. However, Plugsurfing does not support the publish_allowed_to flag to show only locations to certain individual user.

  • Private locations

  • Plugsurfing requires the CPO to share all locations they intend to send CDRs for up front.

  • If the location should not be shown to users, the CPO is encouraged to use the publish property mentioned above. If private chargers can’t be shared up front, but CDRs will be sent for these locations the CPO has to communicate this to Plugsurfing before the integration is setup.

  • The ‘tariff_ids’ property on connectors

  • Plugsurfing only supports one tariff per connector, default set to REGULAR type.

  •  

  • Tariffs Module (Required):

  • If Tariffs Module is not supported, the standard Fees for charging will apply: https://partnersupport.plugsurfing.com/hc/en-us/articles/360021089838-Fees

  • Request Issuing party Commands Status
    Push CPO PUT Tariffs Supported
    PATCH Tariffs Supported
    Pull CPO GET Tariffs Not supported
    EMP GET Tariffs Supported

  • Plugsurfing only support one tariff per connector, and that must be of REGULAR type. Other tariff types will be dropped. If the CPO use multiple tariff types, Plugsurfing MUST be informed before the integration is setup.

  • Differences in 2.2.x

  • PATCH is removed from Tariffs as this was seen is not useful, use PUT instead.

  • Added county_code and party_id fields

  •  

  • Tokens Module (Required):

  • CPO shall use Realtime Authorization when their system is online.

  • Request Issuing party Commands Status
    Push EMP PUT Tokens (creation/update) Supported
    PATCH Tokens (update) Not supported
    Pull CPO Get Tokens (list) Supported

  • Whitelist type

  • Whitelist type Plugsurfing supports all whitelist types when tokens are exchanged. The applicable whitelist type will be communicated as part of the token data exchange and must be respected by the CPO.
  • If the whitelist type is set to NEVER: Offline authorizations are never allowed. A real-time authorization response ALLOWED is mandatory to allow the charging session to start.
  • CDRs without a valid authorization reference to an ALLOWED authorization will be rejected. Plugsurfing will not pay for those rejected CDRs. 
  • If the whitelist type is set to ALLOWED_OFFLINE:Plugsurfing expects a real-time authorization request to be performed.In case of a temporary communication interruption preventing real-time authorization, the CPO is allowed to take a local authorization decision based on the whitelist status of the token.

  • Real-time authorization

  • Plugsurfing expects the authorization request to contain the location reference where the user intends to charge. If the CPO operates private chargers that are not exchanged via the Location module, the CPO must inform Plugsurfing before the system integration is set up. 

  • If Plugsurfing is not informed accordingly, the authorization result will be returned as NOT_ALLOWED. Plugsurfing will return an authorization reference in all real-time authorization responses. This reference must be included in the CDR for the resulting charging session. 

  • Failure to include a valid authorization reference in the CDR where real-time authorization was conducted, will result in rejection and non-payment of the CDR.

  • OCPI 2.2.x Properties not supported by Plugsurfing 

  • Plugsurfing does currently not support the group_id, default_profile_type and energy_contract property in the Tokens module.

  •  

  • Charge Detailed Records (CDR) (Required):

  • The CDR shall be transmitted immediately, no longer than one hour, after the end of Charging Session.
  • The CDR shall contain all information required in accordance with the Protocol version.
  • The CDR submitted by the CPO to Plugsurfing must be unaltered, complete and correct.
  • The CDR shall be associated with a Customer who was Authorized in Real Time only.
  • The Charging Infrastructure Data for a Charging Station must be submitted prior to any Charging Session at this Charging Station.
  • The CDR shall refer to a positive (zero or higher) energy consumption, price and session time.
  • Request Issuing party Commands Status
    Push CPO POST CDRs Supported
    Pull EMP GET CDRs Supported (Not preferred)

  • OCPI 2.2.x Properties not supported by Plugsurfing 

    Credit CDRs

    Plugsurfing does currently not support credit CDRs. 

  •  

  • Sessions Module (Optional*):

  • Request Issuing party Commands Status
    Push CPO PUT sessions Supported
    PATCH sessions Supported
    Pull CPO GET sessions Not supported
    EMP GET sessions Not supported
  • While optional, Plugsurfing strongly recommends the CPO to utilize this module for real time session updates.
  • This is required if remote start/stop is to be used.

  • OCPI 2.2 Properties not supported by Plugsurfing 

  • Charging preferences

  • Plugsurfing does not support setting charging preferences for a session.

  • Charging profiles

  • Multiple charging profiles are not supported by Plugsurfing.

  •  

  • Commands Module (Optional):

  • Issuing party Commands Status
    EMP POST commands (START_SESSION) Supported
    POST commands (STOP_SESSION) Supported
    POST commands (RESERVE_NOW/CANCEL_RESERVATION) Not supported
    POST commands (UNLOCK) Not supported

  • IMPORTANT: Plugsurfing needs to know if the CPO support remote start before the integration is configured. If the CPO supports remote start, the session module is also required. In order to allow Plugsurfing to inform the end user about the availability and status of this functionality.

  •  

  • Hub Client Info Module

  • This module is  dedicated for connecting to Hubs over ocpi 2.2.x, currently this is not supported and  being developed.

  •  

  • Special use cases

  • Home Charging Compensation

  • in OCPI 2.1.1. Plugsurfing follows the 3-Violin guideline in regards to denoting and processing sessions that are eligible for Home Charging compensation. the remark field must be populated with one of the supported values (HCC_E or HCC_V).
  • For OCPI 2.2.x. the home_charging_compensation flag must be set to true in the CDR. 
  • However this does not provide any details on whether the compensated value includes or excludes the VAT. Plugsurfing interprets the CDR as follows

  • home_charging_compensation

    remark

    total_cost.incl_vat set

    Expected outcome

    false

    N/A

    N/A

    No home charging

    true

    HCC_E

    N/A

    Home charging exempt VAT

    true

    HCC_V

    N/A

    Home charging no. VAT exempt

    true

    null

    null

    Home charging exempt VAT

    true

    null

    set

    Home charging no. VAT exempt

  •  

  • Plug and Charge

  • Plug and Charge (PnC) is not natively supported by the current officially released OCPI versions (2.1.1, 2.2 & 2.2.1), however, Plugsurfing have backported the feature from ocpi 2.3 and currently support PnC over OCPI.
  • The connectors (EVSE) must include one of the following values as a enum value in the ConnectorCapabilities field
  • ISO_15118_2_PLUG_AND_CHARGE
  • ISO_15118_20_PLUG_AND_CHARGE

  • Since July 2025, all PnC keys are pushed as tokens automatically.

  • The new format, suggested by EV Roaming foundation is used.

  • UID is the contractId (in EMAID format after ISO-15118)

  • Token type is “OTHER” (until we support OCPI 2.3 with new type “EMAID”)

  • No whitelisting

  • Example token:

  • {
    "uid": "DE-8PS-COO13A3LZ-3",
    "valid": "true",
    "authId": "DE-8PS-COO13A3LZ-3",
    "type": "OTHER",
    "issuer": "DE*8PS",
    "whitelist": "NEVER",
    "last_updated": "..." 
    }

  •  

  • General Info

  • Information to be shared with Plugsurfing before the integration

  • In order to setup the integration properly the following needs to be provided before the integration is configured.

    • The CPO/platform that is considered the main CPO on this connection.
    • CPO/platform name
    • CPO/platform country_code
    • CPO/platform party_id
    • CPO(s) communicating over the connection
    • CPO country_code
    • CPO Name
    • CPO country_code
    • CPO party_id
    • Is remote start supported by the CPO?
    • Does the CPO require the Token used during an remote start request to exist in the CPO system up front? (If not, Plugsurfing can disable token exchange for these virtual tokens to reduce data exchanged).
    • Will real-time authorization requests and/or CDRs be sent for locations not shared up front over the locations module. If yes, please explain why so Plugsurfing understands what type of locations this is, and why they are kept private.
    • The CPO will deliver the CDR to Plugsurfing directly after the session is completed. (If not possible, please explain why.)

     

    Supported Countries

    • Austria
    • Belgium
    • Croatia
    • Czech Republic
    • Denmark
    • Estonia
    • Finland
    • France
    • Germany
    • Hungary
    • Ireland
    • Italy
    • Latvia
    • Liechtenstein
    • Lithuania
    • Luxembourg
    • Norway
    • Poland
    • Portugal
    • Slovakia
    • Slovenia
    • Spain
    • Sweden
    • Switzerland
    • The Netherlands
    • The United Kingdom
    • The United States of America*

Related articles