This post walks through why a taxi booking system ends up with two state machines, one for the trip and one for the payment, and the decisions that sit between them.

Two lifecycles, not one

The trip lifecycle is operational. In a typical taxi workflow it looks something like:

requested -> confirmed -> driver_assigned -> driver_on_way
          -> driver_arrived -> passenger_on_board -> completed

with cancelled reachable from most states. Drivers and dispatchers move it forward.

The payment lifecycle is financial and is driven by the card processor:

none -> authorised -> captured -> (partially_)refunded
     \-> failed
authorised -> cancelled (authorisation released)

These move independently. A trip can be completed while the payment is still authorised, or failed. A payment can be captured at booking time while the trip hasn't started. If you collapse both into one field, you lose the ability to say "the job is done but we haven't collected the money", which is exactly the state your office needs to see.

The rule worth writing down: a completed trip is not proof of payment.

Capture policy is a business decision

With card processors like Stripe you can capture immediately, or authorise first and capture later. For taxis, both make sense depending on the job:

• Immediate capture is simplest. The customer pays when they book or accept a quote. Good for fixed-price jobs where the fare won't change.
• Authorise now, capture later suits work where the final fare may change, or where you only want to take money once the job is real. You then need a trigger: capture on confirmation, on completion, or at a set time before pickup.

Making this a configurable policy, rather than hard-coding it, lets an operator run airport transfers one way and hourly bookings another. It also means your capture job has to handle edge cases. Authorisations don't last forever (for online card payments it's typically around seven days with Stripe, so check the current docs for your card types), so a booking made two weeks ahead can't simply be authorised at booking time and captured on the day.

Make the transitions idempotent

Payment events arrive late, twice, or out of order. A few general habits help:

• Use idempotency keys on every create, capture and refund call, derived from your own booking and attempt IDs.
• Store the processor's object IDs on your payment record and treat the processor as the source of truth for financial state.
• Only allow legal transitions. A refund against a payment that was never captured should be rejected by your code, not by the processor.
• Keep an event log per payment so the office can see what happened and when.

Refunds belong to the payment, not the trip

Cancelling a trip and refunding a payment are separate actions. An operator may cancel and keep a cancellation fee, or refund part of a fare after a complaint on a completed trip. Supporting partial refunds against the payment record, without touching trip state, keeps both histories honest.

Payouts are accounting, not money movement

The other side of a taxi business is paying drivers. It's tempting to model "payout processed" as if money moved. Unless your system actually initiates a bank transfer, be explicit that processing a payout is a record. In Australia, a practical middle ground is generating an ABA file the operator uploads to their bank. The system marks the records as paid; the bank moves the money.

If you want the broader picture of how a booking gets from the website form to a driver, I wrote about that in how a taxi booking form and a dispatch board fit together.

How BookTaxiService does it

BookTaxiService is a browser-based booking and dispatch platform for taxi operators in Australia and New Zealand, built by 2203 Pty Ltd in Melbourne. A few of its payment design choices line up with the points above:

• Operator fares go through the operator's own Stripe credentials. It does not use Stripe Connect for operator fare checkout.
• Immediate capture is the default. Authorisation and later capture are available under configured policies, which can trigger capture on confirmation, on completion or before pickup.
• Payment status is tracked separately from trip status, which moves through driver on way, arrived, passenger on board and completed.
• Full and partial refunds are issued from the payment workflow.
• Card details go into Stripe's payment fields. The platform doesn't store full card numbers; for saved cards it keeps Stripe's reference plus the last four digits, expiry and cardholder name.
• Driver payout processing records payments as paid and, on plans that include it, exports Australian ABA files. It doesn't transfer money itself.

The full feature description is on the BookTaxiService payments and driver payouts page.

Takeaway

If you're building anything where a service is delivered and paid for at different moments, give each its own state machine and decide up front which events are allowed to move each one. It costs a second column and a few more tests. It saves you from guessing, months later, whether "completed" meant the driver finished or the money arrived.