Taxi Meter Persona

View as Markdown

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

{
  "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.