magyari-adam commented on code in PR #4913: URL: https://github.com/apache/fineract/pull/4913#discussion_r2256982061
########## fineract-doc/src/docs/en/chapters/features/buydown-fee.adoc: ########## @@ -0,0 +1,544 @@ += 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. + +== Purpose + +This functionality enables financial institutions to: + +* **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 + +== Supported Loan Type + +[IMPORTANT] +==== +Buy Down Fee is only supported for loans that have **all** of the following: + +* **Advanced Payment Allocation Strategy** (transaction processing strategy) +* **Progressive Loan Schedule** (loan schedule type) + +Other transaction processing strategies or loan schedule types are not supported. +==== + +== Configuration at Loan Product Level + +Buy Down Fee must be configured on the loan product. + +The configuration options include: + +* *Enable Buy Down Fee*: Boolean toggle (`enableBuyDownFee`) (default: disabled) +* *Calculation Mode*: Only "Flat" is currently supported (`buyDownFeeCalculationType`) +* *Amortization Strategy*: Only "EQUAL_AMORTIZATION" is supported (`buyDownFeeStrategy`) +** Daily equal portions are recognized over the life of the loan +* *Income Type*: Specifies allocation rule (`buyDownFeeIncomeType`) + +Options: +* FEE +* INTEREST + +=== GL Mapping + +Required GL Account mappings when Buy Down Fee is enabled: + +* *Buy Down Expense Account*: `buyDownExpenseAccountId` - mandatory when enabled +* *Deferred Income Liability Account*: `deferredIncomeLiabilityAccountId` - mandatory when enabled +* *Income from Buy Down Account*: `incomeFromBuyDownAccountId` - mandatory when enabled + +[IMPORTANT] +==== +All GL accounts become mandatory when `enableBuyDownFee` is set to `true`. +==== + +=== Configuration Dependencies + +When `enableBuyDownFee` is set to `true`, all following parameters become mandatory: + +* `buyDownFeeCalculationType` - must be "FLAT" +* `buyDownFeeStrategy` - must be "EQUAL_AMORTIZATION" +* `buyDownFeeIncomeType` - must be "FEE" or "INTEREST" +* `buyDownExpenseAccountId` - must reference a valid GL account +* `deferredIncomeLiabilityAccountId` - must reference a valid GL account +* `incomeFromBuyDownAccountId` - must reference a valid GL account + +== 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 +* Transaction date cannot be in the future +* Client/Group must be active +* Loan must be disbursed +* Multiple Buy Down Fee transactions per loan are supported + +=== Adjustment Validations + +* Original Buy Down Fee transaction must exist +* Adjustment amount cannot exceed remaining balance +* Adjustment date cannot be before original transaction date +* Cannot adjust if there are unreversed related transactions Review Comment: Buy down fee adjustments are related to the buy down fee transaction (they have relation with type `ADJUSTMENT` between them), and there can be more than one adjustment to the same buy down fee transaction. -- 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]
