Payments

OCPI 2.2.1

By Abhishek Uniyal · Updated

Payments in OCPI 2.2.1

In OCPI 2.2.1, Payments comes from the Direct Payment 2.2.1 extension, published separately from the core chapters.

Payments exchanges Terminal mappings and Financial Advice Confirmations between the CPO and Payment Terminal Provider (PTP). This is the separate Direct Payment 2.2.1 extension. It defines PTP-side and CPO-side interfaces; these are not a universal Sender/Receiver pair.

Sources (5)
"This is a separate module which can be used by CPOs and is an addition on the OCPI 2.2.1 protocol."OCPI 2.2.1 the EVRoaming Foundation extension document · #page-1"Module Identifier: payments Data owner: PTP Type: Functional Module"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-21"• SUCCESS"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-39"Property Type Cardinality Description terminal id CiAsciiString[1..36] 1 Unique ID that identifies a terminal. customer reference CiAsciiString[1..36] ? This reference will be used to link the terminal to a CSMS. The reference might also be provided via the order process. party id CiString[3] ? This is an alternative to the cus- tomer reference which can be used. country code CiString[2] ? This is an alternative to the cus- tomer reference which can be used. address CiString[45] ? Street/block name and house number if available. city CiString[45] ? City or town. postal code CiString[10] ? Postal code of the terminal, may only be omitted when the terminal has no postal code. state CiString[20] ? State or province of the location, only to be used when relevant. country CiString[3] ? ISO 3166-1 alpha-3 code for the country of this location. coordinates GeoLocation ? Coordinates of the terminal. invoice base url URL ? BaseURL to the downloadable invoice invoice creator Enum ? Describes which party creates the in- voice for the eDriver. location ids CiAsciiString[1..36] + List of all locations assigned to that ter- minal. evse uids CiAsciiString[1..36] + List of all EVSEs assigned to that ter- minal. last updated DateTime 1 Timestamp when this Terminal was last updated (or created)."OCPI 2.2.1 the EVRoaming Foundation extension document · #page-30"Property Type Cardinality Description id CiAsciiString[1..36] 1 Uniquely identifies the financial−advice−confirmation. authorization reference CiAsciiString[1..36] 1 Reference to the authorization given by the PTP. total costs Price 1 Real amount that was captured at the PSP. This is a consumer price with VAT. currency CiAsciiString[3] 1 ISO-4217 code of the currency of this tariff. eft data CiAsciiString[1..tbd] + Invoice relevant data from the di- rect payment. EFT capture status code CaptureStatusCode 1 Code that identifies the financial advice status. capture status message CiAsciiString[1..255] ? Message about any error at the financial advice. last updated DateTime 1 Timestamp when this financial advice confirmation was last up- dated (or created)."OCPI 2.2.1 the EVRoaming Foundation extension document · #page-39

Example payload · assigned-terminal

{
  "terminal_id": "EXAMPLE-TERMINAL",
  "location_ids": [
    "EXAMPLE-LOCATION"
  ],
  "evse_uids": [
    "EXAMPLE-EVSE"
  ],
  "last_updated": "2026-01-01T13:00:00Z"
}

Example payload · successful-financial-advice

{
  "id": "EXAMPLE-FINANCIAL-ADVICE",
  "authorization_reference": "EXAMPLE-AUTHORIZATION",
  "total_costs": {
    "excl_vat": 4,
    "incl_vat": 4.4
  },
  "currency": "EUR",
  "eft_data": [
    "Example successful capture"
  ],
  "capture_status_code": "SUCCESS",
  "last_updated": "2026-01-01T13:00:00Z"
}

Which endpoints does this module define?

These paths illustrate the requests. Use the URLs advertised by your partner, replace the placeholders and choose the matching interface. A listed method does not establish that this site's simulator implements it.

PTP

  • Read Terminals.

    GET
    /ocpi/2.2.1/payments/terminals/
  • Assign locations to a Terminal.

    PATCH
    /ocpi/2.2.1/payments/terminals/{terminal_id}
  • Update a Terminal.

    PUT
    /ocpi/2.2.1/payments/terminals/{terminal_id}
  • Read financial advice confirmations.

    GET
    /ocpi/2.2.1/payments/financial-advice-confirmations/
Sources (4)
"Depending on the URL Segments provided, the GET request can either be used to retrieve information about a list of available Terminals at a PTP (GET List) or it can be used to retrieve information about one specific Terminal (GET Object)."OCPI 2.2.1 the EVRoaming Foundation extension document · #page-22"This PATCH should be used by the CPO to assign location ids to a terminal. Example:"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-25"This PUT should be used by the CPO to update location data of a terminal. Example: PUT To URL: https://www.server.com/ocpi/ptp/2.2.1/payments/terminals/55719888- ed09-4cca-82cc-803bdb77bf26"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-25"Depending on the URL Segments provided, the GET request can either be used to retrieve information about a list of all financial advice confirmations at a PTP (GET List) or it can be used to retrieve information about one specific financial advice confirmation"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-33

CPO

  • Read Terminals stored by the CPO.

    GET
    /ocpi/2.2.1/payments/terminals/
  • Create a Terminal.

    POST
    /ocpi/2.2.1/payments/terminals/
  • Read confirmations stored by the CPO.

    GET
    /ocpi/2.2.1/payments/financial-advice-confirmations/
  • Create a financial advice confirmation.

    POST
    /ocpi/2.2.1/payments/financial-advice-confirmations/
Sources (4)
"Depending on the URL Segments provided, the GET request can either be used to retrieve information about a list of Terminals that the PTP has created at the CPO (GET List) or it can be used to retrieve information about one specific created Terminal"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-26"The POST should be used by the PTP to create a newly shipped terminal on the CPO’s system. Here, no location ids should be included as the assignment will be done by the CPO. The object sent here can be just the terminal id or an object with additional"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-28"Depending on the URL Segments provided, the GET request can either be used to retrieve information about a list of Financial Advice confirmations that the PTP has created at the CPO (GET List) or it can be used to retrieve information about one"OCPI 2.2.1 the EVRoaming Foundation extension document · #page-36"The POST should be used by the PTP to create a Financial Advice confirmation on the CPO’s system. This will be used to get the status of the capture and also the required eft data to put on the invoice."OCPI 2.2.1 the EVRoaming Foundation extension document · #page-38

Try an endpoint

Send a request to this site's OCPI endpoints and read the answer. It never reaches your own system.