Skip to main content

​
Overview

By the end of this guide, you will understand how to record loan repayments, choose appropriate payment methods, handle partial payments and overpayments, understand how the system allocates payments, track schedule status, and manage overdue accounts.

​
Understanding Repayment Flow

When a borrower makes a payment:
  1. You record the repayment with amount, date, and method
  2. System automatically allocates payment to schedule items
  3. Payment is applied to interest first, then principal
  4. Schedule items are updated (PENDING → PAID or PARTIAL)
  5. Loan balance is recalculated
  6. If overdue items exist, they’re paid first
The allocation logic is automatic. You simply record the payment amount, and the system handles the distribution across schedule items according to backend/src/controllers/repayment.controller.ts.

​
Recording a New Repayment

​
Method 1: From the Repayments Page

1

Navigate to Repayments

From the sidebar:
  1. Click “Business Management”
  2. Click “Repayments”
  3. Click ”+ Add Repayment” button
2

Select the Loan

  1. Choose the loan from the dropdown
  2. Search by borrower name or loan number
  3. Only ACTIVE loans appear in the list
Start typing the borrower’s name to quickly filter the loan list.
3

Enter Repayment Details

Fill in all required information:
FieldDescriptionRequiredFormat
AmountPayment amount received✅ YesDecimal (14,2)
Payment DateWhen payment was made✅ YesDate (YYYY-MM-DD)
Payment MethodHow payment was received✅ YesSee payment methods below
Reference NumberTransaction referenceOptionalText
NotesAdditional informationOptionalText

​
Payment Methods

The system supports these payment methods (RepaymentMethod enum, schema.prisma:49-56):
MethodDescriptionUse Case
CASHCash paymentWalk-in payments, field collections
TRANSFERBank transferOnline transfers, wire transfers
POSPoint of Sale terminalCard payments
MOBILEMobile moneyMobile wallet payments
USSDUSSD code paymentMobile USSD transactions
OTHEROther payment typesAny other payment method
Always select the correct payment method for accurate reporting and reconciliation.
4

Verify and Submit

  1. Double-check the amount and date
  2. Ensure payment method is correct
  3. Click “Record Repayment”
Result:
  • Repayment is saved to the database
  • Payment is automatically allocated to schedule items
  • Loan balance is updated
  • Schedule statuses change accordingly

​
Method 2: From the Loan Detail Page

1

Open the Specific Loan

  1. Navigate to Business Management → Loans
  2. Find the loan (search by borrower name or loan number)
  3. Click on the loan to open details
2

Access Add Repayment

In the loan detail page:
  1. Scroll to the Repayment section
  2. Click “Add Repayment” or “Record Payment” button
3

Fill in Payment Details

The loan is already pre-selected, so just enter:
  • Payment amount
  • Payment date
  • Payment method
  • Reference number (if applicable)
  • Notes
This method is faster when you’re already viewing a specific loan, as the loan selection is automatic.
4

Submit the Repayment

Click “Record Repayment” to save.
Refer to repayment.controller.ts:6-26 for the repayment creation logic.

​
How Payments Are Allocated

The system follows a specific allocation strategy:

​
Allocation Priority

  1. Overdue items first: Payments go to overdue schedule items before current ones
  2. Interest before principal: Within each schedule item, interest is paid first
  3. Oldest to newest: Overdue items are paid in chronological order
  4. Sequential application: Payment flows through schedule items in sequence

​
Example

Imagine a loan with these schedule items:
SequenceDue DateTotal DueStatus
12026-01-15₦5,000OVERDUE (unpaid)
22026-02-15₦5,000PENDING
32026-03-15₦5,000PENDING
Borrower pays ₦7,500 on March 10, 2026:
  1. ₦5,000 → Schedule item #1 (overdue)
    • Status changes to PAID
  2. ₦2,500 → Schedule item #2 (current)
    • Status changes to PARTIAL
  3. Schedule item #3 remains PENDING
The system handles all allocation automatically via RepaymentAllocation records (schema.prisma:336-350). You can view the allocation breakdown in the repayment details.

​
Choosing the Right Payment Method

Selecting the correct payment method is important for:
  • Accurate financial reporting
  • Bank reconciliation
  • Payment method analytics
  • Audit trails

​
Guidelines

MethodWhen to UseReference Number
CASHPhysical cash receivedReceipt number
TRANSFERBank-to-bank transferTransfer confirmation code
POSCard payment via terminalTransaction ID from POS
MOBILEMobile money (M-Pesa, etc.)Mobile transaction ID
USSDUSSD banking paymentUSSD transaction reference
OTHERChecks, other methodsCheck number or other ref
Always record the payment method reference number for non-cash payments. This is crucial for reconciliation and dispute resolution.

