Loan Origination Commands Overview

Introduction

The BankLingo Loan Origination system exposes a comprehensive set of commands for managing the entire loan lifecycle — from product setup through disbursement and collection. All commands follow the CQRS pattern and return a consistent response envelope.

Loan Lifecycle — Stages & Commands

Stage 1 — Setup & Configuration

Configure loan products before any application can be created.

Command	Description	Docs
CreateSelfServiceLoanProductCommand	Create a new loan product	View →
GetSelfServiceLoanProductsQuery	List all loan products (YAML-first)	View →
UpdateSelfServiceLoanProductCommand	Update a loan product's parameters	View →
UpdateLoanInterestRateCommand	Adjust interest rate on a loan in progress	View →

---

Stage 2 — Application

Customer submits a loan request.

Command	Description	Docs
CreateSelfServiceLoanRequestCommand	Submit a loan application	View →
CreateQuoteUserDetailCommand	Create profile for anonymous (walk-in) applicant	View →
GetLoanQuoteWithDetailsQuery	Retrieve full loan application with all related data	View →
GetAllMyLoanApplicationsQuery	List all applications for the authenticated user	View →
GetLoanQuotesWithFiltersQuery	Admin view — filter loan applications	View →
BankListQuery	Retrieve available banks for mandate/collection setup	View →

---

Stage 3 — Information Gathering

Collect guarantors, next of kin, employment, and identity information.

Command	Description	Docs
CreateGuarantorInformationCommand	Add a single guarantor	View →
CreateMultipleGuarantorInformationCommand	Add multiple guarantors in one request	View →
UpdateGuarantorInformationCommand	Edit guarantor contact details	View →
GetCustomerLoanGuarantorsQuery	List all guarantors for a loan	View →
CreateNextOfKinInformationCommand	Add next of kin	View →
GetCustomerNextOfKinDetailsQuery	Retrieve next of kin information	View →
GetCustomerEmploymentDetailsQuery	Retrieve employment information	View →
GetCustomerIdentityDetailsQuery	Retrieve identity documents	View →

---

Stage 4 — Assessment

Run credit bureau checks and fetch salary statements.

Command	Description	Docs
FetchStatementCommand	Fetch bank statement for salary verification	View →
CreateStatementCommand	Create a statement record	View →
InitiateCreditCheckCommand	Run credit bureau search	View →
GetCustomerLoanCreditBureauSearchesQuery	Retrieve credit bureau results	View →
GetCustomerLoanSalaryHistoryQuery	Retrieve salary verification history	View →

---

Stage 5 — Approval Workflow

Multi-level review and approval chain.

Command	Description	Docs
InitiateApproveLoanRequestCommand	Submit to approval workflow (Relationship Manager)	View →
SetRecommendedLoanAmountCommand	Record advisory recommended amount	View →
SetFinalLoanAmountCommand	Set the binding approved loan amount	View →
ApproveLoanRequestCommand	Approve at current level	View →
RejectLoanRequestCommand	Reject the application (final)	View →
ReturnToPreviousLevelCommand	Return for correction (revisable)	View →
GetLoanApprovalHistoryQuery	View full approval audit trail (includes comments)	View →
GetLoanQuoteActivityQuery	Comment-free activity timeline for UI display	View →
SendLoanOfferCommand	Send offer letter after full approval	View →
Approval Workflow Guide	Roles, hierarchy, and state machine	—

---

Stage 6 — Deductions

Add or remove custom per-loan deductions before disbursement.

Command	Description	Docs
GetLoanDeductionsQuery	List deductions on a loan	View →
AddLoanDeductionCommand	Add a deduction (insurance, legal fees, etc.)	View →
RemoveLoanDeductionCommand	Remove a deduction by code	View →

---

Stage 7 — Mandate & Settlement Setup

Configure mandate and repayment settlement routing.

Command	Description	Docs
InitiateMandateOnLoanCommand	Set up NIBSS/Remita direct debit mandate	View →
UpdateLoanSettlementDetailsCommand	Set settlement account or virtual account	View →
RetrieveICADAccountsQuery	List available ICAD accounts	View →

