Hi Fineract community,
We are working with Apache Fineract 1.15.0 and would appreciate guidance on
implementing a configurable loan-level cap on the combined amount of ordinary
interest, penalties, and fees.
The business requirements are as follows:
1.
Configurable activation point
The cap should become effective at a configurable business event, such as when
a loan becomes overdue or enters non-performing loan (NPL) status.
2.
Calculation of the cap
At activation, the cap should be calculated as:
Cap = total overdue outstanding principal × configured percentage
Principal belonging to installments that are not yet overdue should be excluded
from this calculation. Principal repayment obligations remain separate from the
interest-and-fee cap.
3.
Amounts included at activation
Interest, penalties, and fees already incurred but unpaid at activation should
count toward the cap. Amounts paid before activation and future interest that
has not yet been incurred should be excluded.
For example, with overdue outstanding principal of 1,000, a cap percentage of
100%, unpaid interest of 100, and unpaid penalties of 200:
*
The cap is 1,000.
*
The initial amount counted toward the cap is 300.
*
The remaining capacity is 700.
4.
Effect of repayments and waivers
Repaying principal should not immediately reduce the previously established cap.
Repaying interest, penalties, or fees within the cap’s scope should not release
capacity: both amounts already collected and amounts still outstanding count
toward the cap.
A business waiver of those amounts should release capacity for subsequently
incurred interest, penalties, or fees, while leaving the cap itself unchanged.
5.
Multiple overdue installments
When another installment becomes overdue, the cap should be recalculated using
the total overdue outstanding principal at that time. The new cap replaces the
previous cap, while the accumulated usage is retained.
For example, if the first overdue installment has principal of 2,000, the cap
at 100% is 2,000. After a principal repayment of 500, that cap remains
unchanged. If a second installment with principal of 2,000 subsequently becomes
overdue, the new cap becomes 3,500.
6.
Acceptable treatment of daily penalties
We can accept waiving the entire group of newly generated, unpaid penalties for
a loan on a given business date if retaining that group would exceed the cap.
For example, if the cap is 1,000, existing usage is 980, and the day’s
penalties total 50, waiving the full 50 and leaving usage at 980 is acceptable.
This tolerance applies specifically to daily penalties; the treatment of
partially excess ordinary fees is still being finalized.
Could you advise on the recommended design and development approach for these
requirements?
In particular:
*
Are there existing features or configurations that could support this behavior?
*
Which extension points would you recommend, and where might changes to the core
implementation be necessary?
*
What should we consider to keep repayments, waivers, reversals, backdated
transactions, and batch reruns consistent?
*
Are there related implementations, Jira issues, or design discussions we could
refer to?
We would also welcome guidance on edge cases such as an initial balance already
exceeding the cap, a recalculated cap falling below accumulated usage, or a
loan becoming overdue again after recovery.
Thank you for your advice.