Repayments - Millenium Potters

Overview

The Repayments system handles all aspects of loan payment processing, from recording individual payments to tracking schedule compliance and managing partial payments. Every payment is automatically allocated against the borrower’s repayment schedule.

Repayments are automatically allocated to schedule items, paying interest first, then principal, following industry best practices.

Repayment Data Model

From the Prisma schema:

model Repayment {
  id     String @id @default(cuid())
  loanId String
  loan   Loan
  
  receivedByUserId String
  receivedBy       User    // Staff who recorded payment
  
  amount       Decimal           @db.Decimal(14, 2)
  currencyCode String            @default("NGN")
  paidAt       DateTime          // When payment was made
  method       RepaymentMethod
  reference    String?           // Transaction reference
  notes        String?
  
  allocations RepaymentAllocation[]  // How payment was distributed
  
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime?
}

enum RepaymentMethod {
  CASH      // Cash payment
  TRANSFER  // Bank transfer
  POS       // Point of Sale terminal
  MOBILE    // Mobile money (e.g., M-Pesa)
  USSD      // USSD code payment
  OTHER     // Other methods
}

Payment Allocation Model

model RepaymentAllocation {
  id String @id
  
  repaymentId    String
  repayment      Repayment
  
  scheduleItemId String
  scheduleItem   RepaymentScheduleItem
  
  amount    Decimal  @db.Decimal(14, 2)
  createdAt DateTime @default(now())
}

Each repayment can be split across multiple schedule items. The system tracks exactly how much of each payment went to which installment.

Recording a New Repayment

Method 1: From Repayments Page

Navigate

Go to Business Management → Repayments

Add Payment

Click + Add Repayment button

Select Loan

Search and select the loan receiving payment

Enter Details

Required Fields:

Amount - Payment amount in Naira
Payment Date - When payment was made
Payment Method - How payment was received

Optional Fields:

Reference Number - Transaction ID, check number, etc.
Notes - Any additional information

Record

Click Record Repayment to saveSystem automatically:

Allocates payment to schedule items
Updates loan balance
Marks schedule items as paid/partial
Calculates remaining balance

Method 2: From Loan Detail Page

Open Loan

Navigate to the specific loan’s detail page

Add Payment

Click Add Repayment button in the loan details

Enter Payment Info

Loan is pre-selected, fill in payment details

Save

Click Record Repayment

Method 3: From Repayment Schedules

Navigate to Schedules

Go to Business Management → Repayment Schedules

Find Due Payment

Locate the schedule item you’re collecting

Quick Payment

Click Pay Due for exact amount paymentORClick Custom for partial or different amount

Confirm

Enter payment method and reference, then save

Payment Methods

CASH

Physical cash payment collected in person

TRANSFER

Bank transfer or electronic funds transfer

POS

Card payment via Point of Sale terminal

MOBILE

Mobile money transfer (M-Pesa, etc.)

USSD

Payment via USSD banking code

OTHER

Any other payment method

Best Practices by Method

CASH Payments

Count cash carefully before recording
Issue receipt immediately
Store securely until banking
Record exact denominations in notes if large amount

TRANSFER Payments

Always get transaction reference number
Verify transfer in bank account
Match amount exactly
Record sender name in notes

POS/Card Payments

Ensure transaction approved before recording
Save POS receipt
Record approval code as reference
Give customer their receipt copy

MOBILE Money

Get confirmation SMS/code
Verify money received in mobile wallet
Record transaction ID
Note mobile number used

Payment Allocation Logic

The system automatically allocates payments using this priority:

Find Overdue

Identify all overdue schedule items (past due date, unpaid)

Sort by Date

Sort overdue items by due date (oldest first)

Allocate to Interest

Apply payment to interest portion first

Allocate to Principal

Apply remaining amount to principal

Move to Next Item

If schedule item fully paid, move to next overdue item

Handle Excess

If payment exceeds all overdue amounts, apply to next due installment

Example Allocation

Payment Allocation Example

Scenario:

Schedule Item 1: ₦10,000 due (Jan 1) - ₦5,000 paid, ₦5,000 outstanding
Schedule Item 2: ₦10,000 due (Feb 1) - ₦0 paid, ₦10,000 outstanding
Payment received: ₦12,000

Allocation:

₦5,000 → Schedule Item 1 (completes it, status: PAID)
₦7,000 → Schedule Item 2 (partial, status: PARTIAL)
Remaining on Item 2: ₦3,000

Result:

Item 1: Closed (closedAt set)
Item 2: Partially paid
Loan outstanding reduced by ₦12,000

API Endpoint

// POST /api/repayments
const createRepayment = async (data: {
  loanId: string;
  amount: number;
  method: 'CASH' | 'TRANSFER' | 'POS' | 'MOBILE' | 'USSD' | 'OTHER';
  paidAt: Date;
  reference?: string;
  notes?: string;
}) => {
  // Records payment
  // Auto-allocates to schedule items
  // Updates loan balances
  // Returns repayment with allocations
}

Viewing Repayment History

All Repayments View

Navigate

Go to Business Management → Repayments

Browse Payments

See complete payment history with filters

Available Filters

Date Range

Filter payments by payment date range

Loan

View payments for a specific loan

Payment Method

Filter by CASH, TRANSFER, POS, etc.

Received By

See payments recorded by specific staff member

Repayment List Columns

Date - When payment was made
Loan Number - Associated loan
Borrower - Member who paid
Amount - Payment amount in Naira
Method - How payment was received
Reference - Transaction reference
Received By - Staff who recorded it
Actions - View details, edit, delete

For a Specific Loan

Open Loan Details

Navigate to the loan

Payment History Tab

Click Payment History tab

View Payments

See all payments for this loan with allocation details

Repayment Schedules Management

The Repayment Schedules page provides powerful tracking:

This is your daily operations hub for managing collections across all loans

Access Schedules

Navigate

Go to Business Management → Repayment Schedules

View Dashboard

See summary cards and detailed schedule list

Summary Cards

Total Schedules

Total number of payment schedules matching filters

Pending Payments

Count of unpaid, non-overdue installments

Overdue

Number of payments past their due date

Total Amount Due

Sum of all pending and overdue amounts (in Naira)

Summary cards update automatically based on your active filters

Advanced Filtering

Search by Borrower

Type borrower name to filter schedules

Filter by Union

Select a union from searchable dropdown to view its schedules

Filter by Union Member

Select specific member to see their payment schedule

Filter by Credit Officer

View schedules for loans managed by specific officer

Filter by Status

PENDING - Not yet paid, not overdue
PAID - Fully paid
PARTIAL - Partially paid
OVERDUE - Past due date and unpaid

Date Range Filter

Three modes:

Today Only - Payments due today
Single Date - Pick one specific date
Date Range - Select start and end dates

Amount Range

Filter by minimum and maximum due amount

Schedule List Features

Sorting

Click column headers to sort by:

Due date
Borrower name
Amount due
Status
Union

Pagination

Adjustable rows per page (10, 20, 50, 100)
Next/Previous navigation
Jump to specific page

Quick Actions

Pay Due - Record exact scheduled amount
Custom - Record partial or different amount
View Loan - Open full loan details

Visual Indicators

Color-coded status badges:

🟡 Yellow - Pending
🟢 Green - Paid
🔵 Blue - Partial
🔴 Red - Overdue

Handling Different Payment Scenarios

Exact Payment (On Schedule)

Member pays exact installment amount on time

Action:

Record payment with exact schedule amount
System marks schedule item as PAID
Sets closedAt timestamp
Moves to next installment

Best Practice: Use “Pay Due” button for quick entry

Partial Payment

Member pays less than scheduled amount

What Happens:

Record actual amount paid
System marks schedule item as PARTIAL
Tracks paidAmount vs totalDue
Shortfall carries to next collection
Interest continues to apply

Example:

Due: ₦10,000
Paid: ₦7,000
Remaining: ₦3,000
Status: PARTIAL

Next Steps:

Follow up with borrower
Document reason in notes
Track cumulative shortfall

Overpayment

Member pays more than current installment

Allocation Logic:

Full amount applied to current schedule item (closes it)
Excess applied to next overdue item (if any)
Remaining excess applied to next future installment
Loan completes early if total paid

Example:

Due this month: ₦10,000
Paid: ₦15,000
Allocation:
- ₦10,000 → Current item (PAID)
- ₦5,000 → Next item (PARTIAL or PAID)

