Skip to main content

​
Overview

By the end of this guide, you will understand the complete loan lifecycle from creation through approval to disbursement. You’ll learn how to create draft loans, submit them for approval, handle different loan statuses, and activate loans for repayment tracking.

​
Understanding Loan Statuses

A loan moves through several stages during its lifecycle:
StatusDescriptionWho Can SetNext Actions
DRAFTJust created, not yet submittedCredit OfficerEdit or Submit for Approval
PENDING_APPROVALAwaiting supervisor reviewSystem (on submit)Approve or Reject
APPROVEDApproved by supervisorSupervisor/AdminDisburse
ACTIVEDisbursed and being repaidSystem (on disburse)Record repayments
COMPLETEDAll repayments madeSystem (automatic)None - archived
DEFAULTEDBorrower failed to repayAdminCollection or write-off
WRITTEN_OFFRemoved from active portfolioAdminNone - archived
CANCELEDApplication was canceledAdmin/SupervisorNone
Refer to backend/prisma/schema.prisma:25-34 for the complete LoanStatus enum.
Status transitions are controlled by business logic. You cannot skip stages - for example, a DRAFT loan must go through PENDING_APPROVAL and APPROVED before being ACTIVE.

​
Creating a New Loan Application

1

Navigate to Loans Section

From the sidebar:
  1. Click “Business Management”
  2. Click “Loans”
  3. Click ”+ Add New Loan” button in the top right
2

Select the Borrower

Choose who will receive the loan:
  1. Select Union: Choose from the dropdown of available unions
    • Credit Officers only see unions assigned to them
    • Admins and Supervisors see all unions
  2. Select Union Member: Choose the borrower from the union
    • Only verified members appear in this list (isVerified = true)
    • If a member is missing, check their verification status
You cannot create a loan for a member who is not verified. Verify members first in the Union Members section.
3

Enter Loan Details

Fill in all required loan information:

​
Required Fields

FieldDescriptionValidationFormat
Loan TypeType of loan productRequiredSelect from configured loan types
Principal AmountAmount to lendRequiredDecimal, up to 14 digits
Interest RateAnnual interest rateAuto-filled from loan typePercentage
Term CountLoan durationRequiredInteger (1-999)
Term UnitDuration unitRequiredDAY, WEEK, or MONTH
Repayment FrequencyHow often payments are dueRequiredDaily, Weekly, Monthly
Start DateWhen loan beginsRequiredDate (format: YYYY-MM-DD)
PurposeWhy the member needs the loanRequiredText

​
Optional Fields

  • Notes: Additional information about the loan
  • Processing Fee: May be auto-calculated based on loan type
  • End Date: Usually calculated automatically
The interest rate is often pre-filled based on the selected Loan Type. Admins configure these defaults in System Configuration → Loan Types.
4

Review Repayment Schedule

After entering loan details, the system automatically:
  • Calculates the total amount to be repaid
  • Generates the full repayment schedule
  • Shows all due dates and amounts
Review this carefully:
  • Total Due: Principal + Interest + Fees
  • Number of Installments: Based on term and frequency
  • Due Dates: When each payment is expected
  • Principal vs Interest: Breakdown per payment
The repayment schedule is generated using the RepaymentScheduleItem model (schema.prisma:282-308). Each installment tracks principal, interest, and fees separately.
5

Save as Draft or Submit

You have two options:Option 1: Save as Draft
  • Click “Save as Draft”
  • Loan status is set to DRAFT
  • You can edit it later before submitting
  • Use this when you need to verify information
Option 2: Submit for Approval
  • Click “Submit for Approval”
  • Loan status changes to PENDING_APPROVAL
  • It appears in your supervisor’s approval queue
  • You cannot edit it after submission (contact admin if needed)
Once submitted for approval, Credit Officers cannot edit the loan. If changes are needed, a Supervisor or Admin must reject it so you can modify and resubmit.

​
Required Field Validation

The system validates loan data before saving:

