Payments Module

Introduction

This module supports the Payment Terminal use case for direct payment in the roaming world.

The module consists mainly of two objects: Terminal and Financial Advice Confirmation. A terminal can handle multiple locations and/or EVSEs. It should be possible for a CPO to assign them to a terminal object. At the end of a charging session there should be a CDR sent. There should also be a financial-advice-confirmation sent from the PTP. This should contain the actual cost and EFT data. This object is only needed if the CPO creates the invoice.

Architectural Approaches

There are two architectural approaches for integrating payment terminals:

16.2. Terminal Assignment

This flow shows the exchange and the assignment of the terminal object. This object will be owned and created by the PTP. After the object was pushed to/pulled by the CPO there will be the possibility to assign specific locations to this terminal. This assignment then will be pushed by the CPO to the PTP.

16.3. Terminal Activation

This flow shows a possible former activation of a payment terminal. Usually, this will be needed for payment terminals integrated into a station. Here the CPO orders a station from the OEM with an integrated payment terminal. The OEM will provide a reference to the CPO which can then be used for the terminal activation at the PTP. After the activation, the PTP will create a terminal object on the CPO side.

16.4. Transaction

This flow shows a single transaction in total. After choosing a specific connector on the terminal the PTP has to pull the current connector information to receive the applicable tariff_id. With this id the tariff should be pulled so that it can be shown on the terminal. Also the tariff is needed to reserve the needed preauth limit (stated in the preauthorize_amount field of the tariff) at the PSP. When the user accepts the tariff the PTP will reserve the preauth amount at the PSP and a StartSession command will be sent to the CPO. The PTP will pass an authorization_reference with this request which will be used as the mapping for the invoice (e.g. as postfix of the invoice URL).

During the session there will be session updates pushed by the CPO if existing.

16.5.1. Sender Interface

Typically implemented by market roles like: PTP.

16.5.1.3. GET Terminals Method

Fetch Terminals from a PTP system.

{payments_terminals_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]

https://www.server.com/ocpi/ptp/2.2.1/payments/terminals/?date_from=2019-01-28T12:00:00&date_to=2019-01-29T12:00:00
https://ocpi.server.com/2.2.1/payments/terminals/?offset=50
https://www.server.com/ocpi/2.2.1/payments/terminals/?date_from=2019-01-29T12:00:00&limit=100
https://www.server.com/ocpi/ptp/2.2.1/payments/terminals/?offset=50&limit=100

16.5.1.4. GET Terminal Method

If the CPO wants to check the status of a Terminal object in the PTP system, it might GET the object from the PTP system for validation purposes.

16.5.1.5. PATCH Terminal Method

This PATCH should be used by the CPO to assign location ids and/or evse_uids to a terminal. When sending both location_ids and evse_uids then both have to be considered and the sum of EVSEs will be enabled for this payment terminal.

{
    "location_ids": [
        "df37373d-1669-4127-a6ac-d86750095119",
        "a06dc823-3e5a-40c8-89cf-1b5b9e941412",
        "55719888-ed09-4cca-82cc-803bdb77bf26"
    ]
}

16.5.1.6. PUT Terminal Method

This PUT should be used by the CPO to update location data of a terminal.

{
    "customer_reference": "OMV",
    "invoice_base_url": "someNewURL",
    "last_updated": "2021-01-01T00:00:00Z"
}

16.5.1.7. POST Activate Terminal Method

This POST request should be used by the CPO to activate a terminal with needed information on the PTP side. Activation of a terminal may be needed for payment terminals integrated into a station. Here the CPO has to give the PTP needed information to link the payment terminal to the location/EVSE. This can be done for example via the serial number or other mappings sent via the reference.

{payments_terminals_endpoint_url}/activate

https://www.server.com/ocpi/ptp/2.2.1/payments/terminals/activate

{
    "terminal_id": "a06dc823-3e5a-40c8-89cf-1b5b9e941412",
    "location_ids": [
        "df37373d-1669-4127-a6ac-d86750095119"
    ],
    "reference": "Term-SerialNumber",
    "last_updated": "2019-12-10T17:16:15Z"
}

16.5.1.8. POST Deactivate Terminal Method

This POST request should be used by the CPO to deactivate a given terminal. This may be necessary when the terminal is broken or there is an address change for the given terminal.

{payments_terminals_endpoint_url}/{terminal_id}/deactivate

https://www.server.com/ocpi/ptp/2.2.1/payments/terminals/55719888-ed09-4cca-82cc-803bdb77bf26/deactivate

16.5.1.9. GET Financial Advice Confirmations Method

Fetch Financial Advice Confirmations from a PTP system.

{payments_financial_advice_confirmation_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]

https://www.server.com/ocpi/ptp/2.2.1/payments/financial-advice-confirmations/?date_from=2019-01-28T12:00:00&date_to=2019-01-29T12:00:00
https://ocpi.server.com/2.2.1/payments/financial-advice-confirmations/?offset=50
https://www.server.com/ocpi/2.2.1/payments/financial-advice-confirmations/?date_from=2019-01-29T12:00:00&limit=100
https://www.server.com/ocpi/ptp/2.2.1/payments/financial-advice-confirmations/?offset=50&limit=100

16.5.1.10. GET Financial Advice Confirmation Method

If the CPO wants to check the status of a Financial Advice Confirmation object in the PTP system, it might GET the object from the PTP system for validation purposes.

16.5.2. Receiver Interface

Typically implemented by market roles like: CPO.

16.5.2.3. GET Terminal Method

The PTP system might request the current version of a Terminal object from the CPO's system to, for example, validate the state.

16.5.2.4. POST Terminal Method

The POST should be used by the PTP to create a newly shipped terminal on the CPO's system. Here, if no activation was sent before 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 data if known through the terminal order and/or activation process.

