Migration Guide 2.0.1 → 2.1 Section C & D

Authorization Section — Migration Guide

Use cases C01–C16, D01–D02 (Authorization & Local Authorization List Management). Perspective: CSMS Developer.

8 Sections

25 Use Cases

C01 – C25, D01 – D02

Created by tzi.app — your guide to migrating from OCPP 2.0.1 to OCPP 2.1.

1. Summary of Changes

High-Level Overview

Area	Change Type	Description
IdTokenType	Field size increase	idToken max length: 36 → 255 chars
IdTokenEnumType	New value	DirectPayment added for ad hoc payment flows
AuthorizeRequest	Field size increase	certificate max: 5500 → 10000 chars
AuthorizeResponse	New fields	allowedEnergyTransfer, tariff added
TransactionEventRequest	New fields	transactionLimit, operationMode, tariffId, costDetails added
TransactionEventResponse	New fields	transactionLimit, updatedPersonalMessageExtra added
MessageContentType	New format + size	QRCODE format added; content max: 512 → 1024 chars
StatusInfoType	Field size increase	additionalInfo max: 512 → 1024 chars
C02	Flow changed	No longer sends AuthorizeRequest; CSMS learns via TransactionEventRequest only
C03	Removed	Replaced by new use cases C17, C18, C24, C25
C04	Security hardened	Explicit PIN logging prohibition and brute-force protection requirements
C05	Response extended	RequestStartTransactionResponse now includes optional transactionId
C17–C25	New use cases	Prepaid cards, payment terminals, settlement flows, QR code payments
D01–D02	Schema clarifications	customData explicitly documented; Full update with empty array clarified as invalid

2. Data Type & Schema Changes

2.1 IdTokenType

Field	OCPP 2.0.1	OCPP 2.1	Action Required
`idToken`	max 36 chars	max 255 chars	Update validation to accept longer identifiers
`type`	Implied enum	max 20 chars (`IdTokenEnumStringType`)	Update type handling to string-based enum
`additionalInfo[].additionalIdToken`	max 36 chars	max 255 chars	Update validation

2.2 IdTokenEnumType — New Value

Value	Version	Description
`DirectPayment`	2.1 only	Ad hoc payment via payment terminal. The `idToken` value is the PspRef (Payment Service Provider Reference).

All existing values remain unchanged: Central, eMAID, ISO14443, ISO15693, KeyCode, Local, MacAddress, NoAuthorization.

2.3 AuthorizeRequest

Field	OCPP 2.0.1	OCPP 2.1	Action Required
`certificate`	max 5500 chars	max 10000 chars	Update validation to accept larger certificate chains
`iso15118CertificateHashData[].responderURL`	max 512 chars	max 2000 chars	Update validation

2.4 AuthorizeResponse — New Fields

JSON — AuthorizeResponse diff

OCPP 2.0.1                              OCPP 2.1
─────────                               ────────
{                                        {
  "idTokenInfo": { ... },                  "idTokenInfo": { ... },
  "certificateStatus": "..."               "certificateStatus": "...",
                                      +    "allowedEnergyTransfer": [...],   // NEW
                                      +    "tariff": { ... }                 // NEW
}                                        }

New Field	Type	Description
`allowedEnergyTransfer`	`string[]`	Restricts which energy transfer modes are allowed (e.g., `AC_single_phase`, `DC`). Defaults to charging only if omitted.
`tariff`	`TariffType`	Tariff information for cost calculation. Enables the CS to display/calculate costs locally.

2.5 IdTokenInfoType — Field Size Changes

Field	OCPP 2.0.1	OCPP 2.1
`personalMessage.content`	max 512 chars	max 1024 chars
`personalMessage.format` values	`ASCII`, `HTML`, `URI`, `UTF8`	`ASCII`, `HTML`, `URI`, `UTF8`, QRCODE

2.6 TransactionEventRequest — New Fields

JSON — TransactionEventRequest diff

OCPP 2.0.1                              OCPP 2.1
─────────                               ────────
"transactionInfo": {                     "transactionInfo": {
  "transactionId": "...",                  "transactionId": "...",
  "chargingState": "...",                  "chargingState": "...",
  "stoppedReason": "...",                  "stoppedReason": "...",
  "remoteStartId": 123                     "remoteStartId": 123,
                                      +    "operationMode": "...",          // NEW
                                      +    "tariffId": "...",               // NEW
                                      +    "transactionLimit": {            // NEW
                                      +      "maxCost": ...,
                                      +      "maxEnergy": ...,
                                      +      "maxTime": ...,
                                      +      "maxSoC": ...
                                      +    }
}                                        }
+                                        "costDetails": { ... }            // NEW (top-level)

