PRD — Ride Lifecycle, Fare, Payments (Provider-Agnostic) & ETA at Scale

Currency: COP (v1) Scope: Backend API / “system of record” for rides, fares, payment intents, settlement outcomes, and ETA exposure.

1. Introduction

1.1 Purpose of the Document

This PRD specifies the complete functional and non-functional requirements for a mobility backend that supports: ride lifecycle, fare finalization, provider-agnostic payment orchestration, and ETA exposure at scale. It is written to be unambiguous, testable, and auditable, serving as the single product contract for stakeholders (Product, Engineering, QA, Security, Risk, Operations).

This document defines what must happen, when, and how correctness is measured, without prescribing architecture, algorithms, frameworks, or vendor-specific workflows.

1.2 Business Context (Sector Reality)

In ride-hailing, the platform’s credibility and revenue depend on:

• State integrity (rides cannot “teleport” between states; terminal states are final).
• Pricing integrity (fare must be deterministic, explainable, and immutable post-completion).
• Payment integrity (no duplicate capture, clear outcomes, safe retries).
• Supportability (operators must resolve disputes using evidence, not guesswork).
• Scale behaviors (ETA produces high-QPS read amplification; payments produce high-risk write flows).
• Compliance (PCI-DSS, OWASP, privacy regulation, security controls are non-optional).

1.3 Objectives and Success Metrics (OKRs)

O1 — Revenue Integrity & Customer Trust

• Duplicate successful settlements caused by the platform: 0 (per quarter).
• Completed rides with a recorded canonical settlement outcome: 100%.
• Payment-related support tickets per 1,000 rides: decreasing trend, target baseline established in pilot.

O2 — Deterministic Ride/Fare Correctness

• Illegal ride state transitions accepted: 0.
• Fare mismatch between stored fare and charged amount: 0.

O3 — ETA at Scale Without Harming Core Flows

• ETA freshness contract met or explicitly degraded: ≥ 99.9%.
• Critical write SLOs remain compliant during peak ETA traffic.

1.4 Tenancy and Isolation Model (Explicit)

This system is not a multi-tenant SaaS platform.

• There is no global tenant identifier.
• Isolation is enforced through explicit domain concepts:
  • Resource ownership (e.g., rides owned by a rider)
  • Role-based scope (client app vs ops)
  • Geographic scope (market/city) where applicable

Any requirement phrased as “tenant isolation” MUST be implemented as ownership/scope checks defined in this PRD, not via a global tenantId.

2. Scope

2.1 In Scope

• Ride state machine (authoritative) and lifecycle operations.
• Fare computation contract (inputs, outputs, determinism, audit).
• Provider-agnostic Payment Intent creation and Settlement tracking.
• Provider-agnostic error normalization and retry semantics.
• ETA exposure in four product contexts: Eyeball, Dispatch, Pickup, On-Trip.
• Audit trails, compliance controls, and operational reporting requirements.

2.2 Out of Scope (v1)

• Refunds/chargebacks/dispute workflows (explicitly deferred, but data must support future).
• Driver supply/matching strategies.
• Map/routing algorithm choices and ownership.
• Promotions/dynamic pricing.

2.3 Users (Personas)

End-user perspective

• Rider: cares about correct ETA, transparent fare, correct charge, and receipt.

Platform perspective

• Client App: calls the API reliably under mobile network failures and retries.
• Support/Operations: needs evidence to resolve “I was charged twice” or “fare was wrong”.
• Risk/Fraud: needs signals and controls to reduce abuse and chargebacks.
• Finance/Reconciliation: needs ledger-like data correctness and settlement traceability.
• Security/Compliance: ensures PCI/OWASP/privacy controls are met.

2.4 Primary Benefits

• Prevent double charges and missing charges (core business survival).
• Maintain consistent ride progress and fare explainability.
• Enable payment provider swap without contract changes.
• Provide ETA at scale with honesty and controlled degradation.

2.5 Scope and Ownership (Authorization Model Inputs)

The following scope concepts are part of the product contract and MUST be enforceable:

• Rider ownership: A rider may only read/write rides they own.
• Ride linkage: Payment intents and settlement outcomes are scoped to a ride and inherit the ride’s ownership rules.
• Operational scope: OPS roles may access evidence/audit within defined policy scope (see §6.2), without write capabilities.
• Geographic scope (where applicable): Requests may be restricted to a market/city boundary, if the deployment requires it.

No global tenant isolation semantics exist.

