Skip to content
Go

Payment Preauthorisations

Taxi & Private Hire › Products › Payment › Payment Preauthorisations

Generally available

A hold placed against the customer's payment method when the trip is booked, guaranteeing funds are available before the ride starts. Lifecycle: HELD on booking → CAPTURED at trip-end (becomes a TripPayment) or RELEASED (canceled / failed). Indexed by processorRef for correlating processor webhook callbacks. Multiple preauths per segment are allowed for retry / void-and-replace scenarios.

Settings

How operators configure this feature.

Hold the right amount on the card up front

Pre-authorising a card before the trip protects you against unpaid fares and covers extras like waiting time or tolls. This sets how much to hold as a percentage of the estimated fare — enough to cover the likely total without over-holding a customer's money and triggering complaints.

SettingRangeDefault
Pre-auth amount (% of fare)
How much to hold on the card, as a percent of the estimated fare (120 = fare plus 20%).
 100–200 120

Fields

FieldTypeDescription
tripSegment TripSegment Segment this preauth was held against. ManyToOne — segments can carry multiple preauths over the course of held → voided → reissued cycles.
total int Amount held in cents. Typically matches the quoted trip total at booking — when the final TripCharge differs, the gap is captured via a separate top-up payment.
status TripPreAuthStatus · CREATED | APPROVED | CAPTURED | VOID Lifecycle status — HELD (active hold) / CAPTURED (converted to payment) / RELEASED (voided). Drives the trip-end conversion flow + processor webhook reconciliation.
authCode string Processor authorization code returned on successful hold. Surfaced in support tooling for trace + reconciliation.
processorName string Upstream processor identifier (`mockpay`, `stripe`, `adyen`). Paired with `processorRef` for cross-references to the processor-side record.
processorRef string Processor's identifier for this authorisation (e.g. Stripe `pi_xxx`). Used for capture / void / reconciliation calls and inbound-webhook correlation. Indexed.
tripCharge TripCharge TripCharge this preauth is attached to. Established at booking; persists through capture / release.
tripPayment TripPayment The TripPayment created when this preauth was captured. Null while the preauth is still HELD or has been RELEASED without capture.
clientId bigint Tenant scope. Every tenant-aware entity carries this; `ClientFilter` enforces row-level isolation on read; the multi-tenancy routing layer (`/client/{clientId}`) sets it at create time. Surfaced only under `admin` / `tripLog` groups — never to end users.
internalKey string Optional client-supplied external reference / idempotency key. When present, lets external systems correlate platform-side records back to their own source-of-truth ids. Not persisted to a column — populated by the request handler when the caller sets it.
__objectType string Discriminator string (entity class short-name) emitted alongside the id in serialized output. Resolved at read time by `getObjectType()`; lets the FE dispatch entity-specific rendering without inspecting the URL.
id bigint Snowflake-style primary key (unsigned BIGINT). Generated by `IdFactory` at create time; surfaced to the FE / API as a `G`-prefixed string and stripped back to plain bigint server-side before Doctrine lookup.
createdDate integer Unix timestamp the row was first persisted. Set in the entity's PrePersist hook; never rewritten on subsequent updates.
updatedDate integer Unix timestamp the row was last touched. Bumped on every commit that hits the Doctrine UoW for this entity; drives FE invalidation + the listing change cursor.
passiveUpdatedDate int Read-through alias for `updatedDate` exposed under different serializer groups. Lets the FE distinguish "real edit" from "background touch" projections without changing the underlying column.
listingUpdatedDate int Listing-projection timestamp surfaced only under the `listMode` group. Driven by `TripCache` and other listing-shape refreshers separately from `updatedDate` so a listing rebuild doesn't trigger detail-page invalidation.