# Member Card Validation

## Overview

The Member Card Validation workflow confirms that a passenger is eligible for Subsidy Scheme benefits before a Subsidy Scheme trip proceeds. Validation can be initiated by the Payment Terminal via a physical card read, or by the Taxi Meter via manual entry if the card cannot be read. This workflow may occur at any point during the trip including at Trip End.

## Sequence Diagram

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

    Driver->>TM: Selects Subsidy Scheme trip on Taxi Meter
    TM->>CC: POST /meter/mptp/read (taxiMeterId, driverId, tripId)
    CC->>PT: POST /mptp/read (driverId, tripId)
    PT-->>Driver: Prompts driver to present Subsidy Card

    alt Option A — Payment Terminal reads card successfully
        Driver->>PT: Presents Subsidy Card
        PT->>CC: POST /terminal/mptp/validate (terminalId, driverId, tripId, cardNumber)
        CC-->>CC: Validates card eligibility and balance
        alt Card is valid
            CC-->>PT: 200 OK (mptpMemberData, isEligible: true)
            CC->>TM: POST /mptp/member (mptpMemberData)
            TM-->>Driver: Displays validation success, initiates Subsidy Scheme trip
        else Card is invalid
            CC-->>PT: 200 OK (mptpMemberData, isEligible: false)
            CC->>TM: POST /mptp/member (error details)
            TM-->>Driver: Displays error
        end
    else Option B — Payment Terminal cannot read card, manual entry on Taxi Meter
        Driver->>PT: Cancels card read
        Driver->>TM: Selects manual entry, enters card number on keypad
        TM->>CC: POST /meter/mptp/validate (taxiMeterId, driverId, tripId, cardNumber)
        CC-->>CC: Validates card eligibility and balance
        alt Card is valid
            CC-->>TM: 200 OK (mptpMemberData, isEligible: true)
            TM-->>Driver: Displays validation success, initiates Subsidy Scheme trip
        else Card is invalid
            CC-->>TM: 200 OK (mptpMemberData, isEligible: false)
            TM-->>Driver: Displays error
        end
    end
```

## Step-by-Step

### Step 1 — Driver selects Subsidy Scheme trip on Taxi Meter

The driver selects the option on the Taxi Meter to initiate a Subsidy Scheme trip. The Taxi Meter sends a card read request to CabFare Connect.

**Taxi Meter calls:**
`POST /meter/mptp/read`

**Required fields:** `taxiMeterId`, `driverId`, `tripId`

***

### Step 2 — CabFare Connect forwards card read request to Payment Terminal

CabFare Connect forwards the card read request to the linked Payment Terminal.

**CabFare Connect calls:**
`POST /mptp/read` on the Payment Terminal

The Payment Terminal prompts the driver to present the passenger's Subsidy Card.

***

### Step 3 — Card read or manual entry

**Option A — Payment Terminal reads card successfully**

The driver presents the passenger Subsidy Card to the Payment Terminal. The Payment Terminal reads the card and submits it to CabFare Connect for validation.

**Payment Terminal calls:**
`POST /terminal/mptp/validate`

**Required fields:** `terminalId`, `driverId`, `tripId`, card number

***

**Option B — Payment Terminal cannot read card**

If the Payment Terminal cannot read the card the driver cancels the card read on the Payment Terminal. The driver then selects manual entry on the Taxi Meter and enters the card number on the keypad.

The card number for manual entry is the last 9 digits of the Subsidy Card number. The first 9 digits must not be included. Confirm whether this digit format applies generically or is specific to the Victoria MPTP implementation only.

**Taxi Meter calls:**
`POST /meter/mptp/validate`

**Required fields:** `taxiMeterId`, `driverId`, `tripId`, card number

***

### Step 4 — CabFare Connect validates the card

CabFare Connect checks the card against the current Subsidy Provider eligibility data.

**If the card is valid and the member has a positive balance:**

- If the request came from the Payment Terminal:
  - CabFare Connect returns validation success to the Payment Terminal
  - CabFare Connect sends the member card details to the Taxi Meter via `POST /mptp/member`
  - The Taxi Meter initiates the Subsidy Scheme trip
- If the request came from the Taxi Meter:
  - CabFare Connect returns validation success and member card details to the Taxi Meter
  - The Taxi Meter initiates the Subsidy Scheme trip

**If the card is invalid, expired, or has no remaining balance:**

- If the request came from the Payment Terminal:
  - CabFare Connect returns error details to the Payment Terminal for display
  - CabFare Connect sends error details to the Taxi Meter via `POST /mptp/member`
- If the request came from the Taxi Meter:
  - CabFare Connect returns error details to the Taxi Meter for display

***

### Step 5 — Additional Subsidy Cards

CabFare Connect supports multiple Subsidy Cards within a single trip for additional lifting fees. This process may be repeated for each additional eligible passenger. Only the first Subsidy Card is used to process the subsidy payment. Additional cards are validated and recorded for lifting fee purposes only.

***

## Key Points

- Member Card Validation may occur at any point during the trip including at Trip End
- The Taxi Meter is the designated entry point for manual card number entry if the Payment Terminal cannot read the card
- If the card is invalid the driver must find an alternative method — the trip may continue as a standard trip
- Multiple Subsidy Cards may be added to a single trip for additional lifting fees
- Only the first Subsidy Card submitted is used to calculate the subsidy payment

---
Source: https://docs.cabfare.com/api/member-card-validation