# Edge Cases and Failure Scenarios

## Overview

This page documents known edge cases and failure scenarios that must be handled gracefully by integration partners. These scenarios fall outside the standard sunny day workflow but are expected to occur in production.

***

## Linking Failures

### Meter and Terminal Not Linking

**Scenario:** The driver is logged in on both devices but the link never completes.

**Causes:**

- `driverId` or `vehiclePlate` does not match between the Taxi Meter and Payment Terminal
- Driver is not yet logged in on the Taxi Meter when the Payment Terminal sends the link request
- Payment Terminal event handler for `POST /link/response` is not implemented or not reachable

**Resolution:**

1. Confirm `driverId` is identical on both devices
2. Confirm the Taxi Meter driver login has completed successfully before the Payment Terminal initiates the link request
3. Verify your `POST /link/response` endpoint is implemented and reachable by CabFare Connect
4. Poll current status using `POST /meter/driver/poll` and `POST /terminal/driver/poll` to confirm `loginStatus` and `linkStatus`

**Outcome if unresolved:** Both devices continue in unlinked mode. Standard trips and cash payments remain available. Subsidy Scheme processing is not available until devices are linked.

***

## Driver Login Succeeds but Subsidy Scheme Not Available

**Scenario:** Driver login returns `200 OK` but the UI shows Subsidy Scheme functions as unavailable.

**Cause:** The `mptpDriverData.mptpStatus` in the login response is `MPTP_DRIVER_INVALID`. The driver is not registered or is temporarily not permitted to provide Subsidy Scheme trips.

**Resolution:**

1. Inspect `mptpDriverData.mptpStatus` in the login response
2. If `MPTP_DRIVER_INVALID`, disable Subsidy Scheme functions but allow standard trips to continue
3. If the driver believes this is incorrect, contact CabFare support at [support@cabfare.com](mailto:support@cabfare.com) to verify driver registration status with the Subsidy Provider

***

## Trip Conflicts

### 409 Conflict on Trip Start

**Scenario:** `POST /meter/trip/start` returns `409 Conflict`.

**Cause:** An active trip already exists for this vehicle. The previous trip was not closed correctly.

**Resolution:**

1. Send `POST /meter/job/done` for the previous `tripId` to close the vehicle session
2. Retry `POST /meter/trip/start` with a new unique `tripId`
3. Do not reuse `tripId` values from previous trips

***

## Subsidy Card Failures

### Valid Card Rejected

**Scenario:** A Subsidy Card that the driver believes is valid is rejected by CabFare Connect.

**Causes:**

- Card is expired or cancelled in the Subsidy Provider's system
- Manual entry is using the wrong digits — the full card number rather than the last 9 digits
- Driver or vehicle is not authorised for Subsidy Scheme trips — `403 Forbidden` returned

**Resolution:**

1. Check `mptpMemberData.mptpStatus` in the validation response for the specific reason
2. If manual entry, verify the driver is entering only the last 9 digits of the card number
3. If `403 Forbidden`, check `mptpDriverData.mptpStatus` — the driver or vehicle may not be authorised
4. If the card appears valid but is still rejected, contact [support@cabfare.com](mailto:support@cabfare.com) with the member number and `tripId`

***

## Subsidy Calculation Mismatch

**Scenario:** `POST /meter/trip/end` returns `isSubsidyCalculationMatching: false`.

**Cause:** The subsidy or lifting fee amounts calculated by the Taxi Meter do not match CabFare Connect's calculation based on Subsidy Provider rules.

**Resolution:**

- Always treat CabFare Connect returned values as the source of truth in this case
- Use the returned `mptpSubsidyPaid`, `mptpLiftingFeePaid`, and `mptpTotalLiftingFeesPaid` values
- Present these values to the driver and record them for reconciliation
- Do not use the Taxi Meter's own calculated values for the Balance Payment step

***

## Payment Failures

### Payment Approved on Terminal but Not Reflected in CabFare Connect

**Scenario:** The EFTPOS Terminal prints a receipt confirming payment approval but the Taxi Meter does not receive a payment success notification.

**Cause:** A network or communications failure occurred between the Payment Terminal sending `POST /terminal/payment/complete` and CabFare Connect receiving it.

**Resolution:**

1. The driver can manually mark the payment as successful on the Taxi Meter and continue as normal
2. Ensure `POST /terminal/payment/complete` is retried by the Payment Terminal if no acknowledgement is received
3. Log the `transactionId` and `tripId` for reconciliation

### Payment Declined

**Scenario:** The card payment is declined on the Payment Terminal.

**Resolution:**

1. The Payment Terminal sends `POST /terminal/payment/complete` with `paymentStatus` set to failed
2. CabFare Connect forwards the failure to the Taxi Meter via `POST /payment/complete`
3. The driver selects an alternative payment method on the Taxi Meter — cash, voucher, or another card

***

## Network and Connectivity Failures

### Request Timeout

**Scenario:** A request to CabFare Connect times out with no response.

**Resolution:**

1. Log the full request details including timestamp, endpoint, and all relevant identifiers
2. Retry the request using the same `tripId` and `transactionId` — do not generate new identifiers on retry
3. Use `POST /meter/driver/poll` or `POST /terminal/driver/poll` to verify session state before retrying session-dependent endpoints

### Connectivity Loss Mid-Session

**Scenario:** The device loses network connectivity during an active shift or trip.

**Resolution:**

1. Maintain trip state locally on the device
2. On reconnection, use the poll endpoints to verify current session state
3. Re-send any missing events using the original identifiers
4. CabFare Connect uses `tripId` and `transactionId` to detect duplicate submissions — retrying with the same identifiers is safe

***

## Shift End Failures

### Shift End Data Not Submitted

**Scenario:** The driver logs out but shift end data is not received by CabFare Connect.

**Cause:** Network failure during `POST /meter/driver/logout`, or shift end data not included in the logout request.

**Resolution:**

1. Ensure `POST /meter/driver/logout` always includes all required shift end data if any Subsidy Scheme trips were processed during the shift
2. Retry the logout request using the same identifiers if no acknowledgement is received
3. Contact [support@cabfare.com](mailto:support@cabfare.com) if shift data cannot be submitted after repeated retries

---
Source: https://docs.cabfare.com/api/edge-cases-and-failure-scenarios