Introduction

In this document, Compleo explains which functions are important for a backend provider when using a payment terminal and, if necessary, which should be implemented to ensure convenient operation for CPOs.

Hardware

DUO IMS PT

eTower 200

Structure

The structure of communication is displayed in Figure 1.

Each charging station can communicate with the backend and the receipt server via the Internet. Local communication takes place with the payment terminal in order to process all payment transactions.

Change tariff

The communication channel for a tariff change is described below. A graphical overview can be found in Figure 2.
In this case, the user is the operator of the charging stations and can trigger the tariff change by changing the backend. Tariff changes only become binding if no charging process is active.

After the charging station has received a new tariff, this will be displayed and applied from the next charging process, provided that the validity defined in the message has been reached

Alternatively tariffs can be changed via OCPP Configuration Keys and the ChangeConfiguration command.

OCPP Data transfer

The OCPP message "DataTransfer" is divided into several objects. At the beginning of the message is the "vendorId" and the "messageId". This is followed by the "data" object. This contains the "id", "validFrom" and "restrictions" attribute. The "elements" objects form the end of the "data" object. These consist of "type", "currency", "grossAmount", "vat" and "restrictions".
Some of these details are mandatory fields. Mandatory fields must always be present in the payload. Optional fields are not available in the payload.

{
    "vendorId": "com.compleo-cs",
    "messageId": "tariff",
    "data": {
        "id": "UUID",
        "validFrom": "2022-01-01T00:00:00.000Z",
        "restrictions": {
            "maxGrossCostByTimeWithMinDuration": 11.9
        },
	  "payment": {
            "preAuthorizationAmount": 25.0
        },
        "elements": [
            {
                "type": "FIXED",
                "currency": "EUR",
                "grossAmount": 10,
                "vat": 19,
                "restrictions": {
                    "startTime": "00:00",
                    "endTime": "00:00",
                    "days": [
                        "EVERY_DAY"
                    ],
                    "connectorId": [
                        1,
                        2
                    ]
                }
            },
            {
                "type": "TIME",
                "currency": "EUR",
                "grossAmount": 1,
                "vat": 19,
                "restrictions": {
                    "startTime": "00:00",
                    "endTime": "00:00",
                    "days": [
                        "EVERY_DAY"
                    ],
                    "connectorId": [
                        1,
                        2
                    ]
                }
            },
{
                "type": "ENERGY",
                "currency": "EUR",
                "grossAmount": 0.58,
                "vat": 19,
                "restrictions": {
                    "startTime": "00:00",
                    "endTime": "00:00",
                    "days": [
                        "EVERY_DAY"
                    ],
                    "connectorId": [
                        1,
                        2
                    ]
                }
            },
            {
                "type": "TIME_WITH_MIN_DURATION",
                "currency": "EUR",
                "grossAmount": 0.1,
                "vat": 19,
                "restrictions": {
                    "startTime": "00:00",
                    "endTime": "00:00",
                    "days": [
                        "EVERY_DAY"
                    ],
                    "connectorId": [
                        1,
                        2
                    ],
                    "minDuration": 60
                }
            }
        ]
    }
}

The following tables show the objects of the JSON message as well as the corresponding description of the general "data", "restrictions" and "elements" objects.

General data

General data is stored in this part of the message. There are different types of “messageId”. Only the mess

ageId “tariff” is dealt with here.

Name	Required	Implemented	Description
vendorId	YES	YES	Identification of operator
messageId	YES	YES	Type of message ID
data	YES	YES	‘data’ Object

For a better overview, there is also a graphical representation of the object. This shows the subdivision of the individual objects.

‘data’ object

The “data” object now contains a UUID with which the message is referenced. This means that every payload sent can be traced.

Name	Required	Implemented	Description
id	YES	YES	UUID, for Payload reference
validFrom	NO	NO	From when tariff valid Default: Timestamp „Now“
restrictions	NO	YES	see chapter
payment	NO	YES	see chapter
elements	YES	YES	see chapter

