magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250914878
##########
fineract-doc/src/docs/en/chapters/features/capitalized-income.adoc:
##########
@@ -0,0 +1,501 @@
+= Capitalized Income in Apache Fineract
+
+== Overview
+
+Capitalized Income (formerly referred to as Origination Fee) in Apache
Fineract is a fee-based or interest-based income item that is added to the
principal of a loan and amortized over time. It is designed to be applied at
disbursement and is treated as part of the loan's principal for repayment and
interest calculations.
+
+== Purpose
+
+This functionality enables financial institutions to:
+
+* Recognize deferred income (fees or interest) systematically over the loan
term
+* Align accounting practices with regulatory requirements
+* Improve income recognition accuracy
+
+== Supported Loan Type
+
+[IMPORTANT]
+====
+Capitalized Income is only supported for:
+
+* Progressive Loan Schedules
+* Advanced Payment Allocation Strategy
+
+Other loan schedule types and transaction processing strategies are not
supported.
+====
+
+== Configuration at Loan Product Level
+
+Capitalized income must be configured on the loan product.
+
+The configuration options include:
+
+* *Enable Capitalized Income*: Boolean toggle (default: disabled)
+* *Calculation Mode*: Only "Flat" is currently supported
+** Later "Percentage based" can be introduced
+* *Amortization Strategy*: Only "EQUAL_AMORTIZATION" is supported
+*** Daily equal portions are recognized over the life of the loan
+*** Later other strategies can be introduced
+* *Income Type*: Specifies allocation rule. Defines which "balance category"
to be used.
+
+[NOTE]
+====
+In Fineract, balance of a transaction is either: Principal, Fee, Penalty,
Interest or overpayment
+====
+
+Options:
+* FEE (default)
+* INTEREST
+
+=== GL Mapping
+
+Required GL Account mappings when Capitalized Income is enabled:
+
+* *Deferred Income (Liability)*: `deferredIncomeLiabilityAccountId` -
mandatory when enabled
+* *Income from Capitalization (Income)*: `incomeFromCapitalizationAccountId` -
mandatory when enabled
+
+[IMPORTANT]
+====
+Both GL accounts become mandatory when `enableIncomeCapitalization` is set to
`true`.
+====
+
+=== Configuration Dependencies
+
+When `enableIncomeCapitalization` is set to `true`, all following parameters
become mandatory:
+
+* `capitalizedIncomeCalculationType` - must be "FLAT"
+* `capitalizedIncomeStrategy` - must be "EQUAL_AMORTIZATION"
+* `capitalizedIncomeType` - must be "FEE" or "INTEREST"
+* `deferredIncomeLiabilityAccountId` - must reference a valid GL account
+* `incomeFromCapitalizationAccountId` - must reference a valid GL account
+
+== Behavior and Calculations
+
+* Capitalized income is added via API on or after the first disbursement date
+* It is treated as a principal portion, recalculating the repayment schedule
accordingly
+* Interest and amortization schedules are updated to include the capitalized
income amount
+* Validated to ensure that (Disbursement + Capitalized Income) ≤ Approved Loan
Amount
+
+=== Daily Amortization
+
+* Recognized daily using the configured strategy
+* Recognized portions move from Deferred Income to Income from Capitalization
+
+==== Special Handling
+
+* *Preclosure*: Remaining balance recognized in full on the preclosure date
+* *Charge-off*: Amortization stops and remaining balance is charged off
+
+== Transaction Types Introduced
+
+* Capitalized Income
+* Capitalized Income Amortization
+* Capitalized Income Adjustment
+* Capitalized Income Amortization Adjustment
+
+=== Capitalized Income Transaction
+
+The Capitalized Income transaction in Apache Fineract performs the following
actions:
+
+* Adds a specified amount to the loan principal
+** Considered a deferred income item (such as a fee or interest)
+** Booked as part of the loan's principal
+** Added post-disbursement and only if the loan type supports it (currently:
Progressive Loans)
+* Creates a distinct loan transaction
+** Separately tracked with its own transaction type ("Capitalized Income")
+** Not merged with disbursements or repayments
+* Updates the loan schedule
+** Recalculates amortization and interest schedule to include the added amount
in the outstanding principal
+* Triggers accounting entries
+** Debits "Loan Portfolio" (Asset)
+** Credits "Deferred Income" (Liability)
+** Does not recognize income upfront
+* Initiates daily amortization
+** Source for daily income recognition through "Capitalized Income
Amortization" transactions
+** Progressively converts the deferred amount to recognized income
+
+==== Accounting Entries
+
+[cols="2*"]
+|===
+|Scenario |Debit |Credit
+
+|Capitalized Income
+|Loan Portfolio (Asset)
+|Deferred Income (Liability)
+|===
+
+=== Capitalized Income Amortization
+
+A Capitalized Income Amortization transaction in Apache Fineract does the
following:
+
+* *Recognizes Deferred Income Over Time*: Transfers a portion of the
capitalized income (originally posted as a liability) into recognized income
(posted as interest or fee income), based on a configured daily amortization
strategy.
+
+* *Daily Posting*: The system automatically creates this transaction each day
from the date of capitalized income until the loan maturity or until the full
amount is amortized. This is handled by a background job during the COB (Close
of Business) process.
+
+* *Uses Equal Amortization*: The default and only supported strategy is Equal
Amortization, which divides the total capitalized income evenly over the
remaining number of days until the loan matures.
+
+==== Accounting Entries
+
+[cols="2*"]
+|===
+|Scenario |Debit |Credit
+
+|Daily amortization
+|Deferred Income (Liability)
+|Income from Capitalization (Income)
+|===
+
+==== Stops on Events
+
+* *Preclosure*: Triggers final amortization for remaining unrecognized income
+* *Charge-off*: Halts further amortization; the remaining deferred income is
charged off
+
+[NOTE]
+====
+Reversal Handling: If the original Capitalized Income transaction is reversed,
all associated amortization transactions are also reversed via "Capitalized
Income Amortization Adjustment" transactions.
+====
+
+=== Capitalized Income Adjustment
+
+A Capitalized Income Adjustment transaction in Apache Fineract serves to
reduce the balance of an existing capitalized income transaction.
+
+==== Purpose
+
+* Correct overcharged or misposted capitalized income amounts
+* Reflect fee waivers or negotiated reductions
+* Support backdated corrections if needed
+
+==== Transaction Behavior
+
+* It is a credit-type transaction, reducing the capitalized income balance
+* Treated similarly to other credit transactions and follows a defined
allocation strategy
+* Can be backdated, but not dated before the original capitalized income
transaction
+
+==== Validation Rules
+
+* The adjustment amount must not exceed the not-yet-recognized balance of the
original capitalized income
+* Adjustment is linked to a specific Capitalized Income transaction (by ID)
+* Multiple adjustments can be made against the same original transaction
+* Adjustments cannot be reversed, but must be re-applied if incorrect
+
+==== Accounting Entries
+
+[cols="3*"]
+|===
+|Scenario |Debit |Credit
+
+|Adjustment ≤ unrecognized balance
+|Deferred Income (Liability)
+|Loan Portfolio (Asset)
+
+|Adjustment > unrecognized balance
+|Deferred Income + Income
+|Loan Portfolio (Asset)
+|===
+
+==== Business Event Triggers
+
+* Triggers "Capitalized Income Adjustment" event
+* Updates loan balance and possibly loan status depending on impact
+
+==== Impact
+
+* Reduces amortization basis
+* May modify future amortization amounts
+* Repayment schedule is not affected directly unless recalculated manually
+
+=== Capitalized Income Amortization Adjustment
+
+A Capitalized Income Amortization Adjustment in Apache Fineract is a special
transaction type used to reverse previously recognized income from capitalized
income amortization.
+
+==== Purpose
+
+* Automatically generated when a Capitalized Income transaction is reversed
+* Reverses all already recognized portions (amortized income) linked to the
original Capitalized Income transaction
+
+==== When It Occurs
+
+* *Trigger*: Only initiated during the reversal of a Capitalized Income
transaction
+* Reverses all amortization that has occurred up to that point
+* Restores Deferred Income balances and reverses income recognition
+
+==== Accounting Entries
+
+[cols="3*"]
+|===
+|Transaction Type |Debit |Credit
+
+|Capitalized Income Amortization Adjustment
+|Income from Capitalization (Income)
+|Deferred Income (Liability)
+|===
+
+==== Key Characteristics
+
+* *System-Generated Only*: Cannot be created manually by API or UI
+* *Ensures Accounting Integrity*: Keeps amortized and unrecognized balances
aligned after reversals
+* *Links to Original Amortization*: Maintains traceability by referencing the
reversed Capitalized Income transaction
Review Comment:
Does not link to transactions
--
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]
