Processing Driver Payouts in the TrustRide Admin Panel

TrustRide collects ride payments from riders on behalf of drivers. Admins periodically create payout records that capture how much a driver earned, deduct the platform’s commission, and initiate a manual bank transfer to the driver’s account. The Payout model tracks every payout from creation through to completion or failure.

All monetary values in TrustRide are denominated in Nigerian Naira (₦). Commission rates are stored as percentages (e.g., 20.00 means 20%). The net_amount field always represents what the driver actually receives, after commission is deducted.

The Payout Model

The Payout model (apps/payments/models.py) stores one record per payment period per driver. Its full field set is:

Field	Type	Description
`driver`	FK → User	The driver receiving the payout. Limited to users with `role = "driver"`.
`amount`	DecimalField	Total fare collected from riders in this period (before commission).
`commission`	DecimalField (0–100)	The platform’s commission percentage applied to this payout.
`net_amount`	DecimalField	Amount actually transferred to the driver. Auto-calculated on save.
`status`	CharField	Current lifecycle state. See Payout Status Lifecycle.
`processed_date`	DateTimeField	Timestamp when the bank transfer was initiated. Nullable.
`reference_number`	CharField	Bank transaction reference or ID provided by the bank.
`notes`	TextField	Free-text admin notes (e.g., “Q1 settlement — Abuja routes”).
`bookings`	ManyToManyField → Booking	The individual bookings included in this payout period.

The model also inherits id (UUID), created_at, and updated_at from UUIDModel and TimeStampedModel.

# apps/payments/models.py — net_amount auto-calculation
def save(self, *args, **kwargs):
    if not self.net_amount:
        self.net_amount = self.amount * (1 - self.commission / 100)
    super().save(*args, **kwargs)

Commission Rate

Each driver has a commission_rate field on their User model (default 0.00%). This is the platform’s cut from every payout to that driver. The rate is set per driver by the admin and can differ between drivers depending on their agreement with TrustRide.

# apps/users/models.py
commission_rate = models.DecimalField(
    max_digits=5,
    decimal_places=2,
    default=0.00,
    verbose_name='commission rate (%)'
)

Net Amount Formula

The net_amount is calculated as:

net_amount = amount × (1 - commission / 100)

Example:

Item	Value
Fare collected from riders	₦10,000
Driver’s commission rate	20%
Platform deduction	₦10,000 × 0.20 = ₦2,000
Net payout to driver	₦10,000 × (1 − 0.20) = ₦8,000

If net_amount is left blank when saving a Payout record, the model computes it automatically. If you supply a net_amount explicitly (for example to apply a manual adjustment), the auto-calculation is skipped.

Revenue Tracking

Before creating payout records, review per-trip revenue at: GET /control/revenue/trips/ This page lists all active trips and, for each trip, shows a breakdown of bookings by status:

Column	Description
Reserved	Bookings awaiting payment
Pending	Bookings pending payment verification
Confirmed	Paid and confirmed bookings
Completed	Completed bookings
Cancelled	Cancelled bookings
Expired	Expired unpaid reservations
Refunded	Refunded bookings
Revenue	Sum of `price` for all `confirmed` bookings on this trip

The page footer shows platform-wide totals for revenue, reserved, confirmed, and pending counts across all active trips.

Creating a Payout

When a driver has accumulated completed bookings that are ready for settlement, you create a Payout record through the Django admin at /admin/ (note: Payout records are managed through Django’s built-in admin, not the custom panel). The workflow is:

Review revenue for the driver

Open /control/revenue/trips/ and identify all trips driven by the target driver with confirmed or completed bookings. Note the total confirmed revenue.

Confirm the driver's bank details

Open the driver’s profile at /control/users/<id>/. Check their UserProfile for bank_name, bank_account_name, and bank_account_number. If any field is blank, contact the driver to update their details before proceeding.

Confirm the driver's commission rate

On the same profile page, note the driver’s commission_rate. If it needs adjusting before this payout, update it now.