‘restrictions’ object

The “restrictions” object can occur in both the “data” and the “elements” object. The “restrictions” object can contain different information in both cases. If information is inadvertently classified incorrectly, it cannot be processed by the corresponding location.

Name	Required	Implemented	Description
maxGrossCostByTimeWithMinDuration	NO	YES	max blocking amount

The ‘restrictions' of the 'elements’ object look different and are shown below.

Name	Required	Implemented	Description
startTime	YES	NO	start time tariff ISO 8601 Default: 00:00
endTime	YES	NO	end time tariff ISO 8601 Default: 00:00
days	YES	NO	days when tariff applies values: „MONDAY“, „TUESDAY“, „WEDNESDAY“,„THURSDAY“, „FRIDAY“, „SATURDAY“,„SUNDAY“, „EVERY_DAY“ Default: “EVERY_DAY“
connectorId	YES	YES
minDuration	YES	YES	Start of time costing

The “connectorId” corresponds to the charging point of a charging station. The “connectorId” can either be a single value or several values. This means that a separate setting can be made for each charging point by adding another “elements” object.

For example, it is possible to assign a different price per kWh to the left charging point of a charging station. It is also possible for the left charging point to be assigned a “FIXED” element but the right charging point is not assigned this element and therefore the flat rate defined in the “FIXED” element only has to be paid at the left charging point.

‘payment’ object

The amount of the pre-authorization is determined in the “payment” object. This amount determines how much money is reserved in the customer account. The default value here is €25.

Name	Required	Implemented	Description
preAuthorizationAmount	NO	YES

‘elements’ object

The “elements” object can contain several types of messages A distinction is made between the types “ENERGY”, “TIME_WITH_MIN_DURATION”, “TIME” and “FIXED”.
“ENERGY” is the price per kilowatt hour (KWH) to be paid at the charging station.
“TIME_WITH_MIN_DURATION” represents the usage fee. The time is defined with “minDuration”. If it is exceeded, the customer pays the defined amount in addition to the charged electricity from “ENERGY”. The amount is added every minute. This field can only be set if the “ENERGY” field is also set.
The “Energy” and “TIME_WITH_MIN_DURATION” tariffs can be combined with each other.

Name	Required	Implemented	Description
type	YES	in parts Teil	type of tariff to be changed „ENERGY“, „TIME_WITH_MIN_DURATION“, “TIME” or “FIXED”
currency	YES	YES	currency (ISO 4217)
grossAmount	YES	YES	gross amount
vat	YES	YES	tax percentage
restrictions	YES	YES

Sample Data

A DataTransfer is sent after successful authorization at the payment terminal but before the Authorize message. The final DataTransfer, at the end of the loading process, is sent when the amount of the load has been successfully booked.
If the backend does not accept the DataTransfers, the service continues. Only the Authorize message with the SAMId must be accepted, otherwise the loading process cannot be started.

DataTransfer after authorize: 
[2, "60970052-8a74-4259-9ebd-9178c875322f", "DataTransfer", {
   "vendorId":"CompleoPayController",
   "messageId":"PaymentNotification",
   "data":{
      "Type":"Authorization",
      "PaymentId":"0028882023",
      "SAMId":"PY450001030028882023",
      "ReceiptData":{
         "TerminalId":"45000103",
         "TraceId":"002888",
         "Time":"2023-02-08T14:45:58",
         "Amount":25.0,
         "Currency":"EUR",
         "AID":"3838393135300000",
         "PaymentType":"PinPayment",
         "CardType":"MasterCard",
         "PAN":"0010",
         "VUNumber":"455600000599   "
      }
   }
}]