New Field	Type	Description
`transactionInfo.operationMode`	`OperationModeEnumType`	Current operation mode of the transaction
`transactionInfo.tariffId`	`string (max 60)`	Active tariff identifier
`transactionInfo.transactionLimit`	Object	Transaction limits set by CS (maxCost, maxEnergy, maxTime, maxSoC)
`costDetails`	Object	Detailed cost breakdown for the transaction

New TriggerReason value: LimitSet — sent when a transaction limit is updated, e.g., during incremental payment authorization (see C23).

2.7 TransactionEventResponse — New Fields

JSON — TransactionEventResponse diff

OCPP 2.0.1                              OCPP 2.1
─────────                               ────────
{                                        {
  "totalCost": ...,                        "totalCost": ...,
  "chargingPriority": ...,                 "chargingPriority": ...,
  "idTokenInfo": { ... },                  "idTokenInfo": { ... },
  "updatedPersonalMessage": { ... }        "updatedPersonalMessage": { ... },
                                      +    "transactionLimit": {            // NEW
                                      +      "maxCost": ...,
                                      +      "maxEnergy": ...,
                                      +      "maxTime": ...,
                                      +      "maxSoC": ...
                                      +    },
                                      +    "updatedPersonalMessageExtra": [ ... ]  // NEW
}                                        }

New Field	Type	Description
`transactionLimit`	Object	CSMS-set limits on the transaction (used for prepaid and ad hoc payments)
`updatedPersonalMessageExtra`	`MessageContentType[]` (1–4)	Additional personal messages (multilingual support)

2.8 StatusInfoType

Field	OCPP 2.0.1	OCPP 2.1
`additionalInfo`	max 512 chars	max 1024 chars

2.9 RequestStartTransactionResponse — New Field

New Field	Type	Description
`transactionId`	`string (max 36)`	If a transaction was already started before the remote start request, this field contains its ID

3. Use Case Changes (C01–C16)

C01 — EV Driver Authorization using RFID

No functional changes. Schema field size increases apply (see Section 2).

C02 — Authorization using a Start Button Breaking

Breaking change: Flow fundamentally altered. The CS no longer sends an AuthorizeRequest; the CSMS learns about the session via TransactionEventRequest only.

Aspect	OCPP 2.0.1	OCPP 2.1
Message flow	CS sends `AuthorizeRequest` with `idToken.type=NoAuthorization` (when `AuthEnabled=true`)	No `AuthorizeRequest` is sent. CSMS learns via `TransactionEventRequest` only.
CSMS first notification	`AuthorizeRequest`	`TransactionEventRequest(eventType=Started)`
IdToken delivery	In `AuthorizeRequest`	In `TransactionEventRequest(eventType=Updated, idToken.type=NoAuthorization)` with `idToken` field left empty
CSMS response	`AuthorizeResponse`	`TransactionEventResponse` with `idTokenInfo.status=Accepted`

CSMS Migration Action

Remove any AuthorizeRequest handler logic specific to NoAuthorization tokens
Handle NoAuthorization tokens in the TransactionEventRequest handler instead
Respond with idTokenInfo.status=Accepted in the TransactionEventResponse

C03 — Authorization using Credit/Debit Card Removed

Removed in OCPP 2.1

Replaced by:

C17 — Authorization with Prepaid Card
C18 — Authorization using Locally Connected Payment Terminal
C24 — Ad Hoc Payment via Stand-alone Payment Terminal
C25 — Ad Hoc Payment via QR Code

CSMS Migration Action: Implement the new use cases (C17–C25) that match your payment flow requirements. See Section 4.

C04 — Authorization using PIN-code Security Hardened

Requirement	OCPP 2.0.1	OCPP 2.1
PIN logging	Not specified	CSMS SHALL NOT log the `idToken` value (PIN) in any logs
Brute force protection	Not specified	RECOMMENDED: Implement increasing backoff times after failed attempts

CSMS Migration Action

Audit logging to ensure PIN values are never logged
Implement brute-force protection (rate limiting / backoff) for KeyCode authorization attempts

