Skip to main content

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.

TrustRide does not integrate a payment gateway. Instead, it uses a manual bank transfer workflow that matches how intercity travel payments already work in Nigeria — riders transfer money directly to a bank account and provide proof. This approach eliminates gateway fees, works without card infrastructure, and supports riders who prefer cash-based banking.
TrustRide has no payment gateway integration. Do not attempt to add or reference Paystack, Flutterwave, Stripe, or any other online payment processor. All payment flows in the codebase are manual bank-transfer-based and must remain so.

​
Payment Philosophy

After a rider books a seat, the platform presents the driver’s (or admin’s) bank details on the booking success page and inside the booking chat thread. The rider completes the transfer through their bank’s mobile app or USSD, then uploads a screenshot or photo of the receipt. The driver reviews the receipt and confirms or rejects the payment — no intermediary holds funds at any point. The payment_destination setting in AppSetting controls whether riders pay into the driver’s personal account or a central platform account configured by the admin.

​
Receipt Upload Flow

1

Rider receives bank details

Immediately after booking, the system generates an automatic chat message in the booking thread containing the bank name, account number, and account holder name. The same details appear on the booking success page (/booking-success/<uuid>/).
2

Rider completes the bank transfer

The rider transfers the exact fare amount shown for their seat(s) to the provided account. The total is calculated as price_per_seat × number_of_seats.
3

Rider uploads the receipt

The rider uploads a JPEG, PNG, or PDF proof of payment (max 5 MB) via the booking chat. Uploading the receipt changes the booking status from reserved to pending_verification.
POST /chat/upload-receipt/<uuid:booking_id>/
Content-Type: multipart/form-data

receipt_image=<file>
A system chat message is posted to notify the driver that the receipt is awaiting review.
4

Driver reviews the receipt

The driver opens the booking chat thread and inspects the uploaded receipt image. Payment receipts are stored in ChatMessage.receipt_image and are flagged with is_verified=False until the driver confirms them.

​
Driver Approval

Once the driver is satisfied that the transfer is legitimate, they confirm the payment. This can be done from two places: From the trip management page (HTMX-enhanced row action): 
POST /booking/<uuid:booking_id>/approve/
This endpoint performs the following actions:
  1. Set booking.status to confirmed
  2. Record booking.confirmed_at = timezone.now()
  3. Send a booking confirmation email with a QR e-ticket to the rider
  4. Create an in-app Notification for the rider
  5. Post a system chat message confirming the approval
A second approval path — POST /chat/verify-payment/<uuid:booking_id>/ — exists in the chat app’s URL configuration but currently routes to views.coming_soon while the full chat feature is pending activation. Use /booking/<uuid:booking_id>/approve/ for all payment confirmations.

​
Refund Flow

1

Rider requests a refund

A rider with a confirmed booking can request a refund by submitting a reason. Refundable bookings are those whose trip has not yet departed.
POST /booking/<uuid:booking_id>/refund/
Content-Type: application/x-www-form-urlencoded

reason=Travel plans changed
A Refund record is created with status requested. The driver receives a notification.
2

Driver reviews the request

The driver sees all pending refund requests at /driver/refunds/. They can approve or reject each one.
# Approve
POST /refund/<uuid:refund_id>/approve/

# Reject (with optional reason)
POST /refund/<uuid:refund_id>/reject/
reason=Cancellation window has passed
3

Refund is processed

On approval, the Refund.approve() method runs inside an atomic transaction:
  • Sets refund.status = 'approved'
  • Increments trip.available_seats by 1
  • Deletes the Booking record (the booking UUID is preserved on the Refund for auditing via booking_uuid)
  • Notifies the next rider on the waitlist
A refund approval email is sent to the rider, and a system chat message is posted in the booking thread before the booking record is removed.
4

Admin escalation (optional)

If a dispute cannot be resolved between the rider and driver, the admin can review the refund from the Django admin panel and set the status to admin_review, approved, or rejected directly.

​
Refund Status Choices

StatusMeaning
requestedRider has submitted a refund request; awaiting driver response
driver_respondedDriver has reviewed but escalated to admin
admin_reviewAdmin is reviewing the dispute
approvedRefund granted; booking deleted and seat released
rejectedDriver or admin declined the refund
partialA partial amount was refunded (admin-initiated)
The refund policy page is available at /refund-policy/. Riders are encouraged to review it before requesting a refund.

​
Payout Model

The Payout model tracks what the platform owes each driver after deducting the platform commission. Payouts are created and managed by the admin.

​
Payout Fields

FieldTypeDescription
driverFKThe driver receiving the payout
amountdecimalGross amount collected from riders for this payout period
commissiondecimalPlatform commission rate as a percentage (0–100)
net_amountdecimalAmount actually paid out to the driver
statuschoicepending, processing, completed, failed, or cancelled
reference_numberstringBank transaction reference for reconciliation
processed_datedatetimeWhen the payout was sent to the driver’s account
notestextInternal admin notes about the payout
bookingsM2MThe individual bookings included in this payout period

​
Net Amount Formula

The net_amount is calculated automatically on save if not explicitly provided: 
net_amount = amount × (1 - commission / 100)
For example, a driver with a 10% commission rate on ₦45,000 in collected fares receives: 
net_amount = 45000 × (1 - 10 / 100) = 45000 × 0.90 = ₦40,500

​
Commission Structure

Each driver’s commission rate is stored on their User model as commission_rate. This rate is applied at payout time — not at the moment of booking. The admin creates payout records after confirming that bookings have been completed, using the driver’s current rate to calculate the net amount.

​
Payment Reference

Each Booking has an optional payment_reference field (up to 100 characters) for storing the bank transfer reference number that the rider provides. This helps drivers and admins cross-check receipts against bank statements during verification. 
# The rider can include the reference when uploading their receipt
payment_reference=TRF/20250315/00012345
The field is nullable — it is only populated when the rider or driver records the reference manually.

Build docs developers (and LLMs) love

Get started for freeTalk to us