---

Stage 8 — Disbursement Setup & Execution

Configure how funds are released, then execute disbursement.

Command	Description	Docs
SetDisbursementDetailsCommand	Set disbursement account, mode, and generate repayment schedule	View →
DisburseLoanRequestCommand	Execute the disbursement	View →
GetLoanDisbursementInformationQuery	View disbursement details and status	View →

---

Stage 9 — Disbursement Batch (Back-office)

Bulk disbursement processing with full review/approval workflow.

Command	Description	Docs
InitiateDisbursementBatchCommand	Create a new disbursement batch	View →
AddDisbursementBatchEntryCommand	Add loan to batch	View →
RemoveDisbursementBatchEntryCommand	Remove loan from batch	View →
ValidateDisbursementBatchCommand	Validate batch entries	View →
ConfirmDisbursementBatchCommand	Confirm batch after validation	View →
ReviewDisbursementBatchCommand	Submit batch for review	View →
ApproveDisbursementBatchCommand	Approve batch for processing	View →
RejectDisbursementReviewCommand	Reject at review stage	View →
RejectDisbursementApprovalCommand	Reject at approval stage	View →
CancelDisbursementBatchCommand	Cancel the batch	View →
DeleteDisbursementBatchCommand	Delete a batch record	View →
RetrieveDisbursementBatchesQuery	List batches with filters	View →
RetrieveDisbursementBatchByIdQuery	Get a specific batch	View →
RetrieveDisbursementBatchEntriesQuery	List entries in a batch	View →
RetrieveDisbursementSourcesQuery	List disbursement source accounts	View →
RetrieveDisbursementsQuery	List individual disbursements	View →

---

Stage 10 — Collection & Repayment

Configure repayment account and manage the repayment schedule.

Command	Description	Docs
SetCollectionDetailsCommand	Configure repayment account and auto-debit	View →
GetLoanCollectionInformationQuery	View collection setup	View →
GetRepaymentScheduleQuery	View repayment schedule with installments	View →
WaiveRepaymentScheduleInstallmentCommand	Waive a specific installment	View →

---

Stage 11 — KYC Verification (Back-office, parallel)

Approve or reject identity and address documentation.

Command	Description	Docs
ApproveIdentityDocumentCommand	Approve identity document	View →
RejectIdentityDocumentCommand	Reject identity document	View →
ApproveCustomerAddressInformationCommand	Approve address	View →
RejectCustomerAddressInformationCommand	Reject address	View →
InitiateGuarantorVerificationCommand	Start guarantor verification	View →
ApproveGuarantorVerificationCommand	Approve guarantor	View →
DeclineGuarantorVerificationCommand	Decline guarantor	View →

---

Command Architecture

Command Pattern

All commands follow the CQRS (Command Query Responsibility Segregation) pattern:

{
  "cmd": "CommandName",
  "data": "{\"parameter\":\"value\"}"
}

Response Structure

All commands return a consistent response structure:

{
  "ok": true,
  "message": "Operation completed successfully",
  "statusCode": "00",
  "outData": {
    // Command-specific data
  }
}

Performance Monitoring

Many commands include performance timing data:

{
  "ok": true,
  "outData": {
    "...": "data",
    "PerformanceTimings": {
      "0_TotalExecutionTime": 245,
      "1_ParseParameters": 2,
      "2_FetchData": 180,
      "3_ProcessData": 50
    },
    "PerformanceSummary": {
      "TotalExecutionTimeMs": 245,
      "SlowestOperation": "2_FetchData"
    }
  }
}

Command Categories

1. Customer Management Commands

Commands for managing customer information and KYC:

Command	Purpose	Documented
GetCustomerBasicDetailsQuery	Get complete customer profile	View →
GetCustomerKycInformationQuery	Get KYC verification status	View →
GetCustomerAddressDetailsQuery	Get address information	View →
GetCustomerBranchAssociationsQuery	Get customer's branch access	⏳ Pending
GetCustomerRoleAssociationsQuery	Get customer's role assignments	⏳ Pending
GetCustomerIdentityDetailsQuery	Get identity documents	⏳ Pending
GetCustomerNextOfKinDetailsQuery	Get next of kin details	⏳ Pending
GetCustomerEmploymentDetailsQuery	Get employment information	⏳ Pending

