OCPP 2.1 Schemas — TariffAndCost

Functional Block: I

Types Reference: Shared types referenced below are defined in OCPP-2.1-DataTypes.md.
Types used only within this block are documented inline below.

#Messages

CostUpdated (CSMS → CS)
GetTariffs (CSMS → CS)
SetDefaultTariff (CSMS → CS)
ChangeTransactionTariff (CSMS → CS)
ClearTariffs (CSMS → CS)
NotifySettlement (CS → CSMS)
NotifyWebPaymentStarted (CSMS → CS)
VatNumberValidation (CS → CSMS)

#CostUpdated

Direction: CSMS → CS

#CostUpdatedRequest

Field	Type	Required	Constraints	Description
`totalCost`	number	Yes		Current total cost, based on the information known by the CSMS, of the transaction including taxes. In the currency configured with the configuration Variable: [Currency]
`transactionId`	string	Yes	maxLength: 36	Transaction Id of the transaction the current cost are asked for.
`customData`	CustomDataType	No

Example CostUpdatedRequest

{
  "totalCost": 0.0,
  "transactionId": "string"
}

#CostUpdatedResponse

No required fields. An empty {} is a valid response.

#GetTariffs

Direction: CSMS → CS

#GetTariffsRequest

Field	Type	Required	Constraints	Description
`evseId`	integer	Yes	min: 0.0	EVSE id to get tariff from. When evseId = 0, this gets tariffs from all EVSEs.
`customData`	CustomDataType	No

Example GetTariffsRequest

{
  "evseId": 0
}

#GetTariffsResponse

Field	Type	Required	Constraints
`status`	TariffGetStatusEnumType	Yes
`statusInfo`	StatusInfoType	No
`tariffAssignments`	TariffAssignmentType[]	No	minItems: 1
`customData`	CustomDataType	No

#SetDefaultTariff

Direction: CSMS → CS

#SetDefaultTariffRequest

Field	Type	Required	Constraints	Description
`evseId`	integer	Yes	min: 0.0	EVSE that tariff applies to. When evseId = 0, then tarriff applies to all EVSEs.
`tariff`	TariffType	Yes
`customData`	CustomDataType	No

Example SetDefaultTariffRequest

{
  "evseId": 0,
  "tariff": {
    "tariffId": "string",
    "currency": "string"
  }
}

#SetDefaultTariffResponse

Field	Type	Required
`status`	TariffSetStatusEnumType	Yes
`statusInfo`	StatusInfoType	No
`customData`	CustomDataType	No

#ChangeTransactionTariff

Direction: CSMS → CS

#ChangeTransactionTariffRequest

Field	Type	Required	Constraints	Description
`tariff`	TariffType	Yes
`transactionId`	string	Yes	maxLength: 36	Transaction id for new tariff.
`customData`	CustomDataType	No

Example ChangeTransactionTariffRequest

{
  "tariff": {
    "tariffId": "string",
    "currency": "string"
  },
  "transactionId": "string"
}

#ChangeTransactionTariffResponse

Field	Type	Required
`status`	TariffChangeStatusEnumType	Yes
`statusInfo`	StatusInfoType	No
`customData`	CustomDataType	No

#ClearTariffs

Direction: CSMS → CS

#ClearTariffsRequest

Field	Type	Required	Constraints	Description
`evseId`	integer	No	min: 0.0	When present only clear tariffs matching tariffIds at EVSE evseId.
`tariffIds`	string[]	No	minItems: 1	List of tariff Ids to clear. When absent clears all tariffs at evseId.
`customData`	CustomDataType	No

#ClearTariffsResponse

Field	Type	Required	Constraints	Description
`clearTariffsResult`	ClearTariffsResultType[]	Yes	minItems: 1
`customData`	CustomDataType	No

#NotifySettlement

Direction: CS → CSMS

#NotifySettlementRequest

Field	Type	Required	Constraints	Description
`pspRef`	string	Yes	maxLength: 255	The payment reference received from the payment terminal and is used as the value for idToken.
`settlementAmount`	number	Yes		The amount that was settled, or attempted to be settled (in case of failure).
`settlementTime`	string (date-time)	Yes		The time when the settlement was done.
`status`	PaymentStatusEnumType	Yes
`receiptId`	string	No	maxLength: 50
`receiptUrl`	string	No	maxLength: 2000	The receipt URL, to be used if the receipt is generated by the payment terminal or the CS.
`statusInfo`	string	No	maxLength: 500	Additional information from payment terminal/payment process.
`transactionId`	string	No	maxLength: 36	The transactionId that the settlement belongs to. Can be empty if the payment transaction is canceled prior to the start of the OCPP transaction.
`vatCompany`	AddressType	No
`vatNumber`	string	No	maxLength: 20	VAT number for a company receipt.
`customData`	CustomDataType	No