Create the Payout record

In the Django admin (/admin/payments/payout/add/), create a new Payout with:

Driver — select the correct driver
Amount — the total fare collected (e.g., ₦10,000)
Commission — the driver’s commission_rate (e.g., 20.00)
Net amount — leave blank to auto-calculate, or enter manually for adjustments
Status — set to pending
Bookings — select all the Booking records included in this settlement period
Notes — add a brief description (e.g., “Lagos–Abuja routes, 1–15 Jan 2025”)

Save the record

Save the payout. The net_amount is computed automatically if not provided. The record is now in pending status.

Manual Bank Transfer Process

TrustRide uses manual bank transfers rather than an automated payment gateway for driver payouts. Admins initiate the transfer outside the platform and record the outcome in the payout record.

Change status to Processing

Open the payout record and set status = "processing". This signals that a transfer has been initiated but not yet confirmed. Record the current date/time as processed_date.

Initiate the bank transfer

Using your bank’s internet banking portal or mobile app, transfer the net_amount to the driver’s account (bank name, account name, account number from their profile). The amount must match the payout’s net_amount exactly.

Obtain the transaction reference

After the transfer, your bank provides a transaction reference number (sometimes called a session ID or transaction ID). Copy this value.

Record the reference number

Return to the payout record and paste the bank’s transaction reference into the reference_number field. This is the audit trail linking the platform record to the actual bank transaction.

Mark as Completed

Once you have confirmed the transfer has settled (typically same-day for Nigerian instant transfers), set status = "completed". Add any relevant notes.

Handle failures

If the transfer is rejected or reversed by the bank, set status = "failed" and note the reason in the notes field. Contact the driver to resolve the banking issue, then create a new payout record once their details are corrected.

Nigerian instant bank transfers (NIP) via NIBSS typically settle within seconds to minutes. If a transfer shows as pending for more than 30 minutes, contact your bank’s support line. Do not mark a payout as completed until you have confirmed receipt on the driver’s end or via your bank statement.

Payout Status Lifecycle

A payout moves through the following states:

pending → processing → completed
                    ↘ failed
         cancelled (from pending or processing)

Status	Meaning
`pending`	Payout record created; bank transfer not yet started
`processing`	Bank transfer initiated; awaiting confirmation
`completed`	Transfer confirmed; driver has received funds
`failed`	Bank transfer failed or was reversed
`cancelled`	Payout voided before transfer was made

Never set a payout to completed before the bank transfer is initiated. If the reference_number field is blank, the payout should still be in pending or processing state. A completed payout with no reference number creates an unauditable gap in your financial records.

Associating Bookings with a Payout

The bookings ManyToManyField links specific Booking records to each payout. This lets you:

Avoid double-paying the same booking in two separate payouts.
Reconcile platform revenue by checking which bookings have been settled.
Audit any payout dispute by viewing the exact bookings it covers.

When creating a payout manually, select only bookings with status = "confirmed" or "completed" for the relevant driver and time period. Reserved or pending bookings should not be included until payment is fully confirmed.

Get Started

Core Features

Users & Roles

Admin & Operations

Deployment

Processing Driver Payouts in the TrustRide Admin Panel

The Payout Model

Commission Rate

Net Amount Formula

Revenue Tracking

Creating a Payout

Manual Bank Transfer Process

Payout Status Lifecycle

Associating Bookings with a Payout

Build docs developers (and LLMs) love

Get Started

Core Features

Users & Roles

Admin & Operations

Deployment

Documentation Index

​The Payout Model

​Commission Rate

​Net Amount Formula

​Revenue Tracking

​Creating a Payout

​Manual Bank Transfer Process

​Payout Status Lifecycle

​Associating Bookings with a Payout

Build docs developers (and LLMs) love

The Payout Model

Commission Rate

Net Amount Formula

Revenue Tracking

Creating a Payout

Manual Bank Transfer Process

Payout Status Lifecycle

Associating Bookings with a Payout