# 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

```mermaid
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

---
Source: https://docs.cabfare.com/api/balance-payment