Appearance

Edge Cases and Failure Scenarios ​

View as Markdown

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 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 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 if shift data cannot be submitted after repeated retries