Loan Transactions Overview

Complete guide to loan transactions in BankLingo V2 Core Banking Platform.

Overview

Loan transactions handle the complete loan lifecycle from disbursement to closure. BankLingo V2 implements a robust loan transaction processing engine with:

Delta-based impact tracking: Every field change tracked for accurate reversal
Multi-phase processing: PENDING → APPROVED → COMPLETED → ACTIVE
Payment allocation: Configurable waterfall (penalties → fees → interest → principal)
Schedule management: Multi-schedule tracking, repayment impact, balance updates
Complete audit trail: Every entity impact recorded
Universal reversal: One framework works for all transaction types

Loan Product Types

All loan transactions are performed on product-based loan accounts. BankLingo V2 supports the following loan product types:

Enum: LoanProductTypeEnum

Type	Description	Typical Use
FixedTermLoan	Standard loan with fixed repayment schedule	Personal loans, mortgages
DynamicTermLoan	Loan with flexible terms and adjustments	Adaptive lending
InterestFreeLoan	Loan without interest charges	Islamic banking, employee loans
TranchedLoan	Loan disbursed in multiple tranches	Construction, project financing
RevolvingCredit	Reusable credit line (like credit card)	Working capital, overdrafts

Note: Each product type has its own configuration in the LoanProduct entity, including limits, fees, interest rates, repayment rules, and accounting configuration.

Transaction Types

Core Loan Transactions

Transaction	Purpose	V2 Command	Key Features
Disbursement	Release loan funds	`InitiateLoanDisbursementCommand`	Fee calculation, account/settlement, schedule activation
Repayment	Pay loan installment	`InitiateLoanRepaymentCommand`	Payment allocation, multi-schedule tracking, balance updates
Pay-Off	Full loan settlement	`InitiateLoanPayOffCommand`	Total outstanding, early settlement discount, account closure
Write-Off	Write off bad debt	`InitiateLoanWriteOffCommand`	Balance zeroing, GL write-off entries, schedule updates
Reschedule	Modify loan terms	`InitiateLoanRescheduleCommand`	New schedule creation, term changes, balance preservation
Refinance	New loan pays off old	`InitiateLoanRefinanceCommand`	Two-loan tracking, top-up handling, closure/disbursement
Teller Repayment	Loan payment via teller	`InitiateLoanRepaymentWithDepositCommand`	Payment allocation, till impact, GL income

Transaction States

All loan transactions follow a state machine:

States Explained:

PENDING: Created, may require approval
APPROVED: Approved, ready to execute
REJECTED: Denied before execution
COMPLETED: Executed, balances and schedules updated
ACTIVE: Finalized, permanent
REVERSED: Undone via compensating transaction
CANCELLED: Cancelled before completion
FAILED: Execution failed

Core Concepts

Payment Allocation Waterfall

Loan repayments are allocated in a specific order (configurable per product):

Default Waterfall:

Penalties (overdue charges)
Fees (late fees, transaction fees)
Interest (accrued interest)
Principal (loan balance)

Example:

Payment Amount: 10,000
Outstanding:
  - Penalties: 1,500
  - Fees: 500
  - Interest Due: 3,000
  - Principal Due: 5,000
  - Principal Outstanding: 50,000

Allocation:
  1. Penalties: 1,500 (fully paid)
  2. Fees: 500 (fully paid)
  3. Interest: 3,000 (fully paid)
  4. Principal: 5,000 (fully paid)

Result: All current dues settled ✓

Schedule Management

Loans have repayment schedules that track:

Schedule State: PENDING, PAID, PARTIALLY_PAID, OVERDUE
Principal Due: Expected principal payment
Interest Due: Expected interest payment
Fees Due: Expected fee charges
Paid Amounts: Track what's been paid
Outstanding: Remaining balance

Multi-Schedule Support:

Original schedule preserved
Reschedule creates new schedule
Refinance links old and new schedules
History maintained for audit

Impact Tracking

Every loan transaction records exactly what changed:

ImpactedEntity {
  entityType: "LoanAccount"
  entityId: 67890
  fieldName: "PrincipalBalance"
  oldValue: 100000
  newValue: 95000
  deltaAmount: -5000  // The actual payment
}

Why this matters:

Enables accurate reversal even with concurrent payments
Complete audit trail of all balance changes
Supports multi-entity tracking (loan + schedules + deposit accounts)
Preserves data integrity

GL Integration

All loan transactions automatically post to General Ledger using double-entry accounting:

Disbursement Example:

DR: Loans Receivable (Portfolio Control)  +100,000
CR: Customer Deposits                      -95,000
CR: Fee Income                             -5,000

Repayment Example:

DR: Customer Deposits                      +10,000
CR: Interest Income                        -3,000
CR: Fee Income                             -500
CR: Penalty Income                         -1,500
CR: Loans Receivable                       -5,000

Write-Off Example:

DR: Write-Off Expense (Principal)          +50,000
DR: Write-Off Expense (Interest)           +5,000
CR: Loans Receivable                       -50,000
CR: Interest Receivable                    -5,000

Transaction Limits

All loan transactions respect configured limits:

Limit Type	Description	Enforcement
Maximum Loan Amount	Maximum disbursement per loan	Pre-validation
Minimum Repayment	Minimum payment amount	Pre-validation
Early Settlement	Early payoff restrictions	Date validation
Refinance Eligibility	Minimum tenure before refinance	Pre-check

Approval Workflows

Loan transactions can require approval based on:

Transaction amount (threshold)
Loan product type
Account status (overdue, provisioned)
User permissions
Product configuration

Workflow:

Create Transaction (PENDING)
    ↓
Check Approval Requirement
    ↓
Auto-Approve OR Await Approval
    ↓
Execute Transaction (COMPLETED)
    ↓
Update Loan Account & Schedules

API Integration

All loan transactions are executed via BPMCore command pattern:

Endpoint:

POST /api/bpm/cmd
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure - Loan Repayment:

{
  "commandName": "InitiateLoanRepaymentCommand",
  "data": {
    "loanAccountEncodedKey": "LOAN-001",
    "amount": 10000.00,
    "channelCode": "TELLER",
    "notes": "Monthly repayment"
  }
}

Response:

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Loan repayment completed successfully",
  "data": {
    "transactionKey": "TXN-2025-001",
    "loanAccountNumber": "LN-1234567890",
    "transactionState": "COMPLETED",
    "paymentAllocation": {
      "penalties": 1500.00,
      "fees": 500.00,
      "interest": 3000.00,
      "principal": 5000.00
    },
    "remainingBalance": 45000.00
  }
}

Concurrent Transaction Safety

BankLingo V2 ensures data integrity in concurrent scenarios:

Optimistic Locking

Every loan account has a Version field that increments with each update. Concurrent updates detected and retried.

Delta-Based Tracking

Changes tracked as deltas, not snapshots, preserving concurrent modifications.

Example Scenario

Time 10:00 - Principal Balance: 100,000
Time 10:01 - Repayment 5,000 PENDING
Time 10:02 - Interest Accrual 300 COMPLETED (balance: 100,300)
Time 10:03 - Repayment 5,000 COMPLETED (balance: 95,300)

Final: 95,300 ✓ (both transactions preserved)

Error Handling

All transactions use standard error codes:

Error Code	Description	Action
`00`	Success	Transaction completed
`01`	Insufficient payment	Increase payment amount
`05`	Loan account closed	Cannot transact
`12`	Invalid amount	Verify amount
`51`	Limit exceeded	Adjust amount
`91`	System error	Retry or contact support

Best Practices

For Developers

Always use TransactionImpactRecord for tracking
Track every field change with delta (loan balances, schedule updates)
Implement payment allocation waterfall correctly
Test concurrent repayment scenarios
Validate loan state before transactions
Update all related schedules atomically

For Operators

Review pending disbursements daily
Monitor overdue loans
Verify repayment allocations
Process write-offs with proper approvals
Review reversal requests promptly
Maintain comprehensive loan documentation

For Product Managers

Configure appropriate disbursement limits
Define clear repayment waterfall
Set up narration templates
Configure fee and penalty structures
Monitor loan portfolio health
Review and update policies

Next Steps

Explore specific transaction types:

For implementation:

Last Updated: January 4, 2026
Version: 2.0
Status: Production Ready

Overview​

Loan Product Types​

Transaction Types​

Core Loan Transactions​

Transaction States​

Core Concepts​

Payment Allocation Waterfall​

Schedule Management​

Impact Tracking​

GL Integration​

Transaction Limits​

Approval Workflows​

API Integration​

Concurrent Transaction Safety​

Optimistic Locking​

Delta-Based Tracking​

Example Scenario​

Error Handling​

Best Practices​

For Developers​

For Operators​

For Product Managers​

Next Steps​