Balance Payment

overview the balance payment workflow collects the remaining passenger payable amount after all other payment components have been determined this includes the amount remaining after a subsidy scheme payment has been processed, or the full fare in a standard trip the taxi meter determines the payment method — if card, it instructs cabfare connect to request payment from the payment terminal if cash or another method, the payment terminal is not involved sequence diagram sequencediagram actor driver participant tm as taxi meter participant cc as cabfare connect participant pt as payment terminal tm >>driver displays remaining balance due alt card payment driver >>tm selects card payment tm >>cc post /meter/payment/request (taximeterid, driverid, tripid, paymentamount) cc >>pt post /payment/card (terminalid, driverid, tripid, paymentamount) pt >>driver prompts driver to present passenger card alt payment approved driver >>pt passenger presents card pt >>driver payment approved, prints receipt if configured pt >>cc post /terminal/payment/complete (terminalid, driverid, transactionid, paymentstatus success) cc >>tm post /payment/complete (paymentstatus success) tm >>driver displays payment success else payment declined or failed pt >>cc post /terminal/payment/complete (terminalid, driverid, transactionid, paymentstatus failed) cc >>tm post /payment/complete (paymentstatus failed) tm >>driver displays payment failure, driver takes next steps end else cash or other payment method driver >>tm selects cash or other payment method tm >>driver driver accepts payment directly end step by step step 1 — taxi meter displays remaining balance the taxi meter calculates and displays the remaining passenger payable balance for a subsidy scheme trip this is the fare amount minus the subsidy paid by subsidy provider for a standard trip this is the full fare the driver selects the payment method on the taxi meter step 2 — card payment path if the driver selects card payment the taxi meter sends a payment request to cabfare connect taxi meter calls post /meter/payment/request required fields taximeterid , driverid , tripid , paymentamount the paymentamount must be expressed in cents as an integer for example a balance of $15 50 must be submitted as 1550 cabfare connect forwards the payment request to the payment terminal cabfare connect calls post /payment/card on the payment terminal includes terminalid , driverid , tripid , paymentamount the payment terminal receives the amount and prompts the driver to present the passenger's card the payment terminal processes the payment as a blind amount — it does not need to know the fare breakdown step 3 — payment terminal processes payment the passenger presents their card to the payment terminal if the payment is approved the payment terminal may print a receipt if configured to do so the payment terminal notifies cabfare connect of the successful payment payment terminal calls post /terminal/payment/complete required fields terminalid , driverid , transactionid , paymentstatus cabfare connect forwards the payment outcome to the taxi meter cabfare connect calls post /payment/complete on the taxi meter if the payment is declined or fails the payment terminal notifies cabfare connect of the failed payment cabfare connect forwards the failure to the taxi meter the driver takes appropriate next steps on the taxi meter, such as selecting an alternative payment method edge case if the payment is approved on the payment terminal but a communications failure prevents the success notification reaching cabfare connect or the taxi meter, the driver can manually mark the payment as successful on the taxi meter and continue as normal confirm whether this manual override capability is implemented in the current version of the api step 4 — cash or other payment method if the driver selects cash, voucher, or another payment method the payment terminal is not involved the driver accepts payment directly from the passenger on the taxi meter the workflow proceeds directly to trip end step 5 — multiple payment methods a trip may involve multiple payment methods, for example a partial card payment and a partial cash payment the balance payment workflow supports multiple sequential payment requests within a single trip where the /meter/payment/request can be called more than once per trip key points the payment terminal processes card payments as a blind amount in cents — it does not need to know the fare breakdown post /terminal/payment/complete must be called for every payment attempt regardless of whether it was approved or declined the transactionid must be unique per payment transaction if card payment fails the driver selects an alternative payment method on the taxi meter if cash or another method is selected the payment terminal is not involved and the workflow proceeds directly to trip end