2. KYC Verification Commands

Commands for approving/rejecting KYC documents:

Command	Purpose
ApproveIdentityDocumentCommand	Approve identity document
RejectIdentityDocumentCommand	Reject identity document
ApproveCustomerAddressInformationCommand	Approve address verification
RejectCustomerAddressInformationCommand	Reject address verification

3. Loan Application Commands

Commands for managing loan applications:

Command	Purpose	Documented
GetCustomerLoanDetailsQuery	Get loan application details	View →
GetCustomerLoanSalaryHistoryQuery	Get salary verification history	View →
GetCustomerLoanCreditBureauSearchesQuery	Get credit bureau searches	View →
GetCustomerLoanGuarantorsQuery	Get loan guarantors	View →

4. Guarantor Management Commands

Commands for managing loan guarantors:

Command	Purpose
InitiateGuarantorVerificationCommand	Start guarantor verification
ApproveGuarantorVerificationCommand	Approve guarantor
DeclineGuarantorVerificationCommand	Decline guarantor

Authorization

User Classifications

Commands check user classification for authorization:

• BACKOFFICE_ADMINISTRATORS: Full access to all customer data
• Organization Users: Limited to their organization's data

Role-Based Access

Some commands require specific roles:

Role	Access Level
RELATIONSHIP_MANAGER	Initiate loan applications
BRANCH_MANAGER	Branch-level approval
AREA_MANAGER	Area-level approval
DIVISION_MANAGER	Division-level approval
CREDIT_ADMIN	Credit review and approval
HEAD_CREDIT_ADMIN	Senior credit review
CONTROL_OFFICER	Compliance and final review
FINANCE	Loan disbursement
MD	Managing Director approval
GMD	Group Managing Director approval

Common Parameters

userId

Type: long (integer)
Required: Yes (in most commands)
Description: The ID of the customer/user

Example:

{
  "cmd": "GetCustomerBasicDetailsQuery",
  "data": "{\"userId\":\"129\"}"
}

loanQuoteId

Type: long (integer)
Required: Yes (in loan-specific commands)
Description: The ID of the loan application

Example:

{
  "cmd": "GetCustomerLoanDetailsQuery",
  "data": "{\"userId\":\"129\",\"loanQuoteId\":\"110\"}"
}

Error Handling

Standard Error Codes

Code	Meaning	Description
00	Success	Operation completed successfully
04	Not Found	Resource not found or unauthorized
99	System Error	An unexpected error occurred

Error Response Example

{
  "ok": false,
  "statusCode": "04",
  "message": "User not found or unauthorized",
  "outData": null
}

Performance Optimization

Use Dedicated Commands

Instead of fetching all data with GetCustomerBasicDetailsQuery, use dedicated commands for specific data:

❌ Slow - Fetches everything (245ms):

{
  "cmd": "GetCustomerBasicDetailsQuery",
  "data": "{\"userId\":\"129\"}"
}

✅ Fast - Fetches only KYC (85ms, 65% faster):

{
  "cmd": "GetCustomerKycInformationQuery",
  "data": "{\"userId\":\"129\"}"
}

Parallel Requests

When fetching independent data, make parallel requests:

const [kyc, branches, roles] = await Promise.all([
  api.query({ cmd: "GetCustomerKycInformationQuery", data: "{\"userId\":\"129\"}" }),
  api.query({ cmd: "GetCustomerBranchAssociationsQuery", data: "{\"userId\":\"129\"}" }),
  api.query({ cmd: "GetCustomerRoleAssociationsQuery", data: "{\"userId\":\"129\"}" })
]);

// Total time: ~85ms (slowest query)
// vs GetCustomerBasicDetailsQuery: ~245ms

Next Steps

Explore specific command categories:

• Customer Basic Details →
• Customer KYC Information →
• Branch Associations →
• Role Associations →
• Loan Details →
• Loan Salary History →
• Credit Bureau Searches →
• Loan Guarantors →