Down Payment Configuration

A down payment in Fineract is a portion of the disbursed amount that is immediately collected back from the borrower as a repayment on the same day as disbursement. It reduces the effective credit extended and is commonly used in hire-purchase, BNPL, and asset-backed lending products.

---

How It Works

When down payment is enabled on a loan product, every disbursement on a loan triggers an automatic repayment transaction equal to a configured percentage of the disbursed amount. For multi-tranche loans, a down payment is collected on each tranche disbursement independently.

• The down payment transaction is posted on the same date as the disbursement
• It reduces outstanding principal immediately, before the first regular instalment is due
• If enableAutoRepaymentForDownPayment is true, the repayment is created automatically by Fineract; no manual transaction is required
• The repayment schedule is calculated on the principal after the down payment is applied

---

Product-Level Configuration

Via API

Include the following fields when creating or updating a loan product:

POST /fineract-provider/api/v1/loanproducts
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "enableDownPayment": true,
  "disbursedAmountPercentageForDownPayment": 20.0,
  "enableAutoRepaymentForDownPayment": true
}

Field	Type	Meaning
enableDownPayment	boolean	Activates the down payment feature on the product
disbursedAmountPercentageForDownPayment	decimal	Percentage of each disbursed amount to collect as down payment (e.g. 20.0 = 20%)
enableAutoRepaymentForDownPayment	boolean	If true, Fineract automatically posts the repayment transaction on disbursement. If false, staff must post it manually

Progressive loans only

Down payment is supported on Progressive loan products only ("loanScheduleType": "PROGRESSIVE"). It requires advanced-payment-allocation-strategy as the transaction processing strategy. See the Progressive Loan Configuration guide for the full product setup.

Via UI (Mifos X Web App)

1. Navigate to Products → Loan Products
2. Click Create Loan Product or edit an existing product
3. In the Settings tab, scroll to the Down Payment section
4. Tick Enable Down Payment
5. Enter the percentage in the Down payment percentage field
6. Tick Enable auto repayment for down payment if you want Fineract to post the repayment automatically
7. Save the product

---

Loan-Level Override

By default, every loan created from a product inherits the down payment percentage set on that product. You can override the down payment amount (not the percentage) at loan creation time when the product allows it.

This is useful when the standard percentage does not suit a specific borrower or deal — for example, a product configured at 20% but a borrower negotiating a 30% upfront payment.

Via API

Pass downPaymentAmount in the loan creation request:

POST /fineract-provider/api/v1/loans
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "clientId": 42,
  "productId": 7,
  "principal": 10000,
  "loanTermFrequency": 12,
  "loanTermFrequencyType": 2,
  "numberOfRepayments": 12,
  "repaymentEvery": 1,
  "repaymentFrequencyType": 2,
  "interestRatePerPeriod": 1.5,
  "amortizationType": 1,
  "interestType": 0,
  "interestCalculationPeriodType": 0,
  "transactionProcessingStrategyCode": "advanced-payment-allocation-strategy",
  "loanScheduleType": "PROGRESSIVE",
  "expectedDisbursementDate": "01 April 2026",
  "downPaymentAmount": 3000,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

In this example, the product default would collect 20% of 10 000 = 2 000 as down payment. The downPaymentAmount: 3000 override raises that to 3 000 for this specific loan.

Flat amount, not percentage

downPaymentAmount is a currency amount, not a percentage. It must not exceed the disbursed principal.

Via UI

During loan application:

1. Navigate to the client record and open Add Loan
2. Select the loan product
3. In the Terms tab, locate the Down Payment Amount field (visible only when the product has enableDownPayment: true)
4. Clear the pre-populated default and enter the specific amount
5. Continue through approval and disbursement as normal

---

Auto-Repayment Behaviour

When enableAutoRepaymentForDownPayment: true, Fineract posts the down payment repayment as a system transaction at disbursement time. This transaction:

• Appears in the loan transaction history with type DOWN_PAYMENT
• Is allocated against principal first, following the product's paymentAllocation rules
• Is visible in the repayment schedule as a reduction to the opening balance before the first instalment

When enableAutoRepaymentForDownPayment: false, the down payment is still tracked and expected, but staff must post a manual repayment transaction on disbursement day. The loan will appear as having an outstanding balance equal to the full disbursed amount until that repayment is posted.

For production deployments, always enable auto-repayment unless your workflow requires manual verification of each down payment receipt before it is applied.

---

Accounting Impact

The automatic down payment transaction creates the same accounting entries as a regular loan repayment:

Entry	Debit	Credit
Down payment received	Loan Portfolio (asset) reduction	Cash / Suspense

No separate GL account is required for down payments — they post through the same income and asset accounts as configured in the loan product's accounting settings.

---

Verifying Down Payment on a Loan

After disbursement, confirm the down payment was applied:

# Retrieve all transactions on the loan
GET /fineract-provider/api/v1/loans/{loanId}/transactions

# Retrieve the current repayment schedule
GET /fineract-provider/api/v1/loans/{loanId}/repaymentschedule

In the transactions response, look for a transaction with "type": { "code": "loanTransactionType.downPayment" }. In the repayment schedule, the opening outstanding principal should already reflect the reduction.

---

Common Mistakes

Mistake	Effect	Fix
Enabling down payment on a Cumulative product	Feature is ignored or causes errors	Down payment requires a Progressive product with advanced-payment-allocation-strategy
enableAutoRepaymentForDownPayment: false in production	Loan outstanding balance is overstated until staff posts the repayment manually	Set to true unless manual posting is an explicit workflow requirement
Providing downPaymentAmount greater than the disbursed principal	API returns a validation error	Ensure the override amount is less than or equal to the disbursed amount
Forgetting down payment on multi-tranche loans	Only the first tranche collects a down payment if product is set up correctly; subsequent tranches also trigger it — verify this is intended	Review per-tranche disbursement transactions after each release
Not accounting for the down payment when quoting the repayment schedule to borrowers	Borrower sees the pre-down-payment schedule in the loan offer	Always retrieve the schedule after the down payment has been applied