C05 — Authorization for CSMS-Initiated Transactions Minor Enhancement

Aspect	OCPP 2.0.1	OCPP 2.1
`RequestStartTransactionResponse.transactionId`	Not present	Optional. Returned if a transaction was already started before the remote start request.

CSMS Migration Action: Handle the optional transactionId in RequestStartTransactionResponse to detect pre-existing transactions.

C06 — Authorization using Local Id Type Minor Enhancement

The flow now explicitly documents the RequestStopTransactionRequest path for stopping transactions initiated by a locally-connected payment terminal. Ensure RequestStopTransactionRequest sending is implemented for this use case.

C07 — Authorization using Contract Certificates (ISO 15118) Enhanced

Aspect	OCPP 2.0.1	OCPP 2.1
Certificate field size	max 5500 chars	max 10000 chars
ResponderURL field size	max 512 chars	max 2000 chars
GenChallenge verification	Not explicitly mentioned	Explicitly required: "Verify signature of GenChallenge"
`CentralContractValidationAllowed`	Not explicitly documented in auth flow	Explicitly documented: CS sends full PEM certificate chain when it cannot validate locally

CSMS Migration Action

Update validation for larger certificate and responderURL fields
Implement GenChallenge signature verification if not already done
Handle CentralContractValidationAllowed flow explicitly

C08 — Authorization at EVSE using ISO 15118 EIM

No functional changes.

C09 — Authorization using GroupId

No functional changes.

C10 — Store Authorization Data in Authorization Cache New Guidance

Do NOT include additionalInfo of idToken or groupIdToken in responses intended for caching (they are not cached). This is advisory — no protocol change, but optimize responses accordingly.

C11 — Clear Authorization Data in Authorization Cache

No functional changes.

C12 — Start Transaction with Cached Id Clarification

Sequence clarification: The flow explicitly shows TransactionEventRequest(eventType=Started) being sent when the cable is plugged in (before RFID), followed by TransactionEventRequest(eventType=Updated, triggerReason=Authorized) when the cached token is presented. CSMS validation logic remains the same.

C13 — Offline Authorization through Local Authorization List

No functional changes. CSMS responsibilities remain the same (manage the list via SendLocalListRequest).

C14 — Online Authorization through Local Authorization List

No functional changes.

C15 — Offline Authorization of Unknown Id Clarification

Condition	OCPP 2.0.1	OCPP 2.1
`StopTxOnInvalidId` = true, stop point match	CS ends transaction with `stoppedReason=DeAuthorized`	Same, but explicitly states `TxStopPoint` must contain `Authorized` OR `PowerPathClosed` OR `EnergyTransfer`
`StopTxOnInvalidId` = true, no stop point match	CS stops energy, sends Deauthorized event	Same, with explicit `chargingState=SuspendedEVSE` in the Updated event

CSMS Migration Action: No protocol change, but update documentation/handling to match the more explicit 2.1 behavior.

C16 — Stop Transaction with a Master Pass

No functional changes.

4. New Use Cases in 2.1 (C17–C25)

These are entirely new use cases that do not exist in OCPP 2.0.1. They must be implemented from scratch.

C17 — Authorization with Prepaid Card New

Aspect	Details
Purpose	Handle prepaid/balance-based accounts
Key behavior	Set `cacheExpiryDateTime` to current time to prevent caching. Return `transactionLimit.maxCost` with remaining balance in `TransactionEventResponse`.
New status usage	`NoCredit` when balance <= 0

C18 — Authorization using Locally Connected Payment Terminal New

Aspect	Details
Purpose	Ad hoc payment via an integrated (locally connected) payment terminal
New IdToken type	`DirectPayment` with PspRef as the `idToken` value
New config variable	`PaymentCtrlr.AuthorizeDirectPayment` controls whether `AuthorizeRequest` is sent
New response field	`tariff` in `AuthorizeResponse` for cost calculation
New messages	`VatNumberValidationRequest`/`Response` for VAT number handling

C19 — Cancellation Prior to Transaction New

Aspect	Details
Purpose	Handle payment cancellation before transaction starts
New message	`NotifySettlementRequest` with `status=Cancelled`

C20 — Cancellation After Start of Transaction New

Aspect	Details
Purpose	Handle cancellation after transaction started but no energy delivered
Key behavior	Respond with `totalCost=0` in `TransactionEventResponse`, then process `NotifySettlementRequest` with `status=Cancelled`

