Skip to content
Go

Payment Lifecycle

Taxi & Private Hire › Products › Payment › Payment Lifecycle

Generally available

End-to-end pipeline that takes a trip segment from booking → Quote → Price → TripCharge → TripPayment. Handles preauth on booking, capture at archive, processor-webhook driven state changes, and the SHADOW / BILLING quote duality introduced by fixed-fare. Operators and developers use this as the source of truth for "where in the funnel is this charge stuck?" investigations.

Fields

FieldTypeDescription
tripSegment TripSegment The TripSegment this charge belongs to. Unique FK — at most one TripCharge per segment.
total int Final billable total in cents — what the customer will be charged (post-discount, post-uplift, including modifier + capability + tax line items).
preDiscountTotal integer Total before any discount was applied. Null when no discount fired. Useful for invoice presentation ("was X, now Y").
sourceSegmentQuoteId bigint BIGINT pointer to the segment-level Quote this charge was built from (the BILLING quote — see Quote.role). Snapshot — pricing edits do not retroactively change this link.
sourceTripQuoteId bigint BIGINT pointer to the trip-level Quote when singlePriced mode is active. Lets us identify which trip-level quote drove this segment's charge.
discountModelId bigint Discount-model ID (if any) that contributed to this charge. Null when no discount applied.
discountModelName string Snapshot of the discount-model name at the moment of pricing. Frozen so later renames don't corrupt historical invoices.
discountModelType DiscountModelType · RIDE_SHARE | SINGLE_PRICED_SHARE Discount-model classification (SINGLE_PRICED / RIDE_SHARE / etc.). Drives the apportionment + uplift logic that produced this row.
appliedDiscountType DiscountValueType · PERCENTAGE | ABSOLUTE Discount value type (PERCENT / FIXED_CENTS / etc.). Paired with `appliedDiscountValueSnapshot` to reconstruct exactly what discount was applied.
appliedDiscountValueSnapshot integer Numeric value of the discount as configured on the model at billing time (percent points or cents). Snapshot — survives later model edits.
appliedDiscountAmountCents integer Actual cents removed by the discount on this charge. Derived from `preDiscountTotal - total - uplift adjustments`.
appliedSharePercentage integer For multi-segment apportioned discounts: percentage share of the trip-level discount that landed on this segment. 0–10000 (basis points).
appliedUpliftPercentageSnapshot integer Uplift percentage snapshotted at billing (basis points). Lets the FE re-derive the gross-up applied to the discounted price.
preUpliftTotal integer Total before uplift was applied. Null when no uplift configured. Paired with `appliedUpliftPercentageSnapshot` for invoice transparency.
tripChargeItems Collection Line items composing this charge (base fare, modifier surcharges, capability fees, taxes, tips). orphanRemoval — deleting a charge cascades to its items.
status TripChargeStatus · SETTLED | OUTSTANDING Lifecycle status — DRAFT (computed but not locked), LOCKED (committed at archive), VOIDED (cancelled charge). Transitions are immutable once LOCKED outside corrective flows.
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.