Payments & Collections Module

The Payments module (/payments) is the cashflow heart of BiiTrust. It handles all counter cash receipts, bank deposit slips, mobile money collections via Safaricom M-Pesa, automated repayment waterfall allocation, and payment reversal auditing.

1. Key Definitions & Concepts

2. Navigating the Payments Workspace (/payments)

The main Payments view provides an interactive, filterable ledger of all institutional collections:

┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Payments & Collections                                     [ + Take Repayment ] [ Reconcile ]   │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ [ All ] [ Today ] [ Cash ] [ M-Pesa ] [ Bank ] [ Reversals ] [ Suspense / Unallocated (3) ]     │
├─────────────┬──────────────┬──────────────┬──────────────┬─────────────┬───────────┬────────────┤
│ Reference   │ Date & Time  │ Client       │ Loan #       │ Amount      │ Channel   │ Status     │
├─────────────┼──────────────┼──────────────┼──────────────┼─────────────┼───────────┼────────────┤
│ PMX-098231  │ Today, 14:15 │ Mary Wanjiku │ LOX-004821   │ KES 12,500  │ M-Pesa    │ Allocated  │
│ PMX-098230  │ Today, 13:40 │ Peter Otieno │ LOX-003912   │ KES 4,200   │ Cash      │ Allocated  │
│ PMX-098229  │ Today, 11:10 │ John Kamau   │ LOX-005104   │ KES 25,000  │ Bank Slip │ Allocated  │
│ PMX-098228  │ Today, 09:22 │ Unassigned   │ [PENDING]    │ KES 3,500   │ M-Pesa    │ Suspense   │
└─────────────┴──────────────┴──────────────┴──────────────┴─────────────┴───────────┴────────────┘

Table Columns & Indicators

• Reference: System transaction ID (prefixed with PMX-) or M-Pesa 10-character code (SJL89X2KLM).
• Date & Time: Exact timestamp of receipt entry or Daraja webhook confirmation.
• Client & Loan #: Clickable links navigating directly to the borrower’s Customer 360 profile or the Loan Detail screen.
• Amount: Formatted currency figure with color indicators (Green for active allocations, Gray for reversals).
• Channel: Visual badge:
  • 🟩 M-Pesa: Settled via mobile money API.
  • 🟦 Cash: Collected physically at branch counter.
  • 🟪 Bank: Deposited into institutional bank account.
• Status:
  • Allocated: Applied to loan schedule installments.
  • Suspense: Parked in unallocated queue awaiting borrower matching.
  • Reversed: Voided by authorized manager; offsetting journal posted.

3. Taking a Repayment at the Counter (/loans/repay or Shortcut R)

When a client walks up to the teller window to make a payment:

Step 1: Find the Loan Facility

1. Click Take Repayment or hit shortcut key R.
2. In the borrower search field, type the client’s name, National ID, phone number, or loan number (LOX-...).
3. The system displays the client summary card:
   • Client full name and portrait photograph for positive visual identification.
   • Active loan product, total outstanding balance, and overdue amount.
   • Days Past Due (DPD) and penalty accrual.

Step 2: Enter Payment Details

1. Amount Received: Enter the exact amount handed over (e.g., KES 15,000).
2. Channel Selection:
   • Cash: Cash drawer receipt.
   • M-Pesa (Manual / Offline): Customer already paid via Paybill but automated callback lagged; enter the 10-character M-Pesa receipt code.
   • Bank Slip: Enter bank name and teller deposit slip number.
3. Transaction Date: Defaults to current system date and time.
4. Notes / Narrative: Optional field for cash drawer notes or deposit slip verification remarks.

Step 3: Allocation Preview

The system dynamically computes and renders the live allocation preview before you commit:

• Penalties Cleared: e.g., KES 500
• Fees Cleared: e.g., KES 250
• Interest Paid: e.g., KES 2,250
• Principal Reduction: e.g., KES 12,000
• New Outstanding Balance: Displayed in bold green.

Step 4: Confirm & Print Receipt

1. Click Post Repayment.
2. A thermal receipt modal opens automatically.
3. Click Print Receipt (triggers connected POS receipt printer) or Send SMS Receipt.

4. Initiating an M-Pesa STK Push

To collect money digitally without asking the borrower to navigate complex Paybill menus:

1. Open the borrower’s active loan page (/loan/:hex).
2. Click Request Payment (STK Push) in the primary action bar.
3. Confirm Phone Number: Defaults to the borrower’s registered M-Pesa phone number (+254 7...). You can edit it if they are paying from an alternate phone.
4. Amount: Defaults to the current amount due (installment + overdue fees). You can override this to any custom amount.
5. Click Send PIN Prompt:
   • The platform dispatches a request to Safaricom’s Daraja API.
   • A pulsing spinner appears: “Waiting for customer to enter PIN on handset…”
   • The borrower receives the instant SIM toolkit overlay on their mobile device.
   • Once they enter their M-Pesa PIN, Safaricom sends an encrypted confirmation callback.
   • The modal switches to a green checkmark: “Payment Confirmed: SJL89X2KLM - KES 8,500 applied successfully.”
   • The loan schedule updates instantly in real time without refreshing the page.

5. Resolving Orphan & Suspense Payments (/mpesa)

When a customer pays via Paybill but enters an incorrect reference number (e.g., typos in their National ID or entering their vehicle registration number instead of their loan number), the funds cannot be automatically matched.

Reconciliation Workflow

1. Navigate to Payments $\to$ Suspense / Unallocated filter tab.
2. Select the unmatched payment line (e.g., KES 6,000 from 0712-345678, Ref: SKM9912AZX, Input Account: 'LOAN').
3. Click Reconcile Transaction.
4. In the lookup modal, search for the rightful borrower by phone number or name.
5. Select the target active loan (LOX-009122).
6. Review the resulting waterfall allocation preview.
7. Click Confirm Match & Allocate:
   • The transaction leaves the Suspense account (2190 M-Pesa Clearing Suspense).
   • The funds are credited to the borrower’s loan account (1210 Loans Receivable, 4110 Interest Income).
   • An automated SMS notification is dispatched to the customer’s phone acknowledging receipt.

6. Payment Reversals & Audit Trail (/payments/:hex/reverse)

Mistakes happen (e.g., a teller accidentally credits Loan A instead of Loan B). To prevent fraud, reversals require elevated managerial authority and leave an indelible audit trail.

Step-by-Step Reversal Flow

1. Open the payment receipt record (/payments/:hex).
2. Click Reverse Payment (restricted to manager, director, or accountant).
3. Step 1 — Verify Exposure: Review the original payment details, date, allocation breakdown, and affected installments.
4. Step 2 — Mandatory Justification: Enter a detailed, formal explanation (minimum 15 characters, e.g., “Customer paid cash for account LOX-0042, teller keyed LOX-0024 by mistake. Verified against physical counter receipt #4412”).
5. Step 3 — Confirm Reversal:
   • The payment status switches to reversed.
   • The affected installment schedule rows revert to their previous unpaid status.
   • Overdue penalty counters recalculate as if the payment had never occurred.
   • The general ledger generates an automated mirror reversing entry:
     • Debit: 1210 Loans Receivable (Principal)
     • Debit: 4110 Interest Income
     • Debit: 4120 Fee Income
     • Credit: 1101 Branch Cash Drawer (or M-Pesa Clearing)
   • The reversal event is permanently stamped with the authorizing manager’s user ID, IP address, and timestamp.