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 confirm driverid is identical on both devices confirm the taxi meter driver login has completed successfully before the payment terminal initiates the link request verify your post /link/response endpoint is implemented and reachable by cabfare connect 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 inspect mptpdriverdata mptpstatus in the login response if mptp driver invalid , disable subsidy scheme functions but allow standard trips to continue 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 send post /meter/job/done for the previous tripid to close the vehicle session retry post /meter/trip/start with a new unique tripid 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 check mptpmemberdata mptpstatus in the validation response for the specific reason if manual entry, verify the driver is entering only the last 9 digits of the card number if 403 forbidden , check mptpdriverdata mptpstatus — the driver or vehicle may not be authorised 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 the driver can manually mark the payment as successful on the taxi meter and continue as normal ensure post /terminal/payment/complete is retried by the payment terminal if no acknowledgement is received log the transactionid and tripid for reconciliation payment declined scenario the card payment is declined on the payment terminal resolution the payment terminal sends post /terminal/payment/complete with paymentstatus set to failed cabfare connect forwards the failure to the taxi meter via post /payment/complete 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 log the full request details including timestamp, endpoint, and all relevant identifiers retry the request using the same tripid and transactionid — do not generate new identifiers on retry 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 maintain trip state locally on the device on reconnection, use the poll endpoints to verify current session state re send any missing events using the original identifiers 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 ensure post /meter/driver/logout always includes all required shift end data if any subsidy scheme trips were processed during the shift retry the logout request using the same identifiers if no acknowledgement is received contact support\@cabfare com mailto\ support\@cabfare com if shift data cannot be submitted after repeated retries