# Shift Start

## 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

```mermaid
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.

***

### Step 3 — Driver initiates device link

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`

***

### Step 4 — CabFare Connect forwards link request to Taxi Meter

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

***

### Step 5 — Taxi Meter responds to link request

**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

---
Source: https://docs.cabfare.com/api/shift-start