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.

INFO

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

INFO

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

Balance Payment ​

Overview ​

Sequence Diagram ​

Step-by-Step ​

Step 1 — Taxi Meter displays remaining balance ​

Step 2 — Card payment path ​

Step 3 — Payment Terminal processes payment ​

Step 4 — Cash or other payment method ​

Step 5 — Multiple payment methods ​

Key Points ​