​
Handling Partial Payments

Borrowers sometimes pay less than the full scheduled amount.
1

Record the Actual Amount

Simply record the actual amount received, even if it’s less than expected.Example:
  • Expected payment: ₦5,000
  • Actual payment: ₦3,000
  • Record: ₦3,000
2

System Updates Schedule

After recording:
  • Schedule item status changes to PARTIAL
  • The paidAmount field increases by ₦3,000
  • Remaining balance: ₦2,000
  • Schedule item stays PARTIAL until fully paid
3

Track the Shortfall

The shortfall is tracked automatically:
  • View the schedule to see PARTIAL status
  • The remaining amount is visible: totalDue - paidAmount
  • No additional configuration needed
According to schema.prisma:295-296, each schedule item tracks both totalDue and paidAmount, making it easy to see partial payments.
4

Collect Remaining Amount

When the borrower pays the remaining ₦2,000:
  1. Record another repayment for ₦2,000
  2. System allocates it to the PARTIAL schedule item
  3. Once paidAmount reaches totalDue, status changes to PAID
Best Practice: Add notes to partial payment records explaining the reason (e.g., “Borrower had emergency expenses” or “Agreed partial payment plan”).

​
Handling Overpayments

Borrowers sometimes pay more than the scheduled amount.

​
What Happens

  1. System allocates payment to current schedule item
  2. Excess automatically flows to next schedule items
  3. Future payments may be prepaid
  4. Loan is paid off faster

​
Example

Schedule:
  • Item 1: ₦5,000 due today
  • Item 2: ₦5,000 due next month
  • Item 3: ₦5,000 due in 2 months
Borrower pays ₦12,000:
  1. ₦5,000 → Item 1 (PAID)
  2. ₦5,000 → Item 2 (PAID)
  3. ₦2,000 → Item 3 (PARTIAL)
Result: Two installments are paid in advance.
Overpayments reduce the principal balance faster, which can reduce total interest paid over the life of the loan.

​
Tracking Overpayments

View the repayment schedule to see:
  • Which items are marked PAID ahead of due date
  • How much has been prepaid
  • Updated loan completion date (if applicable)

​
Understanding Schedule Status

Each schedule item has one of four statuses (ScheduleStatus enum, schema.prisma:42-47):

​
Status Definitions

StatusMeaningWhen It Occurs
PENDINGNot yet paid, not overdueDue date is in the future, no payment made
PARTIALPartially paidSome payment recorded but less than totalDue
PAIDFully paidpaidAmount >= totalDue
OVERDUEPast due and unpaiddueDate has passed, not fully paid

​
Status Transitions

Schedule items move through statuses as payments are made: 
PENDING → PARTIAL → PAID
   ↓
OVERDUE → PARTIAL → PAID
OVERDUE Status: Schedule items automatically become OVERDUE when their due date passes and they’re not fully paid. The system updates this status automatically.

​
Monitoring Repayment Schedules

The Repayment Schedules page provides a powerful overview of all payments.
1

Access the Schedules Dashboard

From the sidebar:
  1. Go to “Business Management”
  2. Click “Repayment Schedules”
You’ll see:
  • Summary cards with aggregate statistics
  • Detailed list of all schedule items
  • Advanced filtering options
2

Review Summary Cards

The top of the page shows real-time statistics:
CardShowsUse Case
Total ScheduleTotal number of schedule itemsOverall workload
Pending PaymentsItems with status PENDINGUpcoming collections
OverdueItems with status OVERDUEPriority collections
Total Amount DueSum of all pending + overdueCash flow projection
These cards update based on your active filters, giving you filtered totals instantly.
3

Apply Filters

Filter the schedule list by:
FilterOptionsUse Case
SearchBorrower nameFind specific member
UnionUnion dropdownSee one union’s schedules
Union MemberMember dropdownAll schedules for one member
Credit OfficerOfficer dropdownOne officer’s portfolio
StatusPENDING, PAID, PARTIAL, OVERDUEFocus on specific status
Date RangeToday Only, Single Date, Date RangeSchedules in time period
Amount RangeMin/MaxFind large or small payments
Refer to repayment.controller.ts:154-165 for the complete list of filter parameters supported by the API.
4

Use Quick Actions

From the schedule list, you can:
  • Click “Pay Due” to record a standard payment (full amount)
  • Click “Custom” for partial or overpayments
  • Sort by clicking column headers
  • Adjust rows per page (10, 20, 50, 100)

