Transaction Flows - CSMS Developer Guide

{
  "totalCost": "number",            // Running cost (Updated) or final cost (Ended)
                                    // 0.00 = free transaction. Absence != free.
  "chargingPriority": "integer",    // -9 to 9, default 0. Higher = higher priority.
  "idTokenInfo": {                  // MUST include when IdToken was in the request
    "status": "AuthorizationStatusEnumType",  // Accepted/Blocked/ConcurrentTx/Expired/...
    "cacheExpiryDateTime": "dateTime",
    "chargingPriority": "integer",
    "groupIdToken": { "idToken": "string", "type": "string" },
    "language1": "string (max 8)",
    "language2": "string (max 8)",
    "evseId": [1, 2],
    "personalMessage": { "format": "string", "content": "string" }
  },
  "transactionLimit": {             // Set/update limits on the transaction
    "maxCost": "number",
    "maxEnergy": "number (Wh)",
    "maxTime": "integer (seconds)",
    "maxSoC": "integer (0-100)"
  },
  "updatedPersonalMessage": { ... },       // Message to display to user
  "updatedPersonalMessageExtra": [ ... ]   // Additional messages (max 4)
}

function handleTransactionEventStarted(request):
    // 1. Store the new transaction
    transaction = createTransaction(
        transactionId: request.transactionInfo.transactionId,
        chargingStationId: connection.chargingStationId,
        startTime: request.timestamp,
        seqNo: request.seqNo
    )

    // 2. Store EVSE info if provided (E01.FR.16)
    if request.evse:
        transaction.evseId = request.evse.id
        transaction.connectorId = request.evse.connectorId

    // 3. If idToken is present, MUST validate it (E01.FR.11)
    response = {}
    if request.idToken:
        authResult = validateIdToken(request.idToken)
        response.idTokenInfo = {
            status: authResult.status,
            groupIdToken: authResult.groupIdToken  // if exists (E01.FR.12)
        }

    // 4. Store reservation link if present (E01.FR.13)
    if request.reservationId:
        transaction.reservationId = request.reservationId
        endReservation(request.reservationId)

    // 5. If remoteStartId present, link to original request (C05.FR.03)
    if request.transactionInfo.remoteStartId:
        linkRemoteStart(transaction, request.transactionInfo.remoteStartId)

    // 6. Store meter values if present
    if request.meterValue:
        storeMeterValues(transaction, request.meterValue)

    // 7. Track sequence number for completeness
    transaction.lastSeqNo = request.seqNo

    // 8. ALWAYS return a response
    return response

function handleTransactionEvent_E02(request):
    tx = getTransaction(request.transactionInfo.transactionId)

    switch request.eventType:
        case "Started":
            // Transaction started without driver being known
            // E02.FR.06: When TxStartPoint contains EVConnected
            tx = createTransaction(...)
            // No idToken yet - cannot validate
            return {}

        case "Updated":
            if request.triggerReason == "Authorized" and request.idToken:
                // E02.FR.01: Driver identified - MUST validate
                // E02.FR.04: CSMS SHALL verify validity (might have been
                //            authorized locally with outdated info)
                authResult = validateIdToken(request.idToken)
                tx.idToken = request.idToken
                return {
                    idTokenInfo: {
                        status: authResult.status
                    }
                }

            if request.triggerReason == "ChargingStateChanged":
                tx.chargingState = request.transactionInfo.chargingState
                storeMeterValues(tx, request.meterValue)
                return {}

        case "Ended":
            finalizeTransaction(tx, request)
            return {}

function handleOfflineTransactionEvent(request):
    // E04.FR.03: offline flag SHALL be true for events that occurred offline
    if request.offline:
        // Use request.timestamp as the actual event time
        // (NOT the time the message was received)
        tx = getOrCreateTransaction(request.transactionInfo.transactionId)
        tx.offlineOccurred = true

        // Process normally but note the offline flag
        // IdToken validation still applies
        if request.idToken:
            authResult = validateIdToken(request.idToken)
            return { idTokenInfo: authResult }

    return {}

function handleTransactionEventWithIdValidation(request):
    if request.idToken:
        // E05.FR.01: CSMS MUST verify validity
        authResult = validateIdToken(request.idToken)

        if authResult.status != "Accepted":
            // Return non-accepted status
            // CS will handle suspension/termination based on its config
            return {
                idTokenInfo: {
                    status: authResult.status  // "Blocked"/"Invalid"/"Expired"/etc
                }
            }

        return {
            idTokenInfo: { status: "Accepted" }
        }

    return {}

{
  "eventType": "Ended",
  "timestamp": "2025-01-15T12:45:00Z",
  "triggerReason": "StopAuthorized",
  "seqNo": 5,
  "transactionInfo": {
    "transactionId": "AB1234",
    "chargingState": "EVConnected",
    "timeSpentCharging": 7200,
    "stoppedReason": "Local"
  },
  "idToken": { "idToken": "1234", "type": "ISO14443" },
  "meterValue": [
    {
      "timestamp": "2025-01-15T12:45:00Z",
      "sampledValue": [
        {
          "value": 15000,
          "context": "Transaction.End",
          "measurand": "Energy.Active.Import.Register",
          "unitOfMeasure": { "unit": "Wh" }
        }
      ]
    }
  ]
}

