You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fineract.apache.org by "oleksii-novikov-onix (via GitHub)" <gi...@apache.org> on 2025/08/04 07:24:59 UTC
[PR] FINERACT-2232: Add capitalize income documentation [fineract]
oleksii-novikov-onix opened a new pull request, #4919:
URL: https://github.com/apache/fineract/pull/4919
## Description
Describe the changes made and why they were made.
Ignore if these details are present on the associated [Apache Fineract JIRA ticket](https://github.com/apache/fineract/pull/1284).
## Checklist
Please make sure these boxes are checked before submitting your pull request - thanks!
- [ ] Write the commit message as per https://github.com/apache/fineract/#pull-requests
- [ ] Acknowledge that we will not review PRs that are not passing the build _("green")_ - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
- [ ] Create/update unit or integration tests for verifying the changes made.
- [ ] Follow coding conventions at https://cwiki.apache.org/confluence/display/FINERACT/Coding+Conventions.
- [ ] Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes
- [ ] Submission is not a "code dump". (Large changes can be made "in repository" via a branch. Ask on the developer mailing list for guidance, if required.)
FYI our guidelines for code reviews are at https://cwiki.apache.org/confluence/display/FINERACT/Code+Review+Guide.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250894024
##########
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
Review Comment:
They can be reversed.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "mariiaKraievska (via GitHub)" <gi...@apache.org>.
mariiaKraievska commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2251137151
##########
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
Review Comment:
I noticed this validation rule description might be a bit simplified compared to the actual implementation.
Looking at the code, the validation logic is actually:
`(Total Disbursed + Capitalized Income + New Transaction Amount) ≤ Max Amount`
Where Max Amount depends on loan product configuration:
- If `allowApprovedDisbursedAmountsOverApplied` is true: uses `getOverAppliedMax(loan)`
- Otherwise: uses `getApprovedPrincipal()`
Perhaps we could update the documentation to reflect these details?
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250907345
##########
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
Review Comment:
Created by daily amortization (COB) or final amortization (triggered on loan closure, or by any backdated transaction that affects capitalized income balances)
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250943380
##########
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
+
+==== Business Events
+
+* Triggers a new business event: Capitalized Income Amortization Adjustment
+* Also triggers standard balance and status update events if the loan is affected
+
+== API Endpoints
+
+=== Configure Capitalized Income on Loan Product
+
+* *Endpoint*: `/loanproducts`
+* *Method*: `POST`
+
+[source,json]
+----
+{
+ ...
+ "enableIncomeCapitalization": true, // Mandatory
+ "capitalizedIncomeCalculationType": "FLAT", // Mandatory when enabled
+ "capitalizedIncomeStrategy": "EQUAL_AMORTIZATION", // Mandatory when enabled
+ "capitalizedIncomeType": "FEE", // Mandatory when enabled
+ "deferredIncomeLiabilityAccountId": 123, // Mandatory when enabled
+ "incomeFromCapitalizationAccountId": 456 // Mandatory when enabled
+}
+----
+
+=== Add Capitalized Income
+
+* *Endpoint*: `/loans/{loanId}/transactions?command=capitalizedIncome`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions?command=capitalizedIncome`
+* *Method*: `POST`
+
+[source,json]
+----
+{
+ "transactionDate": "2025-05-01", // Mandatory
+ "dateFormat": "yyyy-MM-dd", // Mandatory
+ "locale": "en", // Mandatory
+ "transactionAmount": 100.0, // Mandatory
+ "paymentTypeId": 1, // Optional
+ "note": "Capitalized income fee", // Optional
+ "externalId": "CINCOME-001" // Optional
+}
+----
+
+==== Response Body
+
+[source,json]
+----
+{
+ "resourceId": 1,
+ "resourceExternalId": "CINCOME-001"
+}
+----
+
+=== Get Capitalized Income Amortization Info
+
+* *Endpoint*: `/loans/{loanId}/deferredincome`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/deferredincome`
+* *Method*: `GET`
+
+==== Response Body
+
+[source,json]
+----
+{
+ "capitalizedIncomeData": [
+ {
+ "amount": 50.0, // Total capitalized income amount
+ "amortizedAmount": 1.1, // Amount already amortized
+ "unrecognizedAmount": 48.9, // Amount not yet amortized
+ "amountAdjustment": 0.0, // Any adjustments made
+ "chargedOffAmount": 0.0 // Amount charged off (if applicable)
+ }
+ ]
+}
+----
+
+=== Add Capitalized Income Adjustment
+
+* *Endpoint*: `/loans/{loanId}/transactions/{capitalizedIncomeTransactionId}?command=capitalizedIncomeAdjustment`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions/{capitalizedIncomeTransactionId}?command=capitalizedIncomeAdjustment`
+* *Method*: `POST`
+
+[source,json]
+----
+{
+ "transactionDate": "2025-05-01", // Mandatory
+ "dateFormat": "yyyy-MM-dd", // Mandatory
+ "locale": "en", // Mandatory
+ "transactionAmount": 50.0, // Mandatory
+ "paymentTypeId": 1, // Optional
+ "note": "Capitalized income fee", // Optional
+ "externalId": "CINCOMEADJ-001" // Optional
+}
+----
+
+==== Response Body
+
+[source,json]
+----
+{
+ "resourceId": 1,
+ "resourceExternalId": "CINCOMEADJ-001"
+}
+----
+
+=== Capitalized Income Template API (to retrieve limits)
+
+* *Endpoint*: `/loans/{loanId}/transactions/template?command=capitalizedIncome`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions/template?command=capitalizedIncome`
+* *Method*: `GET`
+
+[source,json]
+----
+{
+ "paymentTypeOptions": [], // List of available payment types
+ "currency": {...}, // Currency configuration
+ "date": [2025, 5, 29], // Return the current date
+ "amount": 0 // Return the maximum amount that can be capitalized (approved amount - disbursed amount - capitalized income)
+}
+----
+
+=== Capitalized Income Adjustment Template API (to retrieve limits)
+
+* *Endpoint*: `/loans/{loanId}/transactions/template?command=capitalizedIncomeAdjustment`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions/template?command=capitalizedIncomeAdjustment`
Review Comment:
I would mention the `transactionId` query param 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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250893490
##########
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
Review Comment:
Total adjustment amount must not exceed the original Capitalized income transaction amount. It can be greater than the not-yet-recognized amount.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250910506
##########
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
Review Comment:
Can by triggered by backdated Capitalized income adjustment as well.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "adamsaghy (via GitHub)" <gi...@apache.org>.
adamsaghy merged PR #4919:
URL: https://github.com/apache/fineract/pull/4919
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250940346
##########
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
+
+==== Business Events
+
+* Triggers a new business event: Capitalized Income Amortization Adjustment
+* Also triggers standard balance and status update events if the loan is affected
+
+== API Endpoints
+
+=== Configure Capitalized Income on Loan Product
+
+* *Endpoint*: `/loanproducts`
+* *Method*: `POST`
+
+[source,json]
+----
+{
+ ...
+ "enableIncomeCapitalization": true, // Mandatory
+ "capitalizedIncomeCalculationType": "FLAT", // Mandatory when enabled
+ "capitalizedIncomeStrategy": "EQUAL_AMORTIZATION", // Mandatory when enabled
+ "capitalizedIncomeType": "FEE", // Mandatory when enabled
+ "deferredIncomeLiabilityAccountId": 123, // Mandatory when enabled
+ "incomeFromCapitalizationAccountId": 456 // Mandatory when enabled
+}
+----
+
+=== Add Capitalized Income
+
+* *Endpoint*: `/loans/{loanId}/transactions?command=capitalizedIncome`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions?command=capitalizedIncome`
+* *Method*: `POST`
+
+[source,json]
+----
+{
+ "transactionDate": "2025-05-01", // Mandatory
+ "dateFormat": "yyyy-MM-dd", // Mandatory
+ "locale": "en", // Mandatory
+ "transactionAmount": 100.0, // Mandatory
+ "paymentTypeId": 1, // Optional
+ "note": "Capitalized income fee", // Optional
+ "externalId": "CINCOME-001" // Optional
+}
+----
+
+==== Response Body
+
+[source,json]
+----
+{
+ "resourceId": 1,
+ "resourceExternalId": "CINCOME-001"
+}
+----
+
+=== Get Capitalized Income Amortization Info
+
+* *Endpoint*: `/loans/{loanId}/deferredincome`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/deferredincome`
+* *Method*: `GET`
+
+==== Response Body
+
+[source,json]
+----
+{
+ "capitalizedIncomeData": [
+ {
+ "amount": 50.0, // Total capitalized income amount
+ "amortizedAmount": 1.1, // Amount already amortized
+ "unrecognizedAmount": 48.9, // Amount not yet amortized
+ "amountAdjustment": 0.0, // Any adjustments made
+ "chargedOffAmount": 0.0 // Amount charged off (if applicable)
+ }
+ ]
+}
+----
+
+=== Add Capitalized Income Adjustment
+
+* *Endpoint*: `/loans/{loanId}/transactions/{capitalizedIncomeTransactionId}?command=capitalizedIncomeAdjustment`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions/{capitalizedIncomeTransactionId}?command=capitalizedIncomeAdjustment`
+* *Method*: `POST`
+
+[source,json]
+----
+{
+ "transactionDate": "2025-05-01", // Mandatory
+ "dateFormat": "yyyy-MM-dd", // Mandatory
+ "locale": "en", // Mandatory
+ "transactionAmount": 50.0, // Mandatory
+ "paymentTypeId": 1, // Optional
+ "note": "Capitalized income fee", // Optional
+ "externalId": "CINCOMEADJ-001" // Optional
+}
+----
+
+==== Response Body
+
+[source,json]
+----
+{
+ "resourceId": 1,
+ "resourceExternalId": "CINCOMEADJ-001"
+}
+----
+
+=== Capitalized Income Template API (to retrieve limits)
+
+* *Endpoint*: `/loans/{loanId}/transactions/template?command=capitalizedIncome`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions/template?command=capitalizedIncome`
+* *Method*: `GET`
+
+[source,json]
+----
+{
+ "paymentTypeOptions": [], // List of available payment types
+ "currency": {...}, // Currency configuration
+ "date": [2025, 5, 29], // Return the current date
+ "amount": 0 // Return the maximum amount that can be capitalized (approved amount - disbursed amount - capitalized income)
+}
+----
+
+=== Capitalized Income Adjustment Template API (to retrieve limits)
+
+* *Endpoint*: `/loans/{loanId}/transactions/template?command=capitalizedIncomeAdjustment`
+* *Alternative Endpoint*: `/loans/external-id/{loanExternalId}/transactions/template?command=capitalizedIncomeAdjustment`
+* *Method*: `GET`
+
+[source,json]
+----
+{
+ "paymentTypeOptions": [], // List of available payment types
+ "currency": {...}, // Currency configuration
+ "date": [2025, 5, 29], // Return the current date
+ "amount": 0 // Return the maximum amount that can be adjusted (capitalized income - adjustment)
+}
+----
+
+== Accounting Entries
+
+[cols="3*"]
+|===
+|Transaction Type |Debit |Credit
+
+|Capitalized Income
+|Loan Portfolio (Asset)
+|Deferred Income (Liability)
+
+|Capitalized Income Amortization
+|Deferred Income (Liability)
+|Income from Capitalization (Income)
+
+|Capitalized Income Adjustment
+|Deferred Income (Liability) / Income from Capitalization (Income)
Review Comment:
Income from Capitalization will be debited by Capitalized Income Amortization Adjustment if needed, this transaction does not debit it.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250917235
##########
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
+
+==== Business Events
+
+* Triggers a new business event: Capitalized Income Amortization Adjustment
+* Also triggers standard balance and status update events if the loan is affected
Review Comment:
Non-monetary transaction, can not trigger balance changed, or status update events.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] FINERACT-2232: Add capitalize income documentation [fineract]
Posted by "magyari-adam (via GitHub)" <gi...@apache.org>.
magyari-adam commented on code in PR #4919:
URL: https://github.com/apache/fineract/pull/4919#discussion_r2250899643
##########
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)
Review Comment:
Debiting from incomeFromCapitalizationAccount is handled by daily/final amortization. The adjustments only debit Deferred income liability.
--
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: commits-unsubscribe@fineract.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org