adamsaghy commented on code in PR #4913: URL: https://github.com/apache/fineract/pull/4913#discussion_r2245278453
########## fineract-doc/src/docs/en/chapters/features/buydown-fee.adoc: ########## @@ -0,0 +1,630 @@ += 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 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** - 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 +* **Cash Flow Management**: Helps borrowers manage their payment obligations over time +* **Revenue Recognition**: Provides controlled amortization of fee income over the loan term +* **Customer Transparency**: Fee amortization is invisible to customers, maintaining clean loan presentation +* **Flexible Loan Products**: Enables creation of diverse loan products to meet different customer needs +* **Accounting Integration**: Proper journal entries and accounting treatment for fee transactions + +== Fee Types Overview + +Apache Fineract supports various fee calculation types across different product categories: + +=== Loan Fees +* **Flat**: Fixed amount fee +* **Percent of Amount**: Percentage of loan principal +* **Percent of Amount and Interest**: Percentage of principal plus interest +* **Percent of Interest**: Percentage of interest amount only +* **Percent of Disbursement Amount**: Percentage of disbursed amount + +=== Savings Fees +* **Flat**: Fixed amount fee +* **Percent of Amount**: Percentage of account balance + +=== Client Fees +* **Flat**: Fixed amount fee only + +=== Share Fees +* **Flat**: Fixed amount fee +* **Percent of Amount**: Percentage of share value + +== 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 for expense and income mappings + +=== 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 +|=== + +_* 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 (if payment involved) + +2. **Daily Amortization** (via COB): + - Debit: Deferred Income Liability Account + - Credit: Income from Buy Down Account + +=== 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) + +==== 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 Review Comment: What does "adjustment" mean? ( i mean i know what it means, but the documentation not yet explained!) -- 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]