{
    "terminal_id": "452cf8a1-79aa-4a0e-9aee-dc788586053c"
}

{
    "terminal_id": "452cf8a1-79aa-4a0e-9aee-dc788586053c",
    "address": "Street 1",
    "city": "Vienna",
    "country": "AUT",
    "coordinates": {
        "latitude": "51.047599",
        "longitude": "3.729944"
    },
    "customer_reference": "ChargePoint",
    "invoice_base_url": "https://somecompany.com/invoices",
    "invoice_creator": "CPO",
    "location_ids": [],
    "last_updated": "2018-12-10T17:16:15Z"
}

16.5.2.5. GET Financial Advice Confirmation Method

The PTP system might request the current version of a Financial Advice Confirmation from the CPO's system to, for example, validate the state.

16.5.2.6. POST Financial Advice Confirmation Method

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. The PTP has to make sure to use the same authorization_reference as provided in the Commands.StartSession so that the CPO can properly map the financial advice to the session.

{
    "id": "452cf8a1-79aa-4a0e-9aee-dc788586053c",
    "authorization_reference": "pp-100100-1948213567",
    "total_costs": {
        "excl_vat": 4.00,
        "incl_vat": 4.40
    },
    "currency": "EUR",
    "eft_data": [
        "Mastercard",
        "AID: 1234",
        "Crypto: 3456",
        "Nr: **** **** **** 1234",
        "SEQ: 00",
        "Amount: EUR 4.40"
    ],
    "capture_status_code": "SUCCESS",
    "capture_status_message": "Capture successfull at PSP",
    "last_updated": "2018-12-10T17:16:15Z"
}

16.6.1. Terminal Object

The Terminal object describes one physical payment terminal. It is designed primarily to establish a mapping between charge points (locations and/or EVSEs) and payment terminals. The object facilitates the configuration of necessary payment-related data, such as customer reference identifiers and invoice URLs.

16.6.1.1. Examples

{
    "terminal_id": "452cf8a1-79aa-4a0e-9aee-dc788586053c",
    "customer_reference": "Chargepoint",
    "address": "Street 1",
    "city": "Vienna",
    "country": "AUT",
    "coordinates": {
        "latitude": "51.047599",
        "longitude": "3.729944"
    },
    "invoice_base_url": "https://somecompany.com/invoices",
    "invoice_creator": "CPO",
    "location_ids": [],
    "last_updated": "2018-12-10T17:16:15Z"
}

{
    "terminal_id": "9e94f62c-661b-4afa-b6da-019b58fab9ac",
    "address": "Street 1",
    "city": "Vienna",
    "country": "AUT",
    "coordinates": {
        "latitude": "51.047599",
        "longitude": "3.729944"
    },
    "customer_reference": "BP",
    "invoice_base_url": "https://somecompany.com/invoices",
    "invoice_creator": "PTP",
    "location_ids": [
        "df37373d-1669-4127-a6ac-d86750095119",
        "a06dc823-3e5a-40c8-89cf-1b5b9e941412",
        "55719888-ed09-4cca-82cc-803bdb77bf26"
    ],
    "last_updated": "2018-12-10T17:16:15Z"
}

{
    "terminal_id": "9e94f62c-661b-4afa-b6da-019b58fab9ac",
    "address": "Street 1",
    "city": "Vienna",
    "country": "AUT",
    "coordinates": {
        "latitude": "51.047599",
        "longitude": "3.729944"
    },
    "customer_reference": "BP",
    "invoice_base_url": "https://somecompany.com/invoices",
    "invoice_creator": "PTP",
    "location_ids": [
        "df37373d-1669-4127-a6ac-d86750095119",
        "a06dc823-3e5a-40c8-89cf-1b5b9e941412",
        "55719888-ed09-4cca-82cc-803bdb77bf26"
    ],
    "evse_uids": [
        "17d5f8ea-8832-454f-aff5-257bc6a25353"
    ],
    "last_updated": "2018-12-10T17:16:15Z"
}

16.6.2. Financial Advice Confirmation Object

The Financial Advice Confirmation object is utilized to encapsulate the financial details of transactions processed at payment terminals. It correlates payment transactions with charging sessions by using the authorization_reference obtained from the Commands.StartSession, Session, and CDR. This reference ensures that each financial transaction can be accurately mapped to its corresponding charging session.

16.6.2.1. Examples

{
    "id": "452cf8a1-79aa-4a0e-9aee-dc788586053c",
    "authorization_reference": "pp-100100-1948213567",
    "total_costs": {
        "excl_vat": 4.00,
        "incl_vat": 4.40
    },
    "currency": "EUR",
    "eft_data": [
        "Mastercard",
        "AID: 1234",
        "Crypto: 3456",
        "Nr: **** **** **** 1234",
        "SEQ: 00",
        "Amount: EUR 4.40"
    ],
    "capture_status_code": "SUCCESS",
    "capture_status_message": "Capture successfull at PSP",
    "last_updated": "2018-12-10T17:16:15Z"
}

{
    "id": "452cf8a1-79aa-4a0e-9aee-dc788586053c",
    "authorization_reference": "pp-100100-1948213567",
    "total_costs": {
        "excl_vat": 0.00,
        "incl_vat": 0.00
    },
    "currency": "EUR",
    "capture_status_code": "FAILED",
    "capture_status_message": "Capture unsuccessful at PSP",
    "last_updated": "2018-12-10T17:16:15Z"
}

16.7.1. InvoiceCreator enum

Defines which party is responsible for creating and providing the invoice to the EV driver.

16.7.2. CaptureStatusCode enum

This enumeration describes the status of the payment capture process following a transaction at an EV charging station. It helps determine the outcome of the transaction and facilitates accurate financial reporting and customer billing.