DataTransfer after booking:
[2, "370f43d1-b59a-4b74-a97c-e24e44f0dbc3", "DataTransfer", {
   "vendorId":"CompleoPayController",
   "messageId":"PaymentNotification",
   "data":{
      "Type":"Booking",
      "PaymentId":"0028882023",
      "SAMId":"PY450001030028882023",
      "ReceiptData":{
         "TerminalId":"45000103",
         "TraceId":"002888",
         "Time":"2023-02-08T15:19:21",
         "Amount":6.06,
         "Currency":"EUR",
         "AID":"3838393135300000",
         "PaymentType":"PinPayment",
         "CardType":"MasterCard",
         "PAN":"0010",
         "VUNumber":"455600000599   "
      }
   }
}]

Paymenttoken

If a third-party backend wants to support payment, it must implement a payment token. This token informs the backend that authorization via payment has taken place. This payment token is sent with an "Authorize" message in accordance with OCPP and expects an "Accepted" message in the OCPP response. The choice of token is the responsibility of the third-party backend and must be exchanged and agreed with product management.

If, for example, the third-party backend chooses the payment token "ABCDE", the checkout application expects the following exchange of OCPP messages:

SEND: [2, "5061ad9c-f7fc-433a-a5e3-baacf4f7232b", "Authorize", {"id	Tag": "ABCDE"}]

RECV: [3,"5061ad9c-f7fc-433a-a5e3-baacf4f7232b",{"idTagInfo":	{"status":"Accepted"}}]

The payment token described above is replaced by the SAMId in the model with additional information. The SAMId is made up of the prefix "PY", the TerminalId, the TraceId and the current year. The exact meaning of the components is explained below. As the SAMId changes with each loading process, the Authorize message does not have to check the complete token, but only the prefix "PY".

Bezeichnung	Beschreibung
TerminalId	Identification of the payment terminal at the payment service provider
TraceId	Payment transaction number
Time	Time at the start and end of the transaction
Amount	Amount of the pre-authorization and booking amount
Currency	Currency of the transaction
AID	Card-specific information
PaymentType	Information about the payment terminal
CardType	Card type
PAN	The last 4 digits of the card used
VUNumber	Card-specific information

Configuration-Keys

Key	Description	Unit	Type	Access