3. System Overview

3.1 System Function (Big Picture)

The system is the system of record for:

• Ride state transitions
• Fare finalization
• Payment intent creation and settlement outcomes
• ETA exposure status (including degradation metadata)

3.2 Operating Environment

• Multi-client consumption (mobile/web/server), unreliable networks, retries.
• Peak loads, burst traffic, and partial dependency failures.
• Separation of environments with strict data/secret isolation.
• Authorization must be correct under retries and concurrent requests (no “best effort” access checks).

3.3 Architecture General (Non-prescriptive)

The product requires strict separation between:

• Domain contract (rides, fare, payment intent, settlement) and
• External dependencies (payment providers, ETA signal providers), so that vendor changes do not alter the public product semantics.

4. Functional Requirements

4.1 Ride Management (Authoritative State Machine)

4.1.1 Ride States

CREATED, DISPATCHING, ASSIGNED, STARTED, COMPLETED, CANCELED, EXPIRED, FAILED

Terminal: COMPLETED, CANCELED, EXPIRED, FAILED (immutable)

4.1.2 Allowed Transitions (Exhaustive)

• Normal: CREATED → DISPATCHING → ASSIGNED → STARTED → COMPLETED
• Cancel: CREATED|DISPATCHING|ASSIGNED → CANCELED
• Expire: CREATED|DISPATCHING|ASSIGNED → EXPIRED
• Fail: CREATED|DISPATCHING|ASSIGNED|STARTED → FAILED

All other transitions MUST be rejected as STATE_CONFLICT.

4.1.3 Cancellation and Expiration Rules (Real-world)

• Rider cancellation allowed only before STARTED.

• System cancellation allowed in any non-terminal state with mandatory reason codes.

• Expiration MUST be policy-driven with explicit timers (v1 defaults are permitted and must be documented). Business Default v1:

  • DISPATCHING expires after 120s without assignment.
  • ASSIGNED expires after 300s without STARTED.

4.1.4 Concurrency and Retries (Behavioral Contract)

When conflicting terminal transitions are requested concurrently (cancel/complete/fail):

• Exactly one terminal transition may succeed.
• The losing request MUST receive a deterministic conflict response containing the current authoritative state.

4.2 Fare (COP) — Deterministic and Explainable

4.2.1 Inputs (Required)

• baseFareCOP (integer pesos ≥ 0)
• distanceKm (decimal ≥ 0)
• durationMinutes (decimal ≥ 0)

4.2.2 Outputs (Required)

• totalFareCOP (integer pesos)
• fareBreakdown (base, distance, time, minimumApplied)

4.2.3 Determinism Rules

• Currency is COP (integer pesos). No fractional pesos in external contract.
• Rounding is deterministic: round up to the nearest peso.
• Minimum fare applies: totalFareCOP ≥ minimumFareCOP. Business Default v1: minimumFareCOP = 5,000.

4.2.4 Auditability Rules (Support + Finance)

The system MUST store enough evidence to reproduce the fare output:

• inputs used (base, distance, duration, applied minimum)
• calculation timestamp (UTC)
• pricing version identifier (not an implementation detail; a functional contract for change control)

4.3 Payments — Provider-Agnostic Payment Intent + Settlement

This is where industry “implicit rules” matter most.

4.3.1 Canonical Concepts

• Payment Intent: immutable business record describing what must be collected for a completed ride.
• Settlement Attempt: an action to collect funds against a Payment Intent.
• Settlement Outcome: canonical state representing the authoritative result.

The public product contract MUST NOT expose provider-specific terms (e.g., “acceptance token”, “link”, “capture”), but the domain must still represent them through canonical semantics.

4.3.2 Payment Intent Rules (Non-negotiable)

• A Payment Intent MUST be created exactly once when the ride becomes COMPLETED.
• Payment Intent MUST bind to: rideId, riderId, amountCOP, currency=COP, fareBreakdown, createdAtUTC.
• Payment Intent amount and currency MUST be immutable once created.

4.3.3 Canonical Settlement Outcomes (Authoritative)

• PENDING (non-terminal)
• SUCCEEDED (terminal)
• DECLINED (terminal; requires rider action for further attempts)
• FAILED (terminal; retry may be allowed)
• UNKNOWN (terminal v1; outcome cannot be determined within bounded time)

4.3.4 Anti-Duplication and Financial Integrity

