magyari-adam commented on code in PR #4913:
URL: https://github.com/apache/fineract/pull/4913#discussion_r2248129900
##########
fineract-doc/src/docs/en/chapters/features/buydown-fee.adoc:
##########
@@ -0,0 +1,637 @@
+= Buy Down Fee
+
+== Overview
+
+Buy Down Fee is a specialized fee mechanism in Apache Fineract that allows
financial institutions to collect upfront fees from borrowers to reduce their
effective interest rate over the loan term. This feature is particularly
designed for 0% interest "buy down" loans where a merchant fee is collected and
amortized into interest/fee income over the life of the loan.
+
+The key characteristic of Buy Down Fee is that the amortized fee is **NOT
visible to the customer** and **NOT affecting the repayment schedule** - it
operates as a background process for proper revenue recognition while
maintaining transparency in customer-facing loan terms.
+
+=== Key Benefits
+
+* **Interest Rate Reduction**: Borrowers can reduce their effective interest
rate by paying an upfront fee
+* **Merchant Fee Support**: Enables 0% interest loan products with
merchant-paid fees
+* **Revenue Recognition**: Provides controlled amortization of fee income over
the loan term
+* **Customer Transparency**: Fee amortization is invisible to customers,
maintaining clean loan presentation
+* **Accounting Integration**: Proper journal entries and accounting treatment
for fee transactions
+
+== Buy Down Fee Configuration
+
+=== Prerequisites
+
+Before enabling Buy Down Fee functionality, ensure the following prerequisites
are met:
+
+* **Loan Product Type**: Only Progressive Loan products support Buy Down Fee
functionality
+* **Accounting Method**: Accrual accounting must be enabled for proper income
recognition and amortization
+* **General Ledger Accounts**: Required GL accounts must be configured
+
+=== Required Configuration Parameters
+
+When creating or updating a loan product with Buy Down Fee enabled, the
following parameters are mandatory:
+
+[cols="2,1,3", options="header"]
+|===
+|Parameter |Required |Description
+
+|`enableBuyDownFee`
+|Yes
+|Boolean flag to enable/disable Buy Down Fee functionality
+
+|`buyDownFeeCalculationType`
+|Yes*
+|Calculation method for Buy Down Fee. Currently only `FLAT` is supported
+
+|`buyDownFeeStrategy`
+|Yes*
+|Amortization strategy. Currently only `EQUAL_AMORTIZATION` is supported
+
+|`buyDownFeeIncomeType`
+|Yes*
+|Income recognition type: `FEE` or `INTEREST`
+
+|`buyDownExpenseAccountId`
+|Yes*
+|GL Account ID for Buy Down Fee expense recognition
+
+|`incomeFromBuyDownAccountId`
+|Yes*
+|GL Account ID for Buy Down Fee income recognition during amortization
+
+|`deferredIncomeLiabilityAccountId`
+|Yes*
+|GL Account ID for Deferred Income Liability Account used during amortization
+
+|`loanScheduleType`
+|Yes
+|Loan schedule type, must be set to "PROGRESSIVE" for Buy Down Fee
+|===
+
+_* Required only when `enableBuyDownFee` is set to `true`_
+
+=== Accounting Mappings
+
+Buy Down Fee requires specific GL account mappings for proper financial
reporting:
+
+==== Required GL Accounts
+
+* **Buy Down Expense Account** (`buyDownExpenseAccountId`)
+ - Account Type: EXPENSE
+ - Purpose: Records the initial Buy Down Fee expense when transaction is
created
+ - Journal Entry: Debit when Buy Down Fee is added
+
+* **Income from Buy Down Account** (`incomeFromBuyDownAccountId`)
+ - Account Type: INCOME
+ - Purpose: Records income recognition during daily amortization process
+ - Journal Entry: Credit during COB amortization
+
+==== Journal Entry Flow
+
+1. **Buy Down Fee Creation**:
+ - Debit: Buy Down Expense Account
+ - Credit: Cash/Bank Account
+
+2. **Daily Amortization** (via COB):
+ - Debit: Deferred Capitalized Income
+ - Credit: Fee/Interest Income Account
+
+3. **Buy Down Fee Adjustment**:
+- Debit: Deferred Income Liability
+- Credit: Buy Down Expense Account
+
+4. **Buy Down Fee Amortization Adjustment**:
+- Debit: Deferred Income Liability
+- Credit: Income from Buy Down Account
+
+5. **Charge-off Handling**:
+- Debit: Losses Written Off Account
+- Credit: Deferred Income Liability
+
+=== Validation Rules
+
+The system enforces the following validation rules:
+
+==== Product Level Validations
+
+* Buy Down Fee can only be enabled for Progressive Loan products
+* When `enableBuyDownFee` is `true`, all related parameters become mandatory
+* Calculation type must be `FLAT` (other types not yet supported)
+* Strategy must be `EQUAL_AMORTIZATION` (other strategies not yet supported)
+* Income type must be either `FEE` or `INTEREST`
+* Both expense and income GL accounts must be provided and valid
+* GL accounts must have correct account types (EXPENSE and INCOME respectively)
+* `deferredIncomeLiabilityAccountId` mapping requirements:
+ - Must be a valid LIABILITY type GL account
+ - Represents temporary holding of not-yet-recognized income
+ - Used to track unamortized Buy Down Fee portion
+ - Cannot be zero or null when Buy Down Fee is enabled
+
+==== Transaction Level Validations
+
+* Buy Down Fee transactions can only be added to active loans
+* Transaction amount must be positive (greater than zero)
+* Transaction date cannot be before the first disbursement date
+* Loan must have Buy Down Fee enabled in its product configuration
+
+==== Adjustment Validations
+
+A Buy Down Fee adjustment is a mechanism to modify an existing Buy Down Fee
transaction after its initial creation. It allows financial institutions to:
+
+* Reduce the total Buy Down Fee amount
+* Correct errors in the initial fee calculation
+
+===== Adjustment Validations:
+
+* Adjustment amount cannot exceed the original Buy Down Fee amount
+* Total adjustments cannot exceed the remaining unadjusted amount
+* Adjustments can only be made to existing Buy Down Fee transactions
+* Standard payment details validation applies (payment type, notes, etc.)
+
+=== Configuration Examples
+
+==== Enabling Buy Down Fee
+
+[source,json]
+----
+{
+ "enableBuyDownFee": true,
+ "buyDownFeeCalculationType": "FLAT",
+ "buyDownFeeStrategy": "EQUAL_AMORTIZATION",
+ "buyDownFeeIncomeType": "FEE",
+ "buyDownExpenseAccountId": 123,
+ "incomeFromBuyDownAccountId": 456,
+ // ... other loan product parameters
+}
+----
+
+==== Disabling Buy Down Fee
+
+[source,json]
+----
+{
+ "enableBuyDownFee": false
+ // buyDownFee* parameters are optional when disabled
+}
+----
+
+=== Error Scenarios
+
+Common validation errors and their resolutions:
+
+* **"Buy Down Fee calculation type is required"**: Provide
`buyDownFeeCalculationType` when enabling Buy Down Fee
+* **"Buy Down Fee strategy is required"**: Provide `buyDownFeeStrategy` when
enabling Buy Down Fee
+* **"Buy Down Fee income type is required"**: Provide `buyDownFeeIncomeType`
when enabling Buy Down Fee
+* **"Buy Down expense account is required"**: Provide valid
`buyDownExpenseAccountId`
+* **"Income from Buy Down account is required"**: Provide valid
`incomeFromBuyDownAccountId`
Review Comment:
Deferred income liability account is missing here
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
