Command Palette

Search for a command to run...

B
Request
Guide

Loan Lifecycle Management

A comprehensive guide to managing the complete loan lifecycle in Apache Fineract, from application submission through to final closure.

Loan States

Submitted
Approved
Disbursed
Active
Closed

Each loan progresses through these states. Understanding the state transitions helps you implement proper workflow controls in your application.

1. Create Loan Application

Submit a loan application for a client. You'll need the client ID and a loan product ID.

bash
curl --request POST \
  --url "https://your-instance.com/fineract-provider/api/v1/loans" \
  --header "Authorization: Basic {credentials}" \
  --header "Fineract-Platform-TenantId: default" \
  --header "Content-Type: application/json" \
  --data '{
    "clientId": 1,
    "productId": 1,
    "principal": 10000,
    "loanTermFrequency": 12,
    "loanTermFrequencyType": 2,
    "numberOfRepayments": 12,
    "repaymentEvery": 1,
    "repaymentFrequencyType": 2,
    "interestRatePerPeriod": 2,
    "amortizationType": 1,
    "interestType": 0,
    "interestCalculationPeriodType": 1,
    "transactionProcessingStrategyId": 1,
    "expectedDisbursementDate": "15 January 2024",
    "submittedOnDate": "01 January 2024",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'

Key Parameters

  • loanTermFrequencyType: 0=Days, 1=Weeks, 2=Months, 3=Years
  • repaymentFrequencyType: Same as above
  • amortizationType: 0=Equal Principal, 1=Equal Installments
  • interestType: 0=Declining Balance, 1=Flat

2. Approve Loan

After reviewing the application, approve the loan with the approved amount and date.

bash
curl --request POST \
  --url "https://your-instance.com/fineract-provider/api/v1/loans/1?command=approve" \
  --header "Authorization: Basic {credentials}" \
  --header "Fineract-Platform-TenantId: default" \
  --header "Content-Type: application/json" \
  --data '{
    "approvedOnDate": "05 January 2024",
    "approvedLoanAmount": 10000,
    "expectedDisbursementDate": "15 January 2024",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en",
    "note": "Approved after credit check"
  }'

3. Disburse Loan

Disburse the approved loan to the client. This activates the loan and starts the repayment schedule.

bash
curl --request POST \
  --url "https://your-instance.com/fineract-provider/api/v1/loans/1?command=disburse" \
  --header "Authorization: Basic {credentials}" \
  --header "Fineract-Platform-TenantId: default" \
  --header "Content-Type: application/json" \
  --data '{
    "actualDisbursementDate": "15 January 2024",
    "transactionAmount": 10000,
    "paymentTypeId": 1,
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'

4. Make Repayments

Record loan repayments as the client makes payments:

bash
curl --request POST \
  --url "https://your-instance.com/fineract-provider/api/v1/loans/1/transactions?command=repayment" \
  --header "Authorization: Basic {credentials}" \
  --header "Fineract-Platform-TenantId: default" \
  --header "Content-Type: application/json" \
  --data '{
    "transactionDate": "15 February 2024",
    "transactionAmount": 900,
    "paymentTypeId": 1,
    "dateFormat": "dd MMMM yyyy",
    "locale": "en",
    "note": "Monthly payment"
  }'

View Repayment Schedule

Retrieve the loan with its repayment schedule:

bash
curl --request GET \
  --url "https://your-instance.com/fineract-provider/api/v1/loans/1?associations=repaymentSchedule,transactions" \
  --header "Authorization: Basic {credentials}" \
  --header "Fineract-Platform-TenantId: default"

Best Practices

  • Always validate client eligibility before loan submission
  • Use idempotency keys for transaction operations
  • Implement proper error handling for each state transition
  • Store external references for reconciliation
  • Set up webhooks to track loan state changes