​
Amount Validations

  • Principal amount must be positive
  • Must be within the min/max limits of the loan type
  • Format: Decimal with up to 14 digits, 2 decimal places

​
Date Validations

  • Start date cannot be in the past
  • End date must be after start date
  • Due dates are calculated based on frequency

​
Borrower Validations

  • Union member must exist in the system
  • Member must be verified (isVerified = true)
  • Member must belong to the selected union
Refer to loan.controller.ts:6-24 for the creation logic.

​
Editing Draft Loans

You can modify loans in DRAFT status before submission.
1

Find the Draft Loan

  1. Go to Business Management → Loans
  2. Filter by status: DRAFT
  3. Locate your loan in the list
2

Open Edit Mode

Click the Edit icon (pencil) next to the loan.
3

Modify Details

You can change:
  • Principal amount
  • Interest rate
  • Term and frequency
  • Start date
  • Purpose and notes
You cannot change the borrower (union member) after creation. To change the borrower, you must delete and recreate the loan.
4

Save Changes

  • Click “Save Changes” to keep as draft
  • Or click “Submit for Approval” to send for review

​
Approving or Rejecting Loans (Supervisors/Admins)

Supervisors and Admins can review and approve loan applications.
1

View Pending Approvals

  1. Navigate to Business Management → Loans
  2. Apply filter: Status = PENDING_APPROVAL
  3. You’ll see all loans awaiting your review
The dashboard also shows a count of pending approvals on the summary cards for quick access.
2

Review Loan Details

Click on a loan to view:
  • Borrower information and credit history
  • Loan amount and terms
  • Repayment schedule
  • Purpose of the loan
  • Created by which Credit Officer
Verify:
  • Amount is reasonable for the member
  • Terms align with loan type policies
  • Member has capacity to repay
3

Approve the Loan

If the loan looks good:
  1. Click the “Approve” button
  2. Add approval notes (optional but recommended)
  3. Click “Confirm Approval”
Result:
  • Loan status changes to APPROVED
  • The loan is ready for disbursement
  • The Credit Officer is notified
4

OR Reject the Loan

If the loan needs revision:
  1. Click the “Reject” button
  2. Enter a reason for rejection (required)
  3. Click “Confirm Rejection”
Result:
  • Loan status changes to REJECTED
  • The Credit Officer can see your reason
  • They may need to create a new application
Always provide a clear rejection reason so the Credit Officer understands what needs to change.
Refer to loan.controller.ts:100-130 for the status update logic.

​
Disbursing a Loan (Giving the Money)

After approval, loans must be disbursed to activate them.
1

Filter for Approved Loans

  1. Go to Business Management → Loans
  2. Filter: Status = APPROVED
  3. Find the loan to disburse
2

Open Disburse Dialog

  1. Click on the loan to open details
  2. Click the “Disburse” button
  3. A disbursement form appears
3

Enter Disbursement Details

Provide the following information:
FieldDescriptionRequired
Disbursement DateWhen money was actually givenOptional (defaults to today)
Payment MethodHow money was disbursedCASH, TRANSFER, MOBILE, etc.
Reference NumberTransaction ID or check numberOptional
NotesAdditional disbursement notesOptional
If you don’t specify a disbursement date, the system uses the current date/time (loan.controller.ts:135-137).
4

Confirm Disbursement

Click “Confirm Disbursement” to complete.Result:
  • Loan status changes to ACTIVE
  • The disbursedAt timestamp is recorded
  • Repayment schedule becomes active
  • The loan appears in the active loans list
Important: Disbursement cannot be undone. Ensure:
  • Money has actually been given to the borrower
  • All details are correct before confirming
  • You have proper documentation of the disbursement

​
Viewing Loan Details

Access comprehensive loan information at any time.
1

Open the Loan

Click on any loan in the loans list to view full details.
2

Review Available Information

The loan detail page shows:Loan Summary
  • Loan number (unique identifier)
  • Current status
  • Principal, interest, and total amounts
  • Currency (default: NGN)