• A ride MUST NOT have more than one SUCCEEDED settlement outcome, ever.
• A repeated settlement initiation request MUST NOT produce multiple successful charges (must be prevented under retries and timeouts).
• Settlement must be idempotent with respect to Payment Intent and client idempotency key.

4.3.5 Multiple Attempts Policy (Industry reality)

Declines happen; networks fail; tokens expire. The product must formalize attempt policy:

Business Default v1:

• Max settlement attempts per ride: 3.
• New attempt allowed only when last state is FAILED or UNKNOWN.
• DECLINED requires rider action (e.g., change payment method) before a new attempt is permitted.
• Attempts beyond limit must be blocked with a deterministic PAYMENT_POLICY_VIOLATION.

4.3.6 Unpaid Definition (Formal)

A ride is UNPAID iff:

• ride state is COMPLETED, and
• the latest settlement state is not SUCCEEDED.

UNPAID is derived; it is not a ride state.

4.3.7 Receipts and User Evidence (End-user lens)

Upon settlement completion (success or definitive failure), the system MUST provide:

• a user-facing receipt payload (safe fields only)
• a support-facing evidence payload (includes normalized reason codes, timestamps, attempt count)

4.4 ETA Exposure (Four Contexts, Read Amplification, Honest Degradation)

4.4.1 ETA Contexts (Authoritative)

• EYEBALL (destination preview)
• DISPATCH (driver assignment optimization)
• PICKUP (time to pickup)
• ON_TRIP (live arrival updates)

4.4.2 ETA Contract (Required Fields)

Every ETA response MUST include:

• etaContext
• computedAtUTC
• either etaSeconds (integer ≥ 0) OR explicit absence
• isDegraded boolean
• degradationReason when degraded
• freshnessSeconds (computedAtUTC to now, in seconds)

4.4.3 Freshness Policy (Explicit, Non-ambiguous)

Business Default v1:

• ON_TRIP and PICKUP: max age 10s
• DISPATCH and EYEBALL: max age 30s If older, response MUST be degraded with STALE_INPUT_DATA OR no ETA with degradation.

4.4.4 Degradation Reasons (Authoritative Set)

• INSUFFICIENT_LOCATION_SIGNAL (GPS noise/sparsity)
• STALE_INPUT_DATA
• DEPENDENCY_UNAVAILABLE
• RATE_LIMITED
• UNKNOWN

4.4.5 Scale and “Do Not Harm” Rule

ETA requests MUST be treated as “high-QPS reads” and MUST NOT degrade:

• ride completion
• payment intent creation
• settlement initiation

Even under peak ETA traffic. If necessary, ETA may degrade (explicitly), but core writes must remain within SLO.

5. Non-Functional Requirements

5.1 Performance (SLOs)

Critical writes:

• Complete ride (fare finalization + payment intent): p95 ≤ 300ms, p99 ≤ 800ms
• Initiate settlement: p95 ≤ 500ms, p99 ≤ 1200ms

Reads:

• ETA: p95 ≤ 150ms, p99 ≤ 400ms
• Ride status: p95 ≤ 150ms, p99 ≤ 400ms
• Settlement status: p95 ≤ 200ms, p99 ≤ 500ms

5.2 Scalability (Explicit Load Model)

The system MUST support (single region baseline):

• 100,000 concurrent active rides
• up to 1,000 ETA reads per ride (expected worst-case)
• peak 50,000 ETA RPS while preserving critical write SLOs

5.3 Usability and Accessibility

API usability requirements:

• Deterministic errors with errorType, retryable, requestId, optional retryAfterSeconds.
• Backward-compatible evolution: versioned contract changes, documented deprecations.

5.4 Maintainability (Product-level)

• Swapping payment providers MUST NOT require public contract changes.
• Canonical states and invariants must remain stable across versions.
• Change control for pricing rules (pricing version) must be auditable.

6. Security Requirements

6.1 Compliance (Mandatory)

The system MUST comply with:

• PCI-DSS (scope minimized by never handling raw cardholder data; tokenized references only)
• OWASP Top 10 and OWASP API Security Top 10 (input validation, auth, access control, rate limiting, logging, SSRF protections, etc.)
• Applicable privacy regulations (GDPR-like principles; and if operating in Colombia, align with local data protection requirements)

6.2 Authentication and Authorization

• All endpoints require authentication.
• Authorization MUST enforce resource ownership and role-based scope (not tenancy).
  • Rider access MUST be limited to rides they own.
  • Client App access MUST be limited to authorized capabilities for that app.
  • OPS_READONLY MUST be read-only and limited to evidence/audit access.
  • Where applicable, market/city scope MUST be enforced explicitly.
