Test for document automation - Capitalized Income feature

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. It aligns accounting practices with regulatory requirements and improves income recognition accuracy.

Supported Loan Type

• Only supported for Progressive Loan Schedules!

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. (In Fineract balance of a transaction is either: Principal, Fee, Penalty, Interest or overpayment).

  • Options:

    • FEE (default)

    • INTEREST

• GL Mapping:

  • Deferred Income (Liability)

  • Income from Capitalization (Income)

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 for pre-closure and charge-off scenarios:

  • 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

The Capitalized Income transaction in Apache Fineract performs the following actions:

1. Adds a specified amount to the loan principal — This amount is considered a deferred income item (such as a fee or interest) but is booked as part of the loan's principal. It's added post-disbursement and only if the loan type supports it (currently: Progressive Loans).

2. Creates a distinct loan transaction — This transaction is separately tracked with its own transaction type ("Capitalized Income") and is not merged with disbursements or repayments.

3. Updates the loan schedule — Upon adding this transaction, the system recalculates the amortization and interest schedule to include this added amount in the outstanding principal.

4. Triggers accounting entries — It debits the "Loan Portfolio" (Asset) and credits "Deferred Income" (Liability), thus not recognizing income upfront.

5. Initiates daily amortization — This transaction becomes the source for daily income recognition through "Capitalized Income Amortization" transactions, progressively converting the deferred amount to recognized income.

6. Accounting Entries:

Capitalized Income Amortization

A Capitalized Income Amortization transaction in Apache Fineract does the following:

1. Recognizes Deferred Income Over Time: It 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.

2. 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.

3. 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.

4. Accounting Entries:

   1. This recognizes income progressively and complies with accrual accounting principles.

5. Stops on Events:

6. Preclosure: Triggers final amortization for remaining unrecognized income.

7. Charge-off: Halts further amortization; the remaining deferred income is charged off.

8. 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. Here’s how it works and what it does:

1. Purpose:

   • Correct overcharged or misposted capitalized income amounts.

   • Reflect fee waivers or negotiated reductions.

   • Support backdated corrections if needed.

2. 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.

3. 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.

4. Accounting Entries:

5. Business Event Triggers:

   • Triggers "Capitalized Income Adjustment" event.

   • Updates loan balance and possibly loan status depending on impact.

6. 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. It ensures that accounting and balances remain accurate when the original capitalized income is reversed or adjusted. Here's a breakdown:

1. Purpose:

• Automatically generated when a Capitalized Income transaction is reversed.

• Reverses all already recognized portions (amortized income) linked to the original Capitalized Income transaction.

2. When It Occurs

• Trigger: Only initiated during the reversal of a Capitalized Income transaction.

• Reverses all amortization that has occurred up to that point, restoring Deferred Income balances and reversing income recognition.

3. Accounting Entries

4. 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.

5. 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

1. Configure Caplitalized Income on Loan product

   • Endpoint: /loanproducts

   • Method: POST

   • Request Body:

   • { ... "enableIncomeCapitalization": true, //Mandatory "capitalizedIncomeCalculationType": "FLAT", //Mandatory "capitalizedIncomeStrategy": "EQUAL_AMORTIZATION", //Mandatory "capitalizedIncomeType": "FEE" //Mandatory }

2. Add Capitalized Income

   • Endpoint: /loans/{loanId}?command=capitalizedIncome

   • Method: POST

   • Request Body:

     { "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:

   • { "resourceId": 1, "resourceExternalId": "CINCOME-001" }

3. Get Capitalized Income Amortization Info NOT YET IMPLEMENTED

   • Endpoint: /loans/{loanId}/capitalizedincome

   • Method: GET

4. Add Capitalized Income Adjustment

   • Endpoint: /loans/{loanId}/transactions/{capitalizedIncomeTransactionId}?command=capitalizedIncomeAdjustment

   • Method: POST

   • Request Body:

     { "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:

   • { "resourceId": 1, "resourceExternalId": "CINCOMEADJ-001" }

5. Capitalized Income Template API (to retrieve limits)

   • Endpoint: /loans/{loanId}/transactions/template?command=capitalizedIncome

   • Method: GET

   • Response body:

   • { "paymentTypeOptions" : [] //List of available payment types "currency": {...} //Currency configuration "date": [ //Return the current date 2025, 5, 29 ], "amount": 0, //Return the maximum amount that can be capitalized (approved amount - disbursed amount - capitalized income) }

6. Capitalized Income Adjustment Template API (to retrieve limits):

   • Endpoint: /loans/{loanId}/transactions/template?command=capitalizedIncomeAdjustment

   • Method: GET

   • Response body:

   • { "paymentTypeOptions" : [] //List of available payment types "currency": {...} //Currency configuration "date": [ //Return the current date 2025, 5, 29 ], "amount": 0, //Return the maximum amount that can be adjusted (capitalized income - adjustment) }

Accounting Entries

Business Events

• Triggered for:

  • Capitalized Income

    • LoanCapitalizedIncomeTransactionCreatedBusinessEvent

    • LoanBalanceChangedBusinessEvent

  • Daily Amortization

    • LoanCapitalizedIncomeAmortizationTransactionCreatedBusinessEvent

    • LoanCapitalizedIncomeAmortizationAdjustmentTransactionCreatedBusinessEvent

  • Capitalized Income Adjustment

    • LoanCapitalizedIncomeAdjustmentTransactionCreatedBusinessEvent

    • LoanBalanceChangedBusinessEvent

  • Reversal

    • LoanAdjustTransactionBusinessEvent

Database structure

Configuration

• Stored on loan product (m_product_loan):

  • enable_income_capitalization

  • capitalized_income_calculation_type

  • capitalized_income_strategy

  • capitalized_income_type

• Stored on loan (m_loan):

  • enable_income_capitalization

  • capitalized_income_calculation_type

  • capitalized_income_strategy

  • capitalized_income_type

Balances

• On loan:

  • capitalized_income_derived

  • capitalized_income_adjustment_derived

• Capitalized income balance (m_loan_capitalized_income_balance):

  • Each capitalized income has its own balance (1 row for each transaction)

• id version loan_id loan_transaction_id amount //capitalized income transaction amount date //capitalized income transaction date unrecognized_amount //amortization - not yet recognized amount charged_off_amount // charged-off balance amount_adjustment // total adjustment amount created_by //Audit fields created_on_utc last_modified_by last_modified_on_utc

Notes

• Capitalized income transactions support backdating.

• Adjustment transactions must not predate the original capitalized income.

• No automatic reversal is supported; must be handled manually via dedicated transactions.

• Proper GL accounts must be set for Deferred Income and Income from Capitalization to enable this functionality.