Re-engineering Fineract 1. x

This guide helps developers learn how to create a new type of numerical computation in loan lifecycle in Fineract 1.x.

Adding Net Disbursal Amount logic to different Loan Lifecycle Events in Fineract

This guide inspires open-source engineering in Fineract 1. x for functional agents and developers.

To explain a bit here, loan disbursal creates a transaction amount. The actual disbursal transaction may be dependent on a few factors as there are activities such as processing charge collection, loan discounting, existing relationship with the borrower in the form of an already running loan, etc. Therefore, an indicative disbursal transaction amount helps the operational users of any Financial Institution using the Fineract platform. This indicative disbursal amount is known as Net Disbursal Amount.

Net Disbursal Amount (NDA) represents the loan amount disbursed, void of any fees or costs of the financial transactions. I worked on implementing this feature at certain event states of a loan’s lifecycle. This article covers use cases for two types of loan categories - regular loans and loans where a refinance takes place.

A top-up loan links an existing loan schedule and carries forward the outstanding balance of this loan to a new loan(with refinanced conditions, of course). A top-up loan, however, can be used for multiple types of loan behaviours and loan products where essentially the terms and conditions for the loan change. These use cases result from different scenarios, e.g. if the borrower or the financial institution is renegotiating the credit or if the loan portfolio may get securitized.

NDA is an attribute included and recalculated with respect to specific events such as Approval, Disbursal, and Reversal of both Approval and Disbursal of a loan lifecycle. As such, the indicative net disbursal amount is based on the loan amount at varying points of this cycle. These arithmetics are done for regular loans but also enhanced for top-up loans by taking into consideration the top-up amount of the previous loan.

I have cited examples from a recent partner case study by the Muellners Foundation and therefore used the Philippine peso as the choice of currency here.

1. Loan lifecycle event states:

• Pre-Approval

• Post-Approval

• Post-Disbursal

• Disbursal Reversal

• Approval Reversal

2. For a Regular Loan:

Consider the following scenario: A loan application is submitted with a proposed amount of PHP 10,000. Assuming there are two charges;

• charge 1 - fee due at disbursement, which is a flat amount of 95 PHP

• charge 2 - fee due at disbursement, which is 7.5% of the loan amount

A. Pre-Approval Event:

This state signifies that the net disbursal amount is calculated with respect to the proposed loan amount for the loan application. In other words:

NDA = Proposed Amount - Charges at Disbursal

Considering the scenario mentioned above and assuming the amount offered was 10,000 PHP, the net disbursal amount will be calculated as follows:

NDA calculated pre-approval of regular loan based on proposed amount

NDA = 10,000 - (95 + 750) = 9155 PHP

B. Post-Approval Event:

Here, at this stage, the Net Disbursal Amount is calculated with respect to the approved loan amount for the loan. In other words:

NDA = Approved Amount - Charges at Disbursal

Considering the scenario mentioned above and assuming the amount approved was 9,000 PHP, the net disbursal amount will be calculated and, in fact, updated from the previous stage in the fashion below:

NDA = 9,000 - (95 + 675) = 8230 PHP

C. Post-Disbursal Event:

This stage signifies that the Net Disbursal Amount is calculated with respect to the disbursed loan amount for the loan. In other words:

NDA = Disbursed Amount - Charges at Disbursal

Considering the scenario mentioned above and assuming the amount disbursed was 8,000 PHP, the net disbursal amount will be calculated and updated as follows:

NDA = 8,000 - (95 + 600) = 7305 PHP

D. Reversal of Loan Disbursement:

After disbursal of the loan, if, say, the disbursal is reversed, then we are looking at the case of disbursal transaction to roll back. The Net Disbursal Amount is calculated and updated again with respect to the approved loan amount. In other words:

NDA = Approved Amount - Charges at Disbursal

Considering the scenario mentioned above and assuming the amount disbursed was 8,000 PHP, the net disbursal amount will be calculated as follows:

NDA = 9,000 - (95 + 675) = 8230 PHP

E. Reversal of Approval of Loan

If an approved loan is tempted to be reversed, the Net Disbursal Amount is recalculated with respect to the proposed loan amount. In other words:

NDA = Proposed Amount - Charges at Disbursal

Considering the scenario mentioned above, the amount proposed was 10,000 PHP. The net disbursal amount will be calculated as follows:

NDA = 10,000 - (95 + 750) = 9155 PHP

3. Now, for a Refinanced Loan using the Top Up Feature:

Consider the following scenario:

A loan application is submitted with a proposed amount of 10,000 PHP. Assuming there are two charges, the similar type that I considered in the above use case -

• charge 1 - fee due at disbursement, which is a flat amount of 95 PHP

• charge 2 - fee due at disbursement, which is 7.5% of the loan amount

Also, we assume the top-up balance of the previous loan to be closed is 3997.38 PHP. This means that the prior loan’s outstanding balance is moved to the newly disbursed loan, thus ensuring that a refinance has taken place.

A. Pre-Approval Event:

Here, the Net Disbursal Amount is calculated with respect to the proposed loan amount for the refinance loan application. In other words:

NDA = Proposed Amount - Charges at Disbursal

Considering the scenario mentioned above and assuming the amount proposed was 10,000 PHP, the net disbursal amount will be calculated as follows:

NDA = 10,000 - (95 + 750) = 9155 PHP

B. Post-Approval Event:

Here, the Net Disbursal Amount is recalculated with respect to the approved loan amount for the loan. This implies that:

NDA = Approved Amount - Charges at Disbursal - Topup Balance

Considering the scenario mentioned above and assuming the amount approved was 9,000 PHP, the net disbursal amount will be calculated as follows:

NDA = 9,000 - (95 + 675) - 3997.38 = 4232.62 PHP

C. Post-Disbursal Event:

Here, the Net Disbursal Amount is recalculated with respect to the disbursed loan amount for the loan. This implies that:

NDA = Disbursed Amount - Charges at Disbursal - Topup Balance

Considering the scenario mentioned above and assuming the amount disbursed was 8,000 PHP, the net disbursal amount will be calculated as follows:

NDA = 8,000 - (95 + 600) - 3997.38 = 3307.62 PHP

D. Reversal of Loan Disbursal:

Once a refinanced loan is disbursed, it cannot currently be reversed. Hence, you will see an error implying that undoing disbursal for a top up loan is not allowed. In this article, I'm not covering how to bypass this.

E. Reversal of Loan Approval:

If a refinanced loan hasn’t yet been disbursed but approved, and you wish to reverse this approval, then it is possible. After undoing the approval action, the Net Disbursal Amount is recalculated with respect to the proposed loan amount. This implies that

NDA = Proposed Amount - Charges at Disbursal - Topup Balance

Considering the scenario mentioned above, the amount offered was 10,000 PHP. The net disbursal amount will be calculated as follows:

NDA = 10,000 - (95 + 750) = 9155 PHP

You can see from the above that the net disbursal amount feature varies for a loan based on whether it’s a regular or refinanced loan and the current event of its lifecycle.

Let’s go a little deep and understand the code changes we needed to make this arithmetic work for us:

1. Methods Affected

• approveApplication in LoanApplicationWritePlatformServiceJpaRepositoryImpl class

• undoApplicationApproval in LoanApplicationWritePlatformServiceJpaRepositoryImpl class

• undoLoanDisbursal in LoanWritePlatformServiceJpaRepositoryImpl class

• fetchDisbursementData in LoanUtilsService

• toData in LoanTransaction class

2. Database Tables

• File Added: V367__loan_net_disbursal_amount.sql

• Tables modified:

  • Added column net_disbursal_amount to table m_loan.

  • Added column net_disbursal_amount to table m_loan_disbursement_detail.

This article is a contribution made through the Learn Fellowship program.