OCPI 2.3.0 - Payments Module - Receiver Interface (2.3.0)

Download OpenAPI specification:

The Receiver Interface is implemented by the CPO. It allows the PTP to push Terminal information and Financial Advice Confirmations to the CPO.

OCPI 2.3.0 Specification

Schemas

OCPIResponse

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
}

GeoLocation

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"
}

InvoiceCreator

string <enum> (InvoiceCreator)

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

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)

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.

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_base_url": "http://example.com",
"invoice_creator": "CPO",
"reference": "string",
"location_ids": ["string"
],
"evse_uids": ["string"
],
"last_updated": "2019-08-24T14:15:22Z"
}

TaxAmount

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
}

Price

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
}
]
}

CaptureStatusCode

string <enum> (CaptureStatusCode)

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"

FinancialAdviceConfirmation

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)

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.

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"
}

Payments

Retrieve a Terminal

Retrieve a Terminal as stored in the CPO's system.

Authorizations:

ocpiAuthorization

path Parameters

terminal_id

required

string <= 36 characters

Terminal.terminal_id of the Terminal object.

header Parameters

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.

Responses

Response samples

Content type

application/json

{"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_base_url": "http://example.com",
"invoice_creator": "CPO",
"reference": "string",
"location_ids": ["string"
],
"evse_uids": ["string"
],
"last_updated": "2019-08-24T14:15:22Z"
}
}

Create a Terminal

The PTP pushes a new Terminal object to the CPO.

Authorizations:

ocpiAuthorization

header Parameters

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.

Request Body schema: application/json
required

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)

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.

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).

Responses

Request samples

Payload

Content type

application/json

{"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_base_url": "http://example.com",
"invoice_creator": "CPO",
"reference": "string",
"location_ids": ["string"
],
"evse_uids": ["string"
],
"last_updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type

application/json

{"status_code": 1000,
"status_message": "string",
"timestamp": "2019-08-24T14:15:22Z",
"data": null
}

Retrieve a Financial Advice Confirmation

Retrieve a FinancialAdviceConfirmation as stored in the CPO's system.

Authorizations:

ocpiAuthorization

path Parameters

financial_advice_confirmation_id

required

string <= 36 characters

FinancialAdviceConfirmation.id of the FinancialAdviceConfirmation object.

header Parameters

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.

Responses

Response samples

Content type

application/json

{"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"
}
}

Create a Financial Advice Confirmation

The PTP pushes a new FinancialAdviceConfirmation to the CPO.

Authorizations:

ocpiAuthorization

header Parameters

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.

Request Body schema: application/json
required

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)

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.

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).

Responses

Request samples

Payload

Content type

application/json

{"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"
}

Response samples

Content type

application/json

{"status_code": 1000,
"status_message": "string",
"timestamp": "2019-08-24T14:15:22Z",
"data": null
}

OCPI 2.3.0 - Payments Module - Receiver Interface (2.3.0)

Schemas

OCPIResponse

GeoLocation

InvoiceCreator

Terminal

TaxAmount

Price

CaptureStatusCode

FinancialAdviceConfirmation

Payments

Retrieve a Terminal

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Create a Terminal

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Retrieve a Financial Advice Confirmation

Authorizations:

path Parameters

header Parameters

Responses

Response samples

Create a Financial Advice Confirmation

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required