• The system MUST NOT implement a global tenant-based authorization model.

Roles (v1):

• CLIENT_APP (write + read within scope)
• OPS_READONLY (read evidence and audit within scope)

6.3 Data Protection

• Encryption in transit required.
• Secrets must never be exposed in logs.
• Payment tokens and PII must be redacted in logs and responses.
• Data retention policies must be defined and enforced (see below).

6.4 Data Retention (Business Default v1)

• Ride + fare + settlement audit: retain 5 years (financial/audit typical).
• PII (email, optional identifiers): retain as short as legally/operationally necessary, default 180 days unless policy requires longer.

7. Use Cases (Selected Core)

UC-01 Create Ride

Actor: Client App
Preconditions: authenticated rider; request within permitted scope
Description: create ride request
Inputs: riderId, origin, destination
Outputs: rideId, rideState, timestamps

UC-02 Complete Ride

Actor: Client App
Preconditions: STARTED; valid metrics
Description: finalize fare and create payment intent
Outputs: COMPLETED, fare, paymentIntentId

UC-03 Initiate Settlement

Actor: Client App
Preconditions: COMPLETED; payment intent exists; token reference
Description: initiate settlement attempt; record canonical outcome
Outputs: settlementState, attemptCount, retryable

UC-04 Query ETA (On-trip)

Actor: Client App
Preconditions: STARTED
Description: retrieve ETA with freshness + degradation rules
Outputs: etaSeconds or absent, freshnessSeconds, isDegraded, reason

8. Diagrams (MermaidJS)

stateDiagram-v2
  [*] --> CREATED
  CREATED --> DISPATCHING
  DISPATCHING --> ASSIGNED
  ASSIGNED --> STARTED
  STARTED --> COMPLETED

  CREATED --> CANCELED
  DISPATCHING --> CANCELED
  ASSIGNED --> CANCELED

  CREATED --> EXPIRED
  DISPATCHING --> EXPIRED
  ASSIGNED --> EXPIRED

  CREATED --> FAILED
  DISPATCHING --> FAILED
  ASSIGNED --> FAILED
  STARTED --> FAILED

  COMPLETED --> [*]
  CANCELED --> [*]
  EXPIRED --> [*]
  FAILED --> [*]

9. Integrations and Dependencies

Internal

• Ride lifecycle service (state machine)
• Fare finalization service
• Payment intent + settlement state service
• Audit/evidence service
• Error normalization contract

External (Provider-agnostic)

• Payment provider(s) (interchangeable)
• Optional location/ETA signal sources

10. Constraints and Assumptions

Constraints

• COP only (v1)
• No raw cardholder data accepted or stored
• One successful settlement per ride
• The system is not multi-tenant; no global tenant identifier exists. Isolation is enforced via ownership/role/geographic scope defined in this PRD.

Assumptions

• Client supplies distance and duration at completion (or a trusted upstream source exists).
• Payment provider may be asynchronous; outcome may be pending or unknown.

11. Acceptance Metrics (KPIs)

• Duplicate successful settlement rate: 0
• Missing payment intent for completed rides: 0
• SLO compliance (critical vs read): ≥ 99.9%
• ETA freshness compliance: ≥ 99.9% (or explicit degradation)
• Audit completeness: 100%

12. Impact Analysis

• ETA read amplification is the dominant load driver; product must require explicit degradation and non-blocking behavior.
• Payments require strong evidence capture; finance/support workflows depend on canonical outcomes.

13. Risk Management Plan

• Retry storms: enforce idempotency and attempt limits.
• Provider outages: canonical UNKNOWN with evidence and support visibility.
• Fraud/abuse: policy gates and evidence signals (without prescribing detection mechanisms).
• Compliance drift: periodic audits and policy enforcement requirements.

14. Future Considerations

• Refunds/chargebacks/disputes (must reuse evidence model)
• Multiple payment intents per ride (beyond v1 limits)
• Multi-currency, tax/fees
• ETA quality analytics and continuous calibration governance

15. Glossary

• Payment Intent
• Settlement Outcome
• Derived UNPAID
• ETA Freshness
• Degradation
• Scope: Authorization boundary defined by ownership, role, and/or geographic constraints (not tenancy).
• Tenant: SaaS isolation construct intentionally not used in this system.