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.

Reply via email to