C21 — Settlement at End of Transaction New

Aspect	Details
Purpose	Final cost settlement for ad hoc payment transactions
New message	`NotifySettlementRequest` with `status=Settled`, `settlementAmount`, `settlementTime`
New config variables	`PaymentCtrlr.ReceiptByCSMS`, `PaymentCtrlr.SettlementByCSMS`

C22 — Settlement is Rejected or Fails New

Aspect	Details
Purpose	Handle failed/rejected payment settlements
Key behavior	Process `NotifySettlementRequest` with `status=Rejected` or `status=Failed`. Manual capture via PSP may be required.

C23 — Increasing Authorization Amount New

Aspect	Details
Purpose	Handle incremental payment authorization during long sessions
New trigger reason	`LimitSet` in `TransactionEventRequest`
Key behavior	CS sends updated `transactionLimit.maxCost` when authorization is increased

C24 — Ad Hoc Payment via Stand-alone Payment Terminal New

Aspect	Details
Purpose	Separate payment kiosk (not integrated) handles payment, CSMS remotely starts
Key behavior	CSMS sends `RequestStartTransactionRequest` with `idToken.type=DirectPayment` after receiving payment authorization from kiosk

C25 — Ad Hoc Payment via QR Code New

Aspect	Details
Purpose	EV Driver scans QR code, pays via web browser, CSMS starts transaction
New messages	`NotifyWebPaymentStartedRequest`/`Response`
New requirements	TOTP validation (HMAC-SHA256, base62), URL parameter decoding, query parameter support (`maxenergy`, `maxtime`, `maxcost`)

5. New Messages in 2.1

These messages do not exist in OCPP 2.0.1 and must be implemented for the new payment-related use cases.

Incoming to CSMS (CS → CSMS)

Message	Response	Use Cases	Description
`NotifySettlementRequest`	`NotifySettlementResponse`	C19–C22	Payment settlement notifications (settled, cancelled, rejected, failed)
`VatNumberValidationRequest`	`VatNumberValidationResponse`	C18	VAT number validation for ad hoc payments
`NotifyWebPaymentStartedResponse`	(response to CSMS request)	C25	Response to web payment started notification

Outgoing from CSMS (CSMS → CS)

Message	Use Cases	Description
`NotifyWebPaymentStartedRequest`	C25	Notify CS that a QR code web payment is in progress (includes `evseId` and `timeout`)
`SetDisplayMessageRequest`	C24, C25	Display receipt URL on CS screen after settlement

6. Local Authorization List Management (D01–D02) Changes

D01 — Send Local Authorization List

Aspect	OCPP 2.0.1	OCPP 2.1	Impact
Schema namespace	Not specified	urn:OCPP:Cp:2:2025:1:SendLocalListRequest	Update schema validation
`customData` field	Not documented	Explicitly documented on all objects	Support optional passthrough
`IdTokenType.type` definition	`IdTokenEnumType` (strict enum)	`IdTokenEnumStringType` (string-based, max 20 chars)	Update type handling for extensibility
`Full` update with empty array	Described as "clears the list"	Clarified as invalid per schema (`minItems: 1`). To clear the list, omit the field entirely.	Fix code that sends empty array
`personalMessage.content` max length	512 chars	1024 chars	Update validation
`personalMessage.format` values	ASCII, HTML, URI, UTF8	ASCII, HTML, URI, UTF8, QRCODE	Support new format value
`IdTokenType.idToken` max length	36 chars	255 chars	Update validation
`AdditionalInfoType.additionalIdToken` max length	36 chars	255 chars	Update validation
`StatusInfoType.additionalInfo` max length	512 chars	1024 chars	Update validation

D02 — Get Local List Version

Aspect	OCPP 2.0.1	OCPP 2.1	Impact
Schema namespace	Not specified	urn:OCPP:Cp:2:2025:1:GetLocalListVersionRequest	Update schema validation
`customData` field	Not documented	Explicitly documented	Support optional passthrough
Behavior	Identical	Identical	No functional changes

7. Configuration Variable Changes

Existing Variables — No Changes

All authorization-related configuration variables from 2.0.1 remain in 2.1:

AuthCtrlr

