TrustRide’s booking system lets riders search for published intercity trips, choose their exact seat from a visual map, and reserve it instantly with a 30-minute window to complete payment. This guide covers the entire booking journey — from search through completion, including seat states, lifecycle statuses, and post-trip ratings.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Muhammadbugaje/trustride/llms.txt
Use this file to discover all available pages before exploring further.
Searching for Trips
The search endpoint acceptsGET query parameters and returns published, active trips that have not yet departed.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
origin | No | Case-insensitive partial match on origin city/state |
destination | No | Case-insensitive partial match on destination |
departure_date | No | Exact date filter (YYYY-MM-DD) |
passengers | No | Minimum available seats required (default: 1) |
min_price | No | Lower bound on price per seat (₦) |
max_price | No | Upper bound on price per seat (₦) |
vehicle_type | No | Filter by vehicle type (sedan, suv, minivan, etc.) |
departure_time | No | Time-of-day slot: morning, afternoon, or evening |
gender_filter | No | anyone (default), ladies_only, or gentlemen_only |
ladies_only trips, and a female rider will never see gentlemen_only trips.
HTMX Live Availability
The homepage “Upcoming Rides” section polls a dedicated HTMX endpoint to show real-time seat counts without a full page reload:Seat Selection
After a rider navigates to a trip detail page (/trip/<uuid>/), they are shown an interactive seat map rendered from the vehicle’s seat_layout JSON. Seats are laid out in labelled rows (A1, A2, B1, B2, etc.) up to the vehicle’s seating_capacity.
Seat States
| State | Meaning |
|---|---|
| available | The seat is free and can be booked |
| reserved | Held by another rider — payment pending (expires in 30 minutes) |
| confirmed | Payment verified — seat is permanently occupied |
| unavailable | Seat does not exist or has been disabled |
reserved, pending_verification, or confirmed) are passed to the template to render the correct visual state for each seat.
Booking Lifecycle
A booking moves through the following statuses from creation to resolution.reserved
Seat is held for the rider. Payment has not yet been made. The booking expires automatically after 30 minutes if unpaid.
pending_verification
The rider has uploaded a payment receipt. The driver is reviewing it before confirming the seat.
confirmed
The driver has approved the payment. The seat is secured and a confirmation email with a QR ticket is sent to the rider.
completed
The trip has ended. The rider can now submit a rating for the driver.
cancelled
The booking was cancelled by either the rider or driver before confirmation. The seat is immediately released.
expired
The rider did not complete payment within 30 minutes. The seat is released automatically and the next waitlisted rider is notified.
refunded
The rider requested and received a refund after payment was confirmed. The seat is released back to the trip.
Booking Flow
Search for a trip
Use
GET /search/ with your origin, destination, and travel date. Browse the results and select a trip that fits your schedule and budget.View the trip detail
Navigate to
GET /trip/<uuid>/ to see the full trip details — departure time, price, driver profile, vehicle information, and the live seat map.Select a seat
Click an available seat on the visual map. You can select multiple seats by passing comma-separated seat IDs. The seat map shows which seats are already taken in real time.
Submit the booking
Post the booking request to reserve your chosen seat(s). The system creates a A system chat message is automatically created in the booking thread, containing the driver’s bank details and transfer instructions.
Booking record in reserved status and starts the 30-minute payment timer.Upload payment receipt
Transfer the fare to the driver’s bank account and upload a photo or screenshot of the receipt via the booking chat thread (
POST /chat/upload-receipt/<uuid>/). The booking status moves to pending_verification.Booking Success URL
After a successful booking POST, the rider is redirected to the booking success page:ids query parameter carries all booking IDs when multiple seats were reserved in a single transaction. The success page displays the driver’s bank details, total amount due, and a countdown to payment expiry.
Booking Management
Riders manage their bookings from/my-bookings/ and individual booking detail pages.
Booking Detail
Cancel a Booking
Either the rider or the driver can cancel an unconfirmed booking. The seat is released immediately and the other party receives an in-app notification.Cancellation is only available for bookings in
reserved or pending_verification status. Once a booking is confirmed, use the refund flow instead.Request a Refund
Riders with aconfirmed booking can request a refund before the trip departs:
/driver/refunds/.
Rate a Completed Trip
After a booking reachescompleted status, the rider can leave a one-time rating for the driver:
Booking Expiry
TrustRide uses a Celery-powered expiry system to prevent seat hoarding. Any booking inreserved state that has not been paid within the configured window (default: 30 minutes) is automatically expired.
The expiry timestamp is stored in the payment_expiry field on each Booking and is set at creation time:
release_expired_bookings utility is called on every trip detail page load and before any new booking attempt, ensuring the seat map always reflects current reality. When a seat is released by expiry, the notify_next_in_waitlist function is called to alert the next queued rider.
The expiry window is configurable platform-wide via the
booking_expiry_minutes key in AppSetting. The default is 30 minutes.Rating System
TheRating model captures post-trip feedback from riders about their driver (and optionally vice versa).
Rating Fields
| Field | Type | Description |
|---|---|---|
trip | FK | The trip being rated |
reviewer | FK | The user leaving the rating |
reviewee | FK | The user being rated |
rating | integer | Score from 1 (Poor) to 5 (Excellent) |
review_text | text | Optional written comment |
completed, and only if the reviewer has not already submitted a rating for that trip-reviewer-reviewee combination (enforced via unique_together). A rider cannot rate themselves, and only participants of the trip (driver or booked riders) can submit ratings.