function handleTransactionEventEnded(request):
    tx = getTransaction(request.transactionInfo.transactionId)

    // 1. Store final meter values
    if request.meterValue:
        storeMeterValues(tx, request.meterValue)

    // 2. Store stopped reason
    // E06.FR.08: stoppedReason is included if not ended by EV Driver
    // E06.FR.09: stoppedReason MAY be omitted when driver ended it locally
    //            (CSMS can interpret absence as "Local")
    tx.stoppedReason = request.transactionInfo.stoppedReason ?? "Local"
    tx.endTime = request.timestamp
    tx.timeSpentCharging = request.transactionInfo.timeSpentCharging

    // 3. Validate IdToken if present (driver presenting token to stop)
    response = {}
    if request.idToken:
        authResult = validateIdToken(request.idToken)
        response.idTokenInfo = { status: authResult.status }

    // 4. Check sequence completeness
    if tx.lastSeqNo + 1 != request.seqNo:
        // Missing messages! May need to use GetTransactionStatus
        flagIncompleteTransaction(tx)

    // 5. Calculate final cost if applicable
    if shouldCalculateCost(tx):
        response.totalCost = calculateFinalCost(tx)

    // 6. Mark transaction as completed
    tx.status = "Completed"

    return response

function handleOfflineBatchTransaction(request):
    // Process all messages with offline = true
    // Build the complete transaction picture from the batch

    // E12.FR.03: Meter values should be present
    // E12.FR.04 (2.1): CS may drop non-critical Updated messages when low on memory
    //   but NOT messages with triggerReason: LimitSet, CostLimitReached,
    //   EnergyLimitReached, TimeLimitReached, SoCLimitReached

    // E12.FR.05: Intermediate messages are dropped first (2nd, 4th, 6th)
    //   never the first or last

    // Process normally but note all messages are historical
    return processTransactionEvent(request)

// CSMS sends:
{}

// CS responds:
{
  "messagesInQueue": false   // no queued messages
  // ongoingIndicator is NOT present when no transactionId specified
}

function handleTransactionLimits(request, response):
    tx = getTransaction(request.transactionInfo.transactionId)

    // E16.FR.02: CSMS sets limit via TransactionEventResponse
    if csmsWantsToSetLimit(tx):
        response.transactionLimit = {
            maxCost: getMaxCostForTransaction(tx)
        }

    // E16.FR.03: CS confirms limit by echoing it back
    if request.transactionInfo.transactionLimit:
        tx.confirmedLimits = request.transactionInfo.transactionLimit

    // E16.FR.04: CS SHALL NOT exceed CSMS-set limits

    // E16.FR.05/06: Handle limit reached
    if request.triggerReason in ["CostLimitReached", "EnergyLimitReached",
                                  "TimeLimitReached", "SoCLimitReached"]:
        // TxStopPoint NOT "EnergyTransfer": chargingState = SuspendedEVSE
        // TxStopPoint "EnergyTransfer": eventType = Ended
        tx.limitReached = request.triggerReason

    // E16.FR.07: CSMS can update limits
    if csmsWantsToUpdateLimit(tx):
        response.transactionLimit = { maxCost: newLimit }

    // E16.FR.11: When maxCost is active, CSMS SHALL provide cost updates
    if tx.confirmedLimits?.maxCost and not localCostCalculation:
        response.totalCost = calculateRunningCost(tx)

    // E16.FR.14: If limit increased after SuspendedEVSE, CS resumes charging

    // E16.FR.17: To remove a limit, set it to a very high value
    // (limits cannot be unset, only changed)

    // E16.FR.18: Don't expect limit confirmation for offline messages

function remoteStartTransaction(chargingStationId, params):
    remoteStartId = generateUniqueId()

    request = {
        remoteStartId: remoteStartId,
        idToken: params.idToken
    }

    if params.evseId:
        request.evseId = params.evseId

    if params.chargingProfile:
        request.chargingProfile = params.chargingProfile

    response = sendToChargingStation(chargingStationId,
        "RequestStartTransactionRequest", request)

    if response.status == "Accepted":
        // Store remoteStartId to match with upcoming TransactionEventRequest
        // The CS will include remoteStartId in transactionInfo.remoteStartId
        storeRemoteStart(remoteStartId, chargingStationId, params)

        // If response.transactionId is present, transaction already started
        if response.transactionId:
            linkTransaction(remoteStartId, response.transactionId)

    return response

Transaction:
    transactionId: string (UUID, max 36)
    chargingStationId: string
    evseId: integer
    connectorId: integer
    startTime: datetime
    endTime: datetime (nullable)
    status: enum [Active, Completed, Cancelled]
    idToken: IdTokenType (nullable)
    stoppedReason: ReasonEnumType (nullable)
    timeSpentCharging: integer (seconds)
    lastSeqNo: integer
    startSeqNo: integer
    offline: boolean
    remoteStartId: integer (nullable)
    reservationId: integer (nullable)
    tariffId: string (nullable)
    transactionLimits: TransactionLimitType (nullable)
    meterValues: MeterValueType[]
    costDetails: CostDetailsType (nullable)

TransactionEvent:
    transactionId: string (FK)
    eventType: enum [Started, Updated, Ended]
    seqNo: integer
    timestamp: datetime
    triggerReason: TriggerReasonEnumType
    chargingState: ChargingStateEnumType (nullable)
    offline: boolean
    meterValues: MeterValueType[]
    receivedAt: datetime  // when CSMS actually received the message