AuthEnabled, AdditionalInfoItemsPerMessage, OfflineTxForUnknownIdEnabled, AuthorizeRemoteStart, LocalAuthorizeOffline, LocalPreAuthorize, MasterPassGroupId, DisableRemoteAuthorization, SupportedIdTokenTypes

AuthCacheCtrlr

AuthCacheEnabled, AuthCacheAvailable, AuthCacheLifeTime, AuthCacheStorage, AuthCachePolicy, AuthCacheDisablePostAuthorize, AuthCacheEntries

LocalAuthListCtrlr

LocalAuthListEnabled, LocalAuthListEntries, LocalAuthListAvailable, ItemsPerMessageSendLocalList, BytesPerMessageSendLocalList, LocalAuthListStorage, LocalAuthListDisablePostAuthorize, LocalAuthListSupportsExpiryDateTime

TxCtrlr

TxStartPoint, TxStopPoint, EVConnectionTimeOut, StopTxOnInvalidId, MaxEnergyOnInvalidId, StopTxOnEVSideDisconnect

New Variables in 2.1 New

Variable	Controller	Description
`PaymentCtrlr.AuthorizeDirectPayment`	PaymentCtrlr	If `true`, CS sends `AuthorizeRequest` for direct payments before starting. If `false`, CSMS learns via `TransactionEventRequest`.
`PaymentCtrlr.ReceiptByCSMS`	PaymentCtrlr	If `true`, CSMS is responsible for generating receipt URLs.
`PaymentCtrlr.SettlementByCSMS`	PaymentCtrlr	If `true`, CSMS handles settlement directly with the PSP.

8. Migration Checklist

Must Do Breaking / Required

Update idToken max length validation from 36 to 255 characters

Update additionalIdToken max length validation from 36 to 255 characters

Update certificate max length validation from 5500 to 10000 characters

Update responderURL max length validation from 512 to 2000 characters

Update personalMessage.content max length validation from 512 to 1024 characters

Update statusInfo.additionalInfo max length validation from 512 to 1024 characters

Handle DirectPayment IdToken type in AuthorizeRequest handler

Update C02 flow — Remove AuthorizeRequest handling for NoAuthorization; handle via TransactionEventRequest instead

Remove C03 logic — Credit/debit card flow no longer exists as a separate use case

Fix SendLocalListRequest for list clearing — If sending an empty array to clear the list, omit the localAuthorizationList field entirely instead

Support QRCODE in MessageFormatEnumType for personalMessage.format

Should Do New Features

Implement allowedEnergyTransfer in AuthorizeResponse

Implement tariff in AuthorizeResponse for cost transparency

Implement transactionLimit in TransactionEventResponse for prepaid/ad hoc payments

Implement updatedPersonalMessageExtra in TransactionEventResponse for multilingual messages

Handle transactionId in RequestStartTransactionResponse

Handle transactionLimit in incoming TransactionEventRequest

Handle costDetails in incoming TransactionEventRequest

Handle operationMode in incoming TransactionEventRequest

Handle tariffId in incoming TransactionEventRequest

Handle LimitSet trigger reason in incoming TransactionEventRequest

Implement PIN security — Ensure KeyCode values are never logged; add brute-force protection

Support customData passthrough on all message objects

New Use Cases to Implement New

C17

Prepaid card authorization with cacheExpiryDateTime and transactionLimit.maxCost

C18

Locally connected payment terminal with DirectPayment type and VatNumberValidation

C19

Pre-transaction cancellation via NotifySettlementRequest(Cancelled)

C20

Post-start cancellation via TransactionEventResponse(totalCost=0) + NotifySettlementRequest(Cancelled)

C21

End-of-transaction settlement via NotifySettlementRequest(Settled)

C22

Failed/rejected settlement handling via NotifySettlementRequest(Rejected/Failed)

C23

Incremental authorization amount increase via TransactionEventRequest(triggerReason=LimitSet)

C24

Stand-alone payment terminal flow with RequestStartTransactionRequest(idToken.type=DirectPayment)

C25

QR code payment flow with TOTP validation, URL decoding, and NotifyWebPaymentStartedRequest

New Message Handlers to Implement New

Incoming

NotifySettlementRequest handler — return NotifySettlementResponse

Incoming

VatNumberValidationRequest handler — return VatNumberValidationResponse

Outgoing

NotifyWebPaymentStartedRequest sender — with evseId and timeout

Outgoing

SetDisplayMessageRequest sender — for receipt URL display