Key	Description	Unit	Type	Access
PaymentTerminalId	You will receive the terminal ID from your payment service provider after you have provided them with the terminal's serial number.	-	String (8 characters)	r/w
PaymentTerminalSerialNumber	Serial number of the credit card terminal; is only set automatically if the content of the terminal's system printout can be parsed.	-	String	r/w
PaymentToken	Token that marks the charging process as a payment charging process in the CPO backend. Maximum of 20 characters for this value. There are several predefinied parameter options available. "<TermId>", payment terminal id, length: 8 characters "<TrId>", transaction number, length: 6 characters "<Yr>", current year, length: 4 characters Valid tokens are for example: "PY<TermId><TrId><Yr>" or "1234$<TrId><Yr>"	-	String (<= 20 characters)	r/w
PaymentServiceProvider	The configured terminal provider is used to determine the password of the payment terminal.	-	String	r/o
PSPHostIPPort	This port is used by the payment terminal when communicating with the Payment Service Provider's server. If 0 is configured, the port preconfigured in the terminal is used. When using the Payment Service Provider Telecash, the port must be specified here.	-	Integer (>= 0)	r/w
SendPaymentDataViaOCPP	This can be activated if the backend operator supports the processing of receipt data in the backend. This requires the implementation of a specific interface.	-	Boolean	r/w
EndOfDayTime	Time at which the daily closeout is performed.	-	Time. Format: hh:mm	r/w
MerchantCompanyName	Appears on the receipt.	-	String	r/w
MerchantCompanyStreet	Appears on the receipt.	-	String	r/w
MerchantCompanyZIP	Appears on the receipt.	-	String	r/w
MerchantCompanyCity	Appears on the receipt.	-	String	r/w
MerchantCompanyTaxId	Appears on the receipt.	-	String	r/w
StationCity	City in which the charging station is located. Appears on the receipt.	-	String	r/w
ReceiptURL	URL der Webseite, auf der der Kunde seinen Beleg abrufen/suchen kann.	-	String	r/w
ReceiptServerHostname	The receipt server hostname is used for the receipt communication. It is supplemented by "/api/receipt-service/v1/charging-points/<UUID of the charging point>/receipts" for transfering the receipt data.	-	String	r/w
ReceiptServerUsername	Username for logging in to the receipt server.	-	String	r/w
ReceiptServerPassword	Password for logging in to the receipt server.	-	String	r/w
ReceiptNameConnectorId<ConnectorId>	The charging point name appears at the top of the receipt under "Ladestation" (German for charging station) and helps to identify the charging point. If no name has been specified by the backend operator, the name can be freely selected.	-	String	r/w
ReceiptUUIDConnectorId<ConnectorId>	Unique ID of the charging point generated in the backend and used to send the receipts. Initially, the charging station generates a UUID that is used until it is overwritten with the UUID requested by the backend, if necessary. In ENTERPRISE, the UUID is used to assign the receipt to the charging point created in the backend and is therefore mandatory there.	-	String	r/w
PricePerkWhConnectorId<ConnectorId>	Gross price per kWh in the largest unit of currency (e.g. €).	Largest currency unit, e.g. €	Decimal (>= 0)	r/w
PricePerMinuteConnectorId<ConnectorId>	Gross price per minute after the free parking duration in the largest unit of currency (e.g. €), also called blocking fee.	Largest currency unit, e.g. €	Decimal (>= 0)	r/w
FreeParkingTimeConnectorId<ConnectorId>	Charging duration in minutes, after which the price per minute applies.	min	Integer (>= 0)	r/w
MaxBlockingAmountConnectorId<ConnectorId>	Maximum gross costs in the largest unit of currency (e.g. €) that can accumulate due to the price per minute.	Largest currency unit, e.g. €	Decimal (>= 0)	r/w
PreAuthorizationAmount	Reserved at the time of authorization and offset against the actual cost upon completion of the charging process. Specify as a decimal in the currency used. Default: 50 (= 50,00 €, if € is selected as currency) Maximum value: 1.000, higher entries will be rejected.	Largest currency unit, e.g. €	Decimal (>= 0)	r/w
TariffCurrency	Currency in which the prices are given.	-	String (resp. Enum), Permitted values: "EUR" (further currencies will follow)	r/w
VATEnergy	Value added tax of the tariff for charged energy.	%	Decimal (>= 0)	r/w
VATDuration	Value added tax included in the price per minute.	%	Decimal (>= 0)	r/w

Additional Connections for APNs

Compleo AG has integrated Feig payment terminals into its products as part of the charging station ordinance. The operation of the terminals in stations in which only one SIM card is used must be made possible via this card. When using public SIM cards, this can easily be made possible. When using APN SIM cards, each provider must check whether these connections are possible. If it is not possible to enable these connections for the operation of the payment terminals.

Depending on the payment service provider, the following connections must be enabled:

Netzbetreiber	Produktivsystem (IP:Port)
VR-Payment	195.35.87.72:12503
BSPayone	195.200.194.138: 60260 (alt) 195.200.194.138:10420 (neu)
Telecash	217.73.32.104 (prod) 217.73.32.105 (backup) Port 52815-52838
Lavego	213.183.19.105:30001
PayServ.GWS	193.33.23.54:37687

The following URL must be released for the Compleo Digital Receipt document server:

System	URL	Produktivsystem (IP:Port)
Test	Staging.tms.feig.de	195.185.213.139:443
Produktiv	Tms.feig.de	195.185.213.141:443

The following URL must be released for the Compleo Digital Receipt document server:

System	URL	Produktivsystem (IP:Port)
EV Beleg	https://ev-beleg.de	51.105.156.66:443
Wallbe Hub	https://wallbe-hub.com	51.105.156.66:443

Checklist

Select your PSP

Select your Backend

Payment token verified with Backend provider

Connection Method selected

<Back

APN SIM	Public Internet
Enable routing to PSP	Connection to backend secured
Enable routing to Feig TMS

Compleo Knowledgebase

System documentation Integrated Payment Terminal

Analytics