Benefit: Reduces total interest, accelerates loan completion

Late Payment

Payment received after due date

Status Flow:

Schedule item marked OVERDUE when due date passes
Penalty fees may apply (based on loan settings)
When paid, item changes to PAID
Late payment is noted in history

Actions:

Calculate any penalty fees
Add penalty to payment if applicable
Document late reason
Follow up on future payments

Multiple Payments in One Day

Borrower makes several payments same day

Handling:

Record each payment separately
System allocates them in order recorded
Each creates separate allocation records
All show same paidAt date

Best Practice: Combine into one payment when possible for cleaner records

Editing Repayments

Only Administrators and Supervisors can edit or delete repayments. Credit Officers have read-only access to payment history.

Locate Payment

Find the repayment in the list

Open Editor

Click the Edit icon

Modify Fields

Can change:

Payment date
Amount (recalculates allocations)
Payment method
Reference number
Notes

Cannot change:

Associated loan
Received by user

Save Changes

Click Save - system re-allocates payment

Editing a payment amount triggers re-allocation across schedule items

Deleting Repayments

Use with extreme caution. Deleting a repayment:

Removes allocation records
Reopens schedule items
Increases loan outstanding balance
Cannot be undone

Find Payment

Locate the repayment to delete

Delete Action

Click Delete icon (trash can)

Confirm

Review the warning message

Verify Impact

System shows impact on loan and schedule

Confirm Deletion

Click Confirm Delete

Repayments are soft deleted (marked with deletedAt) for audit purposes

Repayment Summary and Reports

Summary Endpoint

// GET /api/repayments/summary?loanId=xxx&dateFrom=2024-01-01&dateTo=2024-12-31
const getRepaymentSummary = async (filters: {
  loanId?: string;
  dateFrom?: string;
  dateTo?: string;
}) => {
  return {
    totalRepayments: number;    // Count of payments
    totalAmount: number;         // Sum of amounts
    averageAmount: number;       // Average payment size
    byMethod: {                  // Breakdown by method
      CASH: number;
      TRANSFER: number;
      // etc.
    };
    byMonth: Array<{             // Monthly trends
      month: string;
      count: number;
      amount: number;
    }>;
  };
}

Collections by Union

Track collection performance by union:

// GET /api/repayments/collections-by-union
const getCollectionsByUnion = async (filters: {
  dateFrom?: string;
  dateTo?: string;
  unionId?: string;
  creditOfficerId?: string;
}) => {
  // Returns union-level collection data
}

Collections Report Shows

Union name
Number of active loans
Total collected
Collection rate percentage
Overdue amount
Credit officer name

Best Practices

Recording Payments

Record payments on the day received
Double-check amounts before saving
Always get transaction references
Issue receipts to borrowers
Add notes for unusual circumstances

Payment Methods

Use correct payment method
For TRANSFER, wait for bank confirmation
For CASH, count in front of borrower
Keep POS receipts for 90 days
Verify MOBILE money before recording

Schedule Monitoring

Check schedules daily
Follow up on overdue items promptly
Use “Today Only” filter each morning
Contact borrowers before due dates
Track patterns in late payments

Data Accuracy

Verify loan before recording
Confirm amount with borrower
Save reference numbers
Don’t delete repayments unnecessarily
Keep audit trail clear

Daily Workflow

Morning Check

Filter schedules by “Today Only”
Review all payments due today
Note borrowers to contact

During the Day

Record payments as received
Issue receipts immediately
Follow up on missed payments

End of Day

Reconcile cash collected
Verify all payments recorded
Check overdue list
Prepare next day’s contacts

Troubleshooting

Cannot record repayment

Check:

Loan exists and is ACTIVE
Amount is positive and reasonable
Payment date is valid
You have necessary permissions
Loan isn’t already completed

Payment allocated incorrectly

Reason: System follows interest-first allocationSolution:

This is intentional behavior
Contact administrator if business rules need adjustment
Document in notes if different allocation expected

Cannot edit payment

Possible reasons:

You lack permission (Credit Officer role)
Loan is completed or closed
Payment is part of completed loan

Solution: Contact Supervisor or Administrator

Schedule item still showing overdue after payment

Check:

Payment was properly allocated
Amount paid was sufficient
Status updated (may need page refresh)
System processed allocation

