Skip to main content

Loan Accounts

Overview​

The Loan Accounts module enables you to originate, approve, and manage customer loans throughout their lifecycle.

Loan Account States​

Understanding loan account states is critical for managing the loan lifecycle. Each loan progresses through various states from application to closure.

Loan Lifecycle Diagram​

State Reference Table​

ValueStateDescriptionTypical Next States
1Partial_ApplicationLoan application is incomplete and being drafted by staff or customerPending_Approval, Closed_Withdrawn
2Pending_ApprovalLoan is complete and awaiting approval from authorized personnelApproved, Rejected
3ApprovedLoan has been approved but not yet disbursed to customerActive, Closed_Withdrawn
4RejectedLoan application was rejected and cannot proceed(Final state)
5ActiveLoan has been disbursed and customer is making repaymentsIn_Arears, Closed
6In_ArearsLoan has overdue payments and requires collection actionActive, Closed, Closed_Written_Off
7ClosedLoan has been fully repaid and account is closed successfully(Final state)
8Closed_Written_OffLoan was closed and written off as irrecoverable bad debt(Final state)
9Closed_WithdrawnLoan application or approved loan was withdrawn before/after approval(Final state)

State Lifecycle Flow​

┌─────────────────────┐
│ Partial_Application │ ◄── Initial State (Draft)
└──────────┬──────────┘
           │
           ▼
   ┌───────────────────┐
   │ Pending_Approval  │ ◄── Submitted for Review
   └────┬──────────────┘
        │
        ├─────► Rejected (Final)
        │
        ▼
   ┌──────────┐
   │ Approved │ ◄── Ready for Disbursement
   └────┬─────┘
        │
        ▼
   ┌────────┐
   │ Active │ ◄── Disbursed, Repayments Ongoing
   └─┬──────┘
     │
     ├─────► In_Arears ◄── Overdue Payments
     │           │
     │           └─────► Closed_Written_Off (Final)
     │
     └─────► Closed (Final) ◄── Fully Repaid
     
     
 Any State ──────► Closed_Withdrawn (Final)

State Business Rules​

Partial_Application (1)​

  • Editable: Yes - full editing allowed
  • Transactions: None allowed
  • Actions Available: Edit, Submit for Approval, Withdraw
  • User Access: Loan Officers, Relationship Managers

Pending_Approval (2)​

  • Editable: Limited - requires special permission
  • Transactions: None allowed
  • Actions Available: Approve, Reject, Return to Draft
  • User Access: Approvers, Managers, Senior Staff

Approved (3)​

  • Editable: No
  • Transactions: Disbursement only
  • Actions Available: Disburse, Undo Approval, Withdraw
  • User Access: Disbursement Officers, Treasury

Active (5)​

  • Editable: No (metadata only)
  • Transactions: Repayments, Fee Collection, Adjustments
  • Actions Available: Accept Payments, Apply Charges, Restructure
  • User Access: Tellers, Loan Officers, Collections

In_Arears (6)​

  • Editable: No
  • Transactions: Repayments, Penalty Application
  • Actions Available: Accept Payments, Penalty Charges, Collection Actions, Write-Off
  • User Access: Collections Team, Managers

Closed States (7, 8, 9)​

  • Editable: No
  • Transactions: None (read-only)
  • Actions Available: View History, Generate Reports
  • User Access: All staff (read-only)

API Integration​

Filtering Loans by State​

GET /api/loans?loanState=5
# Returns all Active loans

GET /api/loans?loanState=2
# Returns all loans Pending_Approval

Response Format​

{
  "id": 12345,
  "accountNumber": "LN-2024-00123",
  "loanState": 5,
  "loanStateDescription": "Active",
  "principalBalance": 500000.00,
  "interestBalance": 25000.00,
  "daysInArears": 0
}

Key Features​

  • Loan Origination - Create new loan applications with full validation
  • Loan Approval Workflow - Multi-level approval with role-based permissions
  • Loan Products - Support for multiple loan types (personal, SME, payroll, etc.)
  • Collateral Management - Track and manage loan security
  • Guarantor Management - Add and verify loan guarantors
  • Loan Restructuring - Modify repayment terms for existing loans
  • Automated Interest - Daily interest accrual and capitalization
  • Penalty Management - Automatic penalty application for late payments
  • Loan Reports - Comprehensive loan portfolio analytics