​
Handling Overdue Payments

Managing overdue accounts is critical for portfolio health.
1

Identify Overdue Accounts

  1. Go to Repayment Schedules
  2. Filter by Status = OVERDUE
  3. Sort by due date (oldest first)
The Overdue summary card shows the total count.
2

Review Overdue Details

For each overdue item, check:
  • How many days overdue (calculate from dueDate)
  • Amount still owed
  • Borrower’s contact information
  • Payment history (any partial payments?)
3

Contact the Borrower

Use the contact information from the union member profile:
  • Phone number
  • Address
  • Alternative contact
Document all contact attempts in the loan notes for audit purposes.
4

Record Late Payment

When the borrower pays:
  1. Record the repayment normally (see Recording a New Repayment)
  2. Payment automatically goes to overdue items first
  3. Schedule item changes from OVERDUE to PAID or PARTIAL
  4. Overdue count decreases
The system prioritizes overdue items automatically. You don’t need to manually specify which schedule item to pay.
5

Apply Penalties (If Configured)

If your organization charges late fees:
  • Check the loan’s penaltyFeePerDayAmount (schema.prisma:250)
  • Calculate days overdue × penalty per day
  • Add penalty as a fee or adjust the schedule item
Penalty fee handling may require admin/supervisor approval depending on your organization’s policies.

​
Viewing Repayment History

​
For All Loans

1

Access Repayments List

Go to Business Management → Repayments
2

Apply Filters

Filter by:
  • Date range: Payments in a specific period
  • Loan: Specific loan’s payments
  • Payment method: All CASH payments, etc.
  • Received by: Which staff member recorded it
3

View Details

Click on any repayment to see:
  • Full payment details
  • Allocation breakdown (which schedule items were paid)
  • Original loan information
  • Recorded by whom and when
Refer to repayment.controller.ts:28-58 for the API that retrieves repayment lists.

​
For a Specific Loan

1

Open the Loan

Navigate to the loan details page.
2

Scroll to Payment History

The loan detail page includes:
  • Repayment Schedule section: All scheduled payments
  • Payment History section: All repayments made
3

Analyze Payment Pattern

Review:
  • Total payments made so far
  • Payment dates and amounts
  • Payment methods used
  • Outstanding balance
  • On-time payment percentage

​
Generating Repayment Reports

Use the repayment summary and collections reports.

​
Repayment Summary

Get aggregate statistics:
  • Total repayments in a date range
  • Total amount collected
  • Breakdown by payment method
  • Collection rate
API: GET /api/repayments/summary (repayment.controller.ts:225-252)

​
Collections by Union

See how much each union has repaid:
  • Filter by date range
  • Filter by credit officer
  • Compare union performance
API: GET /api/repayments/collections-by-union (repayment.controller.ts:254-282)
These reports feed into the supervisor dashboard. See Reporting & Analytics Guide for more details.

​
Editing or Deleting Repayments

​
Editing a Repayment

Use with caution. Editing repayments affects schedule allocations and loan balances.
1

Locate the Repayment

Find the repayment in the repayments list.
2

Open Edit Mode

Click the Edit icon next to the repayment.
3

Modify Details

You can change:
  • Amount (will trigger re-allocation)
  • Payment date
  • Payment method
  • Reference number
  • Notes
Changing the amount will recalculate all allocations and update schedule items accordingly.
4

Save Changes

Click “Save Changes” to apply modifications.

​
Deleting a Repayment

Requires Admin privileges. Deleting repayments should only be done to correct errors.
  1. Only Admins can delete repayments (repayment.controller.ts:115-141)
  2. Deletion removes the repayment record
  3. Allocations are reversed
  4. Schedule items revert to previous status
  5. Loan balance is adjusted
Instead of deleting, consider editing the repayment to correct the error. Deletion should be a last resort.

​
API Reference

For developers integrating with the repayment system:

​
Best Practices

Recording Tips:
  • Record payments on the actual payment date, not the due date
  • Always include reference numbers for non-cash payments
  • Add notes for unusual situations or partial payments
  • Double-check amounts before submitting
  • Record payments daily to keep data current
Common Mistakes to Avoid:
  • Recording future-dated payments (use actual payment date)
  • Forgetting to select the correct payment method
  • Not documenting partial payment arrangements
  • Deleting repayments instead of editing to fix errors
  • Recording payments to the wrong loan (double-check borrower name)
Payment Method Accuracy: Accurate payment method recording is essential for:
  • Bank reconciliation
  • Cash management
  • Fraud prevention
  • Audit compliance

Build docs developers (and LLMs) love

Get started for freeTalk to us