Solution: Refresh page or contact support

Missing repayments in history

Verify:

Date range filter includes the dates
Loan filter is correct
Repayments weren’t deleted
You have permission to view them

API Reference

// Get all repayments
GET /api/repayments?page=1&limit=20&loanId=xxx&method=CASH&dateFrom=2024-01-01&dateTo=2024-12-31

// Get repayment by ID
GET /api/repayments/:id

// Create repayment
POST /api/repayments
Body: {
  loanId: string;
  amount: number;
  method: 'CASH' | 'TRANSFER' | 'POS' | 'MOBILE' | 'USSD' | 'OTHER';
  paidAt: Date;
  reference?: string;
  notes?: string;
}

// Update repayment
PUT /api/repayments/:id
Body: { amount?, method?, paidAt?, reference?, notes? }

// Delete repayment (soft)
DELETE /api/repayments/:id

// Get repayment schedules
GET /api/repayments/schedules?page=1&limit=20&status=OVERDUE&unionId=xxx&dateFrom=2024-01-01

// Get schedule by loan
GET /api/repayments/schedules/loan/:loanId

// Get repayment summary
GET /api/repayments/summary?loanId=xxx&dateFrom=2024-01-01&dateTo=2024-12-31

// Get collections by union
GET /api/repayments/collections-by-union?dateFrom=2024-01-01&dateTo=2024-12-31&unionId=xxx

Summary

Repayment Management provides:

✅ Multiple payment recording methods
✅ 6 payment method types (CASH, TRANSFER, POS, MOBILE, USSD, OTHER)
✅ Automatic payment allocation
✅ Schedule tracking with 4 statuses (PENDING, PARTIAL, PAID, OVERDUE)
✅ Partial and overpayment handling
✅ Advanced filtering and search
✅ Real-time summary cards
✅ Collections reporting by union
✅ Transaction reference tracking
✅ Audit trail preservation

Next Steps

Monitor Dashboard for collection metrics
Generate Reports for portfolio analysis
Review Loans for payment performance

Get Started

Core Features

User Roles

Guides

​Overview

​Repayment Data Model

​Payment Allocation Model

​Recording a New Repayment

​Method 1: From Repayments Page

​Method 2: From Loan Detail Page

​Method 3: From Repayment Schedules

​Payment Methods

CASH

TRANSFER

POS

MOBILE

USSD

OTHER

​Best Practices by Method

​Payment Allocation Logic

​Example Allocation

​API Endpoint

​Viewing Repayment History

​All Repayments View

​Available Filters

Date Range

Loan

Payment Method

Received By

​Repayment List Columns

​For a Specific Loan

​Repayment Schedules Management

​Access Schedules

​Summary Cards

Total Schedules

Pending Payments

Overdue

Total Amount Due

​Advanced Filtering

​Schedule List Features

Sorting

Pagination

Quick Actions

Visual Indicators

​Handling Different Payment Scenarios

​Exact Payment (On Schedule)

​Partial Payment

​Overpayment

​Late Payment

​Multiple Payments in One Day

​Editing Repayments

​Deleting Repayments

​Repayment Summary and Reports

​Summary Endpoint

​Collections by Union

​Best Practices

Recording Payments

Payment Methods

Schedule Monitoring

Data Accuracy

​Daily Workflow

​Troubleshooting

​API Reference

​Summary

Next Steps

Build docs developers (and LLMs) love

Overview

Repayment Data Model

Payment Allocation Model

Recording a New Repayment

Method 1: From Repayments Page

Method 2: From Loan Detail Page

Method 3: From Repayment Schedules

Payment Methods

Best Practices by Method

Payment Allocation Logic

Example Allocation

API Endpoint

Viewing Repayment History

All Repayments View

Available Filters

Repayment List Columns

For a Specific Loan

Repayment Schedules Management

Access Schedules

Summary Cards

Advanced Filtering

Schedule List Features

Handling Different Payment Scenarios

Exact Payment (On Schedule)

Partial Payment

Overpayment

Late Payment

Multiple Payments in One Day

Editing Repayments

Deleting Repayments

Repayment Summary and Reports

Summary Endpoint

Collections by Union

Best Practices

Daily Workflow

Troubleshooting

API Reference

Summary