Appearance

Shift Start ​

View as Markdown

Overview ​

The Shift Start workflow establishes an authenticated, linked session between the Taxi Meter and the Payment Terminal for a specific driver and vehicle. Until both devices are linked, Subsidy Scheme processing is not available and the devices operate independently.

Sequence Diagram ​

sequenceDiagram
    actor Driver
    participant TM as Taxi Meter
    participant CC as CabFare Connect
    participant PT as Payment Terminal

    Driver->>TM: Logs in on Taxi Meter
    TM->>CC: POST /meter/driver/login (driverId, vehiclePlate, taxiMeterId)
    CC-->>TM: 200 OK (mptpDriverData, subsidyStatus)
    TM-->>Driver: Displays Subsidy Scheme eligibility status

    Driver->>PT: Logs in on Payment Terminal
    PT->>CC: POST /terminal/driver/login (driverId, terminalId)
    CC-->>PT: 200 OK (mptpDriverData, subsidyStatus)

    Driver->>PT: Selects option to link terminals
    PT->>CC: POST /terminal/link/request (driverId, vehiclePlate, terminalId)
    CC->>TM: POST /link/request (driverId, vehiclePlate, subsidyStatus)

    alt Taxi Meter accepts link request
        TM-->>CC: 200 OK (link success)
        TM-->>Driver: Displays Subsidy Scheme eligibility, enters linked mode
        CC-->>PT: POST /link/response (link success, subsidyStatus)
        PT-->>Driver: Displays Subsidy Scheme eligibility, enters linked mode
    else Taxi Meter rejects link request
        TM-->>CC: Error (link failure)
        CC-->>PT: POST /link/response (link failure)
        PT-->>Driver: Displays error, continues in unlinked mode
    end

Step-by-Step ​

Step 1 — Driver logs in on Taxi Meter ​

The driver logs in on the Taxi Meter as normal. The Taxi Meter notifies CabFare Connect of the login event.

Taxi Meter calls:
POST /meter/driver/login

Required fields: taxiMeterId, driverId, vehiclePlate

CabFare Connect responds with: the driver's current Subsidy Scheme eligibility status (mptpDriverData).

The Taxi Meter displays the driver's Subsidy Scheme eligibility status on screen. If the driver is not eligible, Subsidy Scheme trip functions are disabled for the shift but standard trips continue normally.

Step 2 — Driver logs in on Payment Terminal ​

The driver logs in on the Payment Terminal. The Payment Terminal notifies CabFare Connect of the login event.

Payment Terminal calls:
POST /terminal/driver/login

Required fields: terminalId, driverId

Optional fields: vehiclePlate — only provide if the vehicle plate is confirmed and known to the Payment Terminal, for example with hardware fixed to a specific vehicle.

CabFare Connect responds with: the same driver Subsidy Scheme eligibility status.

Both devices must be logged in before a link request can succeed.

The driver selects the option to link the terminals on the Payment Terminal. This step may be configured to occur automatically depending on the Payment Terminal implementation.

Payment Terminal calls:
POST /terminal/link/request

Required fields: terminalId, driverId

CabFare Connect forwards the link request to the Taxi Meter.

CabFare Connect calls:
POST /link/request on the Taxi Meter

Includes: driverId, vehiclePlate, driver Subsidy Scheme eligibility status

If the Taxi Meter accepts the link request:

  • Taxi Meter returns a success response to CabFare Connect
  • Taxi Meter displays the driver's Subsidy Scheme eligibility status and enters linked mode
  • CabFare Connect sends a link success response to the Payment Terminal via POST /link/response
  • Payment Terminal enters linked mode and displays the driver's Subsidy Scheme eligibility status

If the Taxi Meter rejects the link request (for example if the driver is not yet logged in on the Taxi Meter):

  • Taxi Meter returns an error response to CabFare Connect
  • CabFare Connect sends a link failure response to the Payment Terminal via POST /link/response
  • Payment Terminal displays an error and continues in unlinked mode

Step 6 — Linked session established ​

Once both devices have confirmed linked mode, the session is active. The following payment types are now available for the duration of the shift:

  • Subsidy Scheme trips — where a passenger Subsidy Card is validated and the subsidy is processed by CabFare Connect, with the remaining balance collected by card, cash, or other method
  • Standard card payment trips — where the full fare is collected by the Payment Terminal with no Subsidy Scheme processing
  • Cash and other payment trips — where the Payment Terminal is not involved in the payment

If the devices do not successfully link, both devices continue to operate independently in unlinked mode. Standard trips and cash payments remain available but Subsidy Scheme processing is not available.

Key Points ​

  • The driver must be logged in on the Taxi Meter before the link request is initiated on the Payment Terminal
  • vehiclePlate is optional at Payment Terminal login and link request — refer to the review note in Step 3
  • Subsidy Scheme eligibility is checked by CabFare Connect at login and communicated to both devices
  • If linking fails, both devices continue in unlinked mode — the shift is not blocked