# Taxi Meter Persona

## Overview

This guide is for Taxi Meter and dispatch system developers integrating with CabFare Connect. As a Taxi Meter partner you are the system brain — you govern driver shifts, calculate fares, manage Subsidy Scheme member validation, and initiate payment requests.

Read this guide alongside the Workflows section and the API Reference before beginning your implementation.

## Your Integration at a Glance

You must:

- Call the CabFare Connect API endpoints listed below to send events to CabFare Connect
- Implement and host the Taxi Meter API endpoints to receive inbound events from CabFare Connect

## Endpoints You Call — CabFare Connect API

| Endpoint                      | When to Call                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `POST /meter/driver/login`    | When the driver logs in on the Taxi Meter                                                                    |
| `POST /meter/driver/poll`     | To check current driver and link status after connectivity loss                                              |
| `POST /meter/trip/start`      | When the driver starts a trip hire                                                                           |
| `POST /meter/trip/end`        | When the driver ends a Subsidy Scheme trip and fare details are ready                                        |
| `POST /meter/mptp/read`       | When the driver selects a Subsidy Scheme trip to request a card read on the Payment Terminal (if applicable) |
| `POST /meter/mptp/validate`   | When the driver performs manual Subsidy Card number entry on the Taxi Meter (if applicable)                  |
| `POST /meter/payment/request` | When the driver selects card payment for the remaining balance                                               |
| `POST /meter/payment/cancel`  | When the driver cancels a pending card payment request                                                       |
| `POST /meter/job/done`        | When all payments are complete and the job is closed                                                         |
| `POST /meter/driver/logout`   | When the driver logs out of the Taxi Meter                                                                   |

## Endpoints You Host — Taxi Meter API

| Endpoint                 | Purpose                                                                      |
| ------------------------ | ---------------------------------------------------------------------------- |
| `POST /link/request`     | Receive link mode request from CabFare Connect                               |
| `POST /mptp/member`      | Receive Subsidy Card validation results from CabFare Connect (if applicable) |
| `POST /payment/complete` | Receive payment outcome notification from CabFare Connect                    |
| `POST /driver/logout`    | Receive driver logout notification from CabFare Connect                      |

## Implementation Checklist

### Shift Management

- [ ] Implement `POST /meter/driver/login` — submit `taxiMeterId`, `driverId`, `vehiclePlate` and handle the returned Subsidy Scheme eligibility status (if applicable)
- [ ] Display driver Subsidy Scheme eligibility status on screen after login (if applicable)
- [ ] Disable Subsidy Scheme trip functions if driver eligibility status is invalid (if applicable)
- [ ] Implement `POST /meter/driver/logout` — include all required shift end data if any Subsidy Scheme trips (if applicable) were processed during the shift
- [ ] Implement `POST /meter/driver/poll` — use after connectivity loss to recover session state

### Linking

- [ ] Host `POST /link/request` — return success or error response to CabFare Connect
- [ ] Display link status and driver Subsidy Scheme eligibility (if applicable) on screen after successful link
- [ ] Transition to unlinked mode if a link failure or driver logout notification is received from CabFare Connect

### Trip Management

- [ ] Implement `POST /meter/trip/start` — generate a unique `tripId` and submit with `taxiMeterId`, `driverId`, `vehiclePlate`
- [ ] Store the `tripId` and use it consistently for all subsequent events in the hire
- [ ] Handle `202 Accepted` response from trip start — disable Subsidy Scheme functions for this trip if driver status is not valid

### Subsidy Card Validation (if applicable)

- [ ] Implement `POST /meter/mptp/read` — call when driver selects Subsidy Scheme trip to request card read on Payment Terminal
- [ ] Implement `POST /meter/mptp/validate` — call for manual Subsidy Card number entry if Payment Terminal cannot read the card
- [ ] Host `POST /mptp/member` — receive and display Subsidy Card validation results from CabFare Connect
- [ ] Support multiple Subsidy Cards per trip for additional lifting fees

### Trip End and Subsidy Processing (if applicable)

- [ ] Implement `POST /meter/trip/end` — submit all fare details including base fare, extras, lifting fees, and Subsidy Scheme member details (if applicable) in cents
- [ ] Use the subsidy amount (if applicable) and remaining balance returned by CabFare Connect as the source of truth
- [ ] Handle `isSubsidyCalculationMatching: false` — always use CabFare Connect returned values in this case
- [ ] Display the remaining passenger-payable balance to the driver after subsidy processing

### Balance Payment

- [ ] Implement `POST /meter/payment/request` — submit `tripId` and `paymentAmount` in cents when driver selects card payment
- [ ] Implement `POST /meter/payment/cancel` — cancel a pending payment request if required
- [ ] Host `POST /payment/complete` — receive payment outcome from CabFare Connect and update display accordingly
- [ ] Handle payment failure — allow driver to select an alternative payment method
- [ ] Implement `POST /meter/job/done` — call after all payments are complete to close the trip and trigger Subsidy Provider reporting (if applicable)

### Receipt

- [ ] If configured with a Taxi Meter printer, print receipt including subsidy payment details (if applicable) after job done

## Key Technical Reminders

- All monetary amounts must be in cents as integers — never dollars as floats
- The `tripId` must be unique per trip — never reuse values from previous trips
- The `taxiMeterId`, `driverId`, and `vehiclePlate` must be consistent across all API calls within a session
- Return an immediate `200 OK` or `204 No Content` when receiving inbound events from CabFare Connect before processing the event
- Use `POST /meter/driver/poll` after connectivity loss to verify session state before resuming normal operation

## Support

Contact [support@cabfare.com](mailto:support@cabfare.com) for integration assistance. Refer to the Error Handling and Troubleshooting section for common issues and diagnostic guidance.

***

## Fleet Isolation Using Client IDs

CabFare Connect supports multiple fleet isolation under a single integration using the `clientIds` field. This allows a Taxi Meter provider to integrate once with CabFare Connect and manage multiple fleets — for example Fleet A and Fleet B — while keeping their data and operations entirely distinct within CabFare Connect.

### How It Works

The `clientIds` field accepts key-value pairs that you define. CabFare Connect uses these to differentiate between fleets when processing events and reporting data.

```json
{
  "taxiMeterId": "TM100",
  "driverId": "999998",
  "vehiclePlate": "M1000",
  "clientIds": {
    "fleetId": "FLEET-A",
    "networkId": "NET-001"
  }
}
```

### When to Use Client IDs

Use `clientIds` when:

- Your integration manages drivers and vehicles across multiple fleet operators
- You need CabFare Connect to isolate reporting and data by fleet
- You want to include additional reference data alongside the standard identifiers without creating separate integrations

### Where clientIds Can Be Submitted

The `clientIds` field is available on the majority of CabFare Connect API endpoints. Include it consistently on all requests for a given fleet to ensure correct isolation throughout the shift and trip lifecycle.

---
Source: https://docs.cabfare.com/api/taxi-meter-persona