Billing & Invoicing
Manage payments, generate invoices, and track revenue from your shipments.
What It Does
The Billing module handles shipment payment tracking, invoice generation (PDF), payment gateway integration, and financial reconciliation. Every shipment can generate a professional invoice, and payments can be collected manually or through integrated gateways.
| Detail | Value |
|---|---|
| Who uses it | Admin (full access), Employee (billing view) |
| Menu path | Finance → Billing |
| Required permission | settings.billing.view |
Payment Flow
Payments are tracked at the shipment level. When creating or editing a shipment, you set the payment status and method.
-
1
Set Payment Status
When creating a shipment, set the payment status: Unpaid, Pending, or Paid.
-
2
Select Payment Method
For "Paid" shipments, select the payment method: Manual, Stripe, or PayPal.
-
3
Process Payment
Manual: Optionally upload a payment proof image (bank transfer screenshot, receipt photo).
Stripe / PayPal: The customer is redirected to the payment gateway. The payment is processed automatically and the status updates on success.
Payment Status Badges
| Status | Meaning | Badge Color |
|---|---|---|
| Unpaid | No payment recorded. Invoice outstanding. | Red |
| Pending | Payment initiated but not yet confirmed (e.g., bank transfer in progress). | Amber |
| Paid | Payment received and confirmed. Invoice settled. | Green |
| Void | Invoice cancelled. Excluded from financial totals. | Gray |
Invoice Generation
Each shipment can generate a professional PDF invoice. Invoices are generated on demand from the shipment detail page or the billing list.
Invoice Contents
- Tracking number and shipment reference
- Sender and receiver names and addresses
- Package details — weight, dimensions, description
- Price breakdown — subtotal, tax, discount, total
- Company branding — logo, name, address, tax ID
- QR code for online payment (if configured)
Invoice Configuration
Customize the invoice appearance and content in Settings → Billing:
| Setting | Description |
|---|---|
| Invoice Theme | Professional template with your branding colors |
| Tax Number | Your company tax registration number printed on invoices |
| Terms | Payment terms text displayed at the bottom of the invoice |
| Footer Notes | Custom notes printed in the invoice footer area |
| Signature Image | Upload a signature image to display on invoices |
Export Options
- Individual PDF — download a single invoice from the shipment detail or billing list
- Bulk Billing Report PDF — select multiple shipments and export a consolidated billing report with organization branding
Billing Report
The billing report provides a financial overview of all invoiced shipments for a given period.
Features
- Date range filter — select start and end dates to narrow the report
- Shipment list — shows all invoiced shipments with tracking number, client, service, amount, and payment status
- Totals summary — total billed, total collected, outstanding balance
- PDF export — download the report as a branded PDF with your organization logo and details
Reconciliation
The reconciliation view compares revenue collected against costs incurred for each shipment, helping you understand profitability.
- Revenue vs. Cost per shipment — see the margin on each delivery
- Period-based report — aggregate reconciliation data by week, month, or custom date range
- PDF export — download the reconciliation report for accounting or audit purposes
Payment Gateways
Payment gateways are configured in Settings → Billing. Each gateway can be enabled independently and supports a test mode for development and staging environments.
Stripe
Credit and debit cards, Apple Pay. Provides the broadest international coverage. Requires Stripe API keys (publishable + secret).
PayPal
PayPal balance, credit and debit cards via PayPal checkout. Requires PayPal Client ID and Secret.
Paystack
Cards, bank transfer, and mobile money. Optimized for African markets (Nigeria, Ghana, South Africa, Kenya). Requires Paystack public and secret keys.
Gateway Configuration Fields
| Field | Description |
|---|---|
| Enabled | Toggle the gateway on or off |
| Test Mode | Use sandbox/test API keys for development. No real charges are processed. |
| API Keys | Public key (client-side) and secret key (server-side) from the provider dashboard |
| Webhook URL | Auto-generated URL to receive payment confirmation callbacks from the provider |
Test mode before going live
Always enable Test Mode first and process a few test payments to verify the integration works correctly. Once confirmed, switch to live mode with your production API keys.
Billing Permissions
| Action | Permission | Default Roles |
|---|---|---|
| View billing list and invoices | settings.billing.view | Super Admin, Admin |
| Mark invoice as paid | settings.billing.view | Super Admin, Admin |
| Download / export PDF invoices | settings.billing.view | Super Admin, Admin |
| Void an invoice | settings.billing.view | Super Admin, Admin |
| Configure payment gateways | settings.billing.update | Super Admin, Admin |
The Employee and Driver roles do not have direct access to the billing module. Employees can see the shipment total on the shipment detail page but cannot manage invoices. The Customer role can view their own invoices through the customer portal.
Troubleshooting
| Problem | Solution |
|---|---|
| Invoice PDF shows blank company logo | Upload your logo in Settings → Company Profile. The logo must be a PNG or JPG file. |
| Stripe payment fails with "Invalid API key" | Verify the API keys in Settings → Billing → Stripe. Ensure you are using test keys for test mode and live keys for production. |
| Payment status not updating after gateway payment | The webhook URL may not be configured in your payment provider's dashboard. Copy the webhook URL from Settings and add it to your Stripe/PayPal/Paystack dashboard. |
| Invoice total shows $0.00 | The shipment has no rate assigned. Verify that a matching Rate Card exists for the shipment's route, or assign a price manually in the shipment form. |
| Billing report PDF export is slow | For large date ranges with hundreds of invoices, the PDF generation may take 30+ seconds. Narrow the date range or wait for the background notification. |