Download OpenAPI specification:
The Sender Interface is implemented by the PTP (Payment Terminal Provider). It allows CPOs to retrieve payment terminal information and financial advice confirmations.
| status_code required | integer OCPI status code, 1000 for success. |
| status_message | string An optional status message which may help when debugging. |
| timestamp required | string <date-time> The time this message was generated. |
| data | any Response data object or list of objects. |
{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": null
}| latitude required | string <= 10 characters ^-?[0-9]{1,2}\.[0-9]{5,7}$ Latitude of the point in decimal degree. Example 50.770774. Decimal separator "." required. |
| longitude required | string <= 11 characters ^-?[0-9]{1,3}\.[0-9]{5,7}$ Longitude of the point in decimal degree. Example -126.104965. Decimal separator "." required. |
{- "latitude": "string",
- "longitude": "string"
}| Enum | Description |
|---|---|
| CPO | The CPO issues the invoice and provides it via the invoice_base_url + authorization_reference. |
| PTP | The PTP issues the invoice and directly shows/provides it the eDriver via the payment terminal. |
Defines who creates the invoice for the charging session.
"CPO"| terminal_id required | string <= 36 characters Unique ID that identifies a terminal. | ||||||
| customer_reference | string <= 36 characters This reference will be used to link the terminal to a CSMS. The reference might also be provided via the order process. | ||||||
| party_id | string = 3 characters This is an alternative to the customer reference which can be used. | ||||||
| country_code | string = 2 characters This is an alternative to the customer reference which can be used. | ||||||
| address | string <= 45 characters Street/block name and house number if available. | ||||||
| city | string <= 45 characters City or town. | ||||||
| postal_code | string <= 10 characters Postal code of the terminal, may only be omitted when the terminal has no postal code. | ||||||
| state | string <= 20 characters State or province of the location, only to be used when relevant. | ||||||
| country | string = 3 characters ISO 3166-1 alpha-3 code for the country of this location. | ||||||
object (GeoLocation) Coordinates of the terminal. | |||||||
| invoice_base_url | string <uri> BaseURL to the downloadable invoice. | ||||||
| invoice_creator | string <enum> (InvoiceCreator)
Describes which party creates the invoice for the eDriver. | ||||||
| reference | string <= 36 characters Mapping value as issued by the PTP(e.g serial number). | ||||||
| location_ids | Array of strings[ items <= 36 characters ] List of all locations assigned to that terminal. | ||||||
| evse_uids | Array of strings[ items <= 36 characters ] List of all EVSEs assigned to that terminal. | ||||||
| last_updated required | string <date-time> Timestamp when this Terminal was last updated (or created). |
{- "terminal_id": "string",
- "customer_reference": "string",
- "party_id": "str",
- "country_code": "st",
- "address": "string",
- "city": "string",
- "postal_code": "string",
- "state": "string",
- "country": "str",
- "coordinates": {
- "latitude": "string",
- "longitude": "string"
}, - "invoice_creator": "CPO",
- "reference": "string",
- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
], - "last_updated": "2019-08-24T14:15:22Z"
}| location_ids | Array of strings[ items <= 36 characters ] |
| evse_uids | Array of strings[ items <= 36 characters ] |
{- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
]
}| terminal_id | string <= 36 characters Unique ID that identifies a terminal. Optional for activation as it will be set by the PTP. | ||||||
| customer_reference | string <= 36 characters This reference will be used to link the terminal to a CSMS. The reference might also be provided via the order process. | ||||||
| party_id | string <= 3 characters This is an alternative to the customer reference which can be used. | ||||||
| country_code | string <= 2 characters This is an alternative to the customer reference which can be used. | ||||||
| address | string <= 45 characters Street/block name and house number if available. | ||||||
| city | string <= 45 characters City or town. | ||||||
| postal_code | string <= 10 characters Postal code of the terminal, may only be omitted when the terminal has no postal code. | ||||||
| state | string <= 20 characters State or province of the location, only to be used when relevant. | ||||||
| country | string <= 3 characters ISO 3166-1 alpha-3 code for the country of this location. | ||||||
object (GeoLocation) Coordinates of the terminal. | |||||||
| invoice_base_url | string <uri> BaseURL to the downloadable invoice. | ||||||
| invoice_creator | string <enum> (InvoiceCreator)
Describes which party creates the invoice for the eDriver. | ||||||
| reference | string <= 36 characters Mapping value as issued by the PTP(e.g serial number). | ||||||
| location_ids | Array of strings[ items <= 36 characters ] List of all locations assigned to that terminal. | ||||||
| evse_uids | Array of strings[ items <= 36 characters ] List of all EVSEs assigned to that terminal. | ||||||
| last_updated required | string <date-time> Timestamp when this Terminal was last updated (or created). |
{- "terminal_id": "string",
- "customer_reference": "string",
- "party_id": "str",
- "country_code": "st",
- "address": "string",
- "city": "string",
- "postal_code": "string",
- "state": "string",
- "country": "str",
- "coordinates": {
- "latitude": "string",
- "longitude": "string"
}, - "invoice_creator": "CPO",
- "reference": "string",
- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
], - "last_updated": "2019-08-24T14:15:22Z"
}| name required | string A description of the tax. In countries where a tax name is required like Canada this can be something like "QST". In countries where this is not required, this can be something more generic like "VAT" or "General Sales Tax". |
| account_number | string Tax Account Number of the business entity remitting these taxes. Optional as this is not required in all countries. |
| percentage | number Tax percentage. Optional as this is not required in all countries. |
| amount required | number The amount of money of this tax that is due. |
{- "name": "string",
- "account_number": "string",
- "percentage": 0,
- "amount": 0
}| before_taxes required | number Price/Cost excluding taxes. |
Array of objects (TaxAmount) All taxes that are applicable to this price and relevant to the receiver of the Session or CDR. |
{- "before_taxes": 0,
- "taxes": [
- {
- "name": "string",
- "account_number": "string",
- "percentage": 0,
- "amount": 0
}
]
}| Enum | Description |
|---|---|
| SUCCESS | Indicates that the payment capture was completed successfully without any issues. Funds were secured and will be settled according to the payment processor's timeline. This status confirms that all checks (e.g., fraud, card validation) passed and the transaction was approved. |
| PARTIAL_SUCCESS | Used when only part of the transaction amount was approved or when certain conditions of the payment were altered during processing. This might occur in scenarios where the available balance was insufficient for the full requested amount, or specific transaction limits were enforced by the card issuer. |
| FAILED | Indicates that the payment capture attempt was unsuccessful. This failure can be due to various reasons such as insufficient funds, card expiration, network issues, or refusal by the card issuer. |
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.
"SUCCESS"| id required | string <= 36 characters Unique ID that identifies a financial advice confirmation. | ||||||||
| authorization_reference required | string <= 36 characters Reference to the authorization given by the PTP in the Commands.StartSession. | ||||||||
required | object (Price) Real amount that was captured at the PSP. This is a consumer price with VAT. | ||||||||
| currency required | string = 3 characters ISO-4217 code of the currency of this tariff. | ||||||||
| eft_data required | Array of strings non-empty [ items <= 255 characters ] Invoice relevant data from the direct payment. | ||||||||
| capture_status_code required | string <enum> (CaptureStatusCode)
Code that identifies the financial advice status. | ||||||||
| capture_status_message | string <= 255 characters Message about any error at the financial advice. | ||||||||
| last_updated required | string <date-time> Timestamp when this financial advice confirmation was last updated (or created). |
{- "id": "string",
- "authorization_reference": "string",
- "total_costs": {
- "before_taxes": 0,
- "taxes": [
- {
- "name": "string",
- "account_number": "string",
- "percentage": 0,
- "amount": 0
}
]
}, - "currency": "str",
- "eft_data": [
- "string"
], - "capture_status_code": "SUCCESS",
- "capture_status_message": "string",
- "last_updated": "2019-08-24T14:15:22Z"
}Fetch a paginated list of Terminal objects. If date_from and/or date_to are provided, only Terminals with last_updated between the given dates will be returned.
| date_from | string <date-time> Only return objects that have last_updated after or equal to this Date/Time (inclusive). |
| date_to | string <date-time> Only return objects that have last_updated up to this Date/Time, but not including (exclusive). |
| offset | integer >= 0 Default: 0 The offset of the first object returned. Default is 0. |
| limit | integer >= 1 Maximum number of objects to GET. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": [
- {
- "terminal_id": "string",
- "customer_reference": "string",
- "party_id": "str",
- "country_code": "st",
- "address": "string",
- "city": "string",
- "postal_code": "string",
- "state": "string",
- "country": "str",
- "coordinates": {
- "latitude": "string",
- "longitude": "string"
}, - "invoice_creator": "CPO",
- "reference": "string",
- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
], - "last_updated": "2019-08-24T14:15:22Z"
}
]
}Retrieve a specific Terminal object.
| terminal_id required | string <= 36 characters Terminal.terminal_id of the Terminal object. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": {
- "terminal_id": "string",
- "customer_reference": "string",
- "party_id": "str",
- "country_code": "st",
- "address": "string",
- "city": "string",
- "postal_code": "string",
- "state": "string",
- "country": "str",
- "coordinates": {
- "latitude": "string",
- "longitude": "string"
}, - "invoice_creator": "CPO",
- "reference": "string",
- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
], - "last_updated": "2019-08-24T14:15:22Z"
}
}Update a Terminal object with new information. The terminal_id is provided via the URL path parameter.
| terminal_id required | string <= 36 characters Terminal.terminal_id of the Terminal object. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
| terminal_id required | string <= 36 characters Unique ID that identifies a terminal. | ||||||
| customer_reference | string <= 36 characters This reference will be used to link the terminal to a CSMS. The reference might also be provided via the order process. | ||||||
| party_id | string = 3 characters This is an alternative to the customer reference which can be used. | ||||||
| country_code | string = 2 characters This is an alternative to the customer reference which can be used. | ||||||
| address | string <= 45 characters Street/block name and house number if available. | ||||||
| city | string <= 45 characters City or town. | ||||||
| postal_code | string <= 10 characters Postal code of the terminal, may only be omitted when the terminal has no postal code. | ||||||
| state | string <= 20 characters State or province of the location, only to be used when relevant. | ||||||
| country | string = 3 characters ISO 3166-1 alpha-3 code for the country of this location. | ||||||
object (GeoLocation) Coordinates of the terminal. | |||||||
| invoice_base_url | string <uri> BaseURL to the downloadable invoice. | ||||||
| invoice_creator | string <enum> (InvoiceCreator)
Describes which party creates the invoice for the eDriver. | ||||||
| reference | string <= 36 characters Mapping value as issued by the PTP(e.g serial number). | ||||||
| location_ids | Array of strings[ items <= 36 characters ] List of all locations assigned to that terminal. | ||||||
| evse_uids | Array of strings[ items <= 36 characters ] List of all EVSEs assigned to that terminal. | ||||||
| last_updated required | string <date-time> Timestamp when this Terminal was last updated (or created). |
{- "terminal_id": "string",
- "customer_reference": "string",
- "party_id": "str",
- "country_code": "st",
- "address": "string",
- "city": "string",
- "postal_code": "string",
- "state": "string",
- "country": "str",
- "coordinates": {
- "latitude": "string",
- "longitude": "string"
}, - "invoice_creator": "CPO",
- "reference": "string",
- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
], - "last_updated": "2019-08-24T14:15:22Z"
}{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": null
}Partially update a Terminal, for example to assign locations or EVSEs.
| terminal_id required | string <= 36 characters Terminal.terminal_id of the Terminal object. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
| location_ids | Array of strings[ items <= 36 characters ] |
| evse_uids | Array of strings[ items <= 36 characters ] |
{- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
]
}{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": null
}Request to activate a payment terminal.
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
| terminal_id | string <= 36 characters Unique ID that identifies a terminal. Optional for activation as it will be set by the PTP. | ||||||
| customer_reference | string <= 36 characters This reference will be used to link the terminal to a CSMS. The reference might also be provided via the order process. | ||||||
| party_id | string <= 3 characters This is an alternative to the customer reference which can be used. | ||||||
| country_code | string <= 2 characters This is an alternative to the customer reference which can be used. | ||||||
| address | string <= 45 characters Street/block name and house number if available. | ||||||
| city | string <= 45 characters City or town. | ||||||
| postal_code | string <= 10 characters Postal code of the terminal, may only be omitted when the terminal has no postal code. | ||||||
| state | string <= 20 characters State or province of the location, only to be used when relevant. | ||||||
| country | string <= 3 characters ISO 3166-1 alpha-3 code for the country of this location. | ||||||
object (GeoLocation) Coordinates of the terminal. | |||||||
| invoice_base_url | string <uri> BaseURL to the downloadable invoice. | ||||||
| invoice_creator | string <enum> (InvoiceCreator)
Describes which party creates the invoice for the eDriver. | ||||||
| reference | string <= 36 characters Mapping value as issued by the PTP(e.g serial number). | ||||||
| location_ids | Array of strings[ items <= 36 characters ] List of all locations assigned to that terminal. | ||||||
| evse_uids | Array of strings[ items <= 36 characters ] List of all EVSEs assigned to that terminal. | ||||||
| last_updated required | string <date-time> Timestamp when this Terminal was last updated (or created). |
{- "terminal_id": "string",
- "customer_reference": "string",
- "party_id": "str",
- "country_code": "st",
- "address": "string",
- "city": "string",
- "postal_code": "string",
- "state": "string",
- "country": "str",
- "coordinates": {
- "latitude": "string",
- "longitude": "string"
}, - "invoice_creator": "CPO",
- "reference": "string",
- "location_ids": [
- "string"
], - "evse_uids": [
- "string"
], - "last_updated": "2019-08-24T14:15:22Z"
}{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": null
}Request to deactivate a payment terminal.
| terminal_id required | string <= 36 characters Terminal.terminal_id of the Terminal object. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": null
}Fetch a paginated list of FinancialAdviceConfirmation objects.
| date_from | string <date-time> Only return objects that have last_updated after or equal to this Date/Time (inclusive). |
| date_to | string <date-time> Only return objects that have last_updated up to this Date/Time, but not including (exclusive). |
| offset | integer >= 0 Default: 0 The offset of the first object returned. Default is 0. |
| limit | integer >= 1 Maximum number of objects to GET. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": [
- {
- "id": "string",
- "authorization_reference": "string",
- "total_costs": {
- "before_taxes": 0,
- "taxes": [
- {
- "name": "string",
- "account_number": "string",
- "percentage": 0,
- "amount": 0
}
]
}, - "currency": "str",
- "eft_data": [
- "string"
], - "capture_status_code": "SUCCESS",
- "capture_status_message": "string",
- "last_updated": "2019-08-24T14:15:22Z"
}
]
}Retrieve a specific FinancialAdviceConfirmation object.
| financial_advice_confirmation_id required | string <= 36 characters FinancialAdviceConfirmation.id of the FinancialAdviceConfirmation object. |
| X-Request-ID required | string Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. |
| X-Correlation-ID required | string Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value). |
| OCPI-from-country-code | string = 2 characters 'country code' of the connected party this message is sent from. |
| OCPI-from-party-id | string = 3 characters 'party id' of the connected party this message is sent from. |
| OCPI-to-country-code | string = 2 characters 'country code' of the connected party this message is to be sent to. |
| OCPI-to-party-id | string = 3 characters 'party id' of the connected party this message is to be sent to. |
{- "status_code": 1000,
- "status_message": "string",
- "timestamp": "2019-08-24T14:15:22Z",
- "data": {
- "id": "string",
- "authorization_reference": "string",
- "total_costs": {
- "before_taxes": 0,
- "taxes": [
- {
- "name": "string",
- "account_number": "string",
- "percentage": 0,
- "amount": 0
}
]
}, - "currency": "str",
- "eft_data": [
- "string"
], - "capture_status_code": "SUCCESS",
- "capture_status_message": "string",
- "last_updated": "2019-08-24T14:15:22Z"
}
}