Borrower Information
  • Union member name and details
  • Union affiliation
  • Contact information
  • Verification status
Repayment Schedule
  • All scheduled payments
  • Due dates for each installment
  • Principal and interest breakdown
  • Payment status (PENDING, PAID, PARTIAL, OVERDUE)
Payment History
  • All repayments made so far
  • Payment dates and amounts
  • Payment methods used
  • Running balance
Documents
  • Attached loan documents
  • Member documents
  • Verification documents
Status History
  • Timeline of status changes
  • Who made each change
  • Timestamps for each transition
Refer to loan.controller.ts:57-76 for the API that retrieves this information.

​
Understanding the Repayment Schedule

The schedule shows all expected payments:
ColumnDescriptionSource Field
SequencePayment number (1, 2, 3…)sequence
Due DateWhen payment is expecteddueDate
Principal DueAmount toward loan principalprincipalDue
Interest DueInterest portioninterestDue
Fee DueAny applicable feesfeeDue
Total DueTotal amount for this paymenttotalDue
Paid AmountHow much has been paidpaidAmount
StatusPENDING, PAID, PARTIAL, OVERDUEstatus (ScheduleStatus enum)
Schedule statuses (schema.prisma:42-47):
  • PENDING: Not yet paid, not overdue
  • PARTIAL: Partially paid but not complete
  • PAID: Fully paid
  • OVERDUE: Past due date and not paid
Use the schedule to track upcoming payments and identify overdue accounts. The system automatically updates schedule item statuses as repayments are recorded.

​
Handling Different Loan Statuses

​
Active Loans

​
Completed Loans

  • Status: COMPLETED
  • Automatic when all repayments are made
  • No further action needed
  • Loan is archived but remains in records

​
Defaulted Loans

  • Status: DEFAULTED
  • Requires admin intervention
  • Options: Collection actions or write-off
  • Can be set manually by Admin users

​
Canceled Loans

  • Status: CANCELED
  • For applications that won’t proceed
  • Can only be set by Admin/Supervisor
  • Use instead of deleting
Never delete loans with repayment history. Use status changes instead:
  • Set to CANCELED for abandoned applications
  • Set to WRITTEN_OFF for uncollectible debts
  • Set to DEFAULTED for collection cases

​
Assigning Loans to Officers

Admins can reassign loans between Credit Officers.
1

Access Loan Assignment

  1. Open the loan details
  2. Click “Assign Loan” or “Reassign”
2

Select New Officer

  1. Choose the new Credit Officer from the dropdown
  2. Enter a reason for reassignment (optional)
  3. Click “Confirm Assignment”
3

Verify Assignment

The loan now appears in the new officer’s portfolio.
  • The assignedOfficerId field is updated
  • Original creator (createdByUserId) remains unchanged
Refer to loan.controller.ts:156-178 for the assignment logic. Find loans quickly using filters:
FilterOptionsUse Case
StatusAny LoanStatus valueFind all pending approvals
UnionUnion dropdownSee loans for specific union
Union MemberMember dropdownView a member’s loan history
SearchText inputSearch by borrower name or loan number
Date RangeStart/End datesLoans created in a period
Amount RangeMin/MaxFind loans above/below certain amounts
Combine filters for precise results. For example: Status=ACTIVE + Union=specific union + Date Range=this month.

​
API Reference

For developers integrating with the loan system:

​
Best Practices

Workflow Tips:
  • Save as draft when you need to verify member information
  • Double-check principal amounts before submitting
  • Use clear, descriptive purposes for loan applications
  • Review the repayment schedule before submission
  • Add notes for unusual or special cases
Common Mistakes to Avoid:
  • Submitting loans for unverified members
  • Forgetting to disburse after approval (loan stays APPROVED forever)
  • Disbursing before final verification of borrower identity
  • Deleting loans instead of using CANCELED status
  • Approving without reviewing member’s existing loan load

Build docs developers (and LLMs) love

Get started for freeTalk to us