Example NotifySettlementRequest

{
  "pspRef": "string",
  "settlementAmount": 0.0,
  "settlementTime": "2024-01-15T10:30:00Z",
  "status": "Settled"
}

#NotifySettlementResponse

Field	Type	Required	Constraints	Description
`receiptId`	string	No	maxLength: 50	The receipt id if the receipt is generated by CSMS.
`receiptUrl`	string	No	maxLength: 2000	The receipt URL if receipt generated by CSMS. The Charging Station can QR encode it and show it to the EV Driver.
`customData`	CustomDataType	No

No fields are required. An empty {} is a valid response.

#NotifyWebPaymentStarted

Direction: CSMS → CS

#NotifyWebPaymentStartedRequest

Field	Type	Required	Constraints	Description
`evseId`	integer	Yes	min: 0.0	EVSE id for which transaction is requested.
`timeout`	integer	Yes		Timeout value in seconds after which no result of web payment process (e.g. QR code scanning) is to be expected anymore.
`customData`	CustomDataType	No

Example NotifyWebPaymentStartedRequest

{
  "evseId": 0,
  "timeout": 0
}

#NotifyWebPaymentStartedResponse

No required fields. An empty {} is a valid response.

#VatNumberValidation

Direction: CS → CSMS

#VatNumberValidationRequest

Field	Type	Required	Constraints	Description
`vatNumber`	string	Yes	maxLength: 20	VAT number to check.
`evseId`	integer	No	min: 0.0	EVSE id for which check is done
`customData`	CustomDataType	No

Example VatNumberValidationRequest

{
  "vatNumber": "string"
}

#VatNumberValidationResponse

Field	Type	Required	Constraints	Description
`status`	GenericStatusEnumType	Yes
`vatNumber`	string	Yes	maxLength: 20	VAT number that was requested.
`company`	AddressType	No
`evseId`	integer	No	min: 0.0	EVSE id for which check was requested.
`statusInfo`	StatusInfoType	No
`customData`	CustomDataType	No

#Local Types

Types used only within this block's messages.

#PaymentStatusEnumType

The status of the settlement attempt.

Value
`Settled`
`Canceled`
`Rejected`
`Failed`

Used in: NotifySettlement

#TariffChangeStatusEnumType

Status of the operation

Value
`Accepted`
`Rejected`
`TooManyElements`
`ConditionNotSupported`
`TxNotFound`
`NoCurrencyChange`

Used in: ChangeTransactionTariff

#TariffClearStatusEnumType

Value
`Accepted`
`Rejected`
`NoTariff`

Used in: ClearTariffs

#TariffGetStatusEnumType

Status of operation

Value
`Accepted`
`Rejected`
`NoTariff`

Used in: GetTariffs

#TariffKindEnumType

Kind of tariff (driver/default)

Value
`DefaultTariff`
`DriverTariff`

Used in: GetTariffs

#TariffSetStatusEnumType

Value
`Accepted`
`Rejected`
`TooManyElements`
`ConditionNotSupported`
`DuplicateTariffId`

Used in: SetDefaultTariff

#AddressType

(2.1) A generic address format.

Field	Type	Required	Constraints	Description
`address1`	string	Yes	maxLength: 100	Address line 1
`city`	string	Yes	maxLength: 100
`country`	string	Yes	maxLength: 50	Country name
`name`	string	Yes	maxLength: 50	Name of person/company
`address2`	string	No	maxLength: 100	Address line 2
`postalCode`	string	No	maxLength: 20	Postal code
`customData`	CustomDataType	No

Used in: NotifySettlement, VatNumberValidation

#ClearTariffsResultType

Field	Type	Required	Constraints	Description
`status`	TariffClearStatusEnumType	Yes
`statusInfo`	StatusInfoType	No
`tariffId`	string	No	maxLength: 60	Id of tariff for which status is reported. If no tariffs were found, then this field is absent, and status will be NoTariff.
`customData`	CustomDataType	No

Used in: ClearTariffs

#TariffAssignmentType

Shows assignment of tariffs to EVSE or IdToken.

Field	Type	Required	Constraints	Description
`tariffId`	string	Yes	maxLength: 60	Tariff id.
`tariffKind`	TariffKindEnumType	Yes
`evseIds`	integer[]	No	minItems: 1
`idTokens`	string[]	No	minItems: 1	IdTokens related to tariff
`validFrom`	string (date-time)	No		Date/time when this tariff become active.
`customData`	CustomDataType	No

Used in: GetTariffs