Loan Accounts API
Overview
The Loan Accounts API provides comprehensive endpoints for managing customer loan accounts, including loan origination, approval workflows, and loan servicing.
Loan Account Lifecycle & State Transitions
The loan lifecycle manages the journey from application through approval, disbursement, repayment, and eventual closure. This diagram illustrates all possible states and transitions.
State Descriptions
| State | Description | Transactions Allowed |
|---|---|---|
| Partial Application | Loan being created/drafted | None |
| Pending Approval | Submitted for credit approval | None |
| Approved | Approved, awaiting disbursement | Disbursement only |
| Rejected | Application rejected | None |
| Active | Loan disbursed, repayments ongoing | Repayments, adjustments |
| In Arrears | Payment overdue | Repayments, penalties |
| Closed | Loan fully repaid | View only |
| Closed Written Off | Loan closed with debt write-off | View only |
| Closed Withdrawn | Customer withdrew before disbursement | View only |
State Change Commands
| Action | Command | From State | To State |
|---|---|---|---|
| Create Loan | CreateLoanCommand | - | Partial Application |
| Request Approval | RequestLoanApprovalCommand | Partial Application | Pending Approval |
| Approve Loan | ApproveLoanCommand | Pending Approval | Approved |
| Reject Loan | RejectLoanCommand | Pending Approval | Rejected |
| Send Back | SetLoanBackToPartialApplicationCommand | Pending Approval | Partial Application |
| Disburse Loan | DisburseLoanCommand | Approved | Active |
| Close Loan | CloseLoanCommand | Active, In Arrears | Closed |
| Write Off | InitiateLoanWriteOffCommand | In Arrears | Closed Written Off |
| Pay Off Loan | InitiateLoanPayOffCommand | Active | Closed |
| Refinance Loan | InitiateLoanRefinanceCommand | Active | Active (new terms) |
| Reschedule Loan | InitiateLoanRescheduleCommand | Active | Active (new schedule) |
| Undo Approval | UndoLoanApprovalCommand | Approved | Pending Approval |
| Mark In Arrears | Automatic (on missed payment) | Active | In Arrears |
| Clear Arrears | Automatic (on catch-up payment) | In Arrears | Active |
Repayment Tracking
When a loan is in Active or In Arrears state, the system tracks:
- Outstanding Principal: Remaining loan amount
- Interest Accrued: Interest charges to date
- Penalties: Late payment penalties (when in arrears)
- Days Past Due: Number of days overdue (when in arrears)
- Next Payment Due Date: Scheduled payment date
- Payment History: All repayment transactions
Coming Soon
Documentation for the Loan Accounts API is currently being developed. This module will include:
- Create Loan - Originate new loan accounts
- Loan Approval - Handle approval workflows
- Update Loan - Modify loan terms
- Get Loan Details - Retrieve loan information
- Loan Restructuring - Modify repayment schedules
- Loan Status - Manage loan lifecycle
Module Status
📝 Status: Documentation in progress
🎯 Target: Q1 2026
📧 Contact: For early access or questions, contact our API team
Related Modules
- Loan Transactions - Loan disbursement and repayments
- Clients - Customer management