Hi

This sounds like an interesting borrower-protection feature. In particular, 
counting both collected and outstanding amounts makes sense: otherwise, 
repayments would repeatedly reopen capacity and allow cumulative charges to 
grow indefinitely.



Before choosing the implementation approach, I would clarify a few policy 
questions:



Can recalculation reduce the cap? 

Suppose overdue principal of 2,000 establishes a cap of 2,000. After principal 
repayments of 1,900, another installment with principal of 500 becomes overdue. 
The replacement cap would be 600. If accumulated usage is already 1,200, should 
the system only stop new charges, or also reduce existing unpaid amounts?

What happens after recovery and renewed default?

Does a new default start a fresh cap period, or does previous usage carry 
forward? This substantially affects the protection provided.

Should all business waivers restore capacity?

Waiving 200 and subsequently charging another 200 may be intentional, but it 
means forgiveness can be replaced by new costs. Business waivers, corrections, 
and automatic cap-enforcement adjustments should have distinct treatment.

What exactly does “incurred interest” mean?

Earned interest, interest already due, and accounting accruals may differ. 
Scheduled future interest should not accidentally consume capacity.

Which charges consume capacity first? 

When ordinary interest, fees, and penalties arise on the same date, processing 
order could change the outcome.



From a design perspective, I would treat this as a loan-level policy with an 
auditable history, rather than derive it solely from current outstanding 
balances. That history would record activation, principal snapshots, cap 
changes, included amounts, and qualifying waivers. Repayments would change the 
collected/outstanding split without reducing usage.



The policy would need to participate in interest calculation, charge 
application, and transaction reprocessing. A COB-only adjustment could leave 
gaps around manual charges and repayments between batch runs. Backdated 
transactions and reversals should reproduce the same result through 
deterministic replay, while batch reruns must not duplicate charges or waivers.



I have not confirmed an out-of-the-box configuration in Fineract 1.15.0 that 
covers these combined requirements. Existing charge and waiver functionality 
may provide building blocks, but the cumulative usage and lifecycle rules 
appear to require additional development.



Is this intended to implement a particular regulatory requirement or a 
voluntary product policy? That would help determine whether the 
overdue-principal basis, recalculation rules, and waiver treatment are 
appropriate before committing to the implementation.



Regards,

Adam S

Sent from my iPhone


> On 9 Nov 2026, at 03:42, bee ylong <[email protected]> wrote:
> 
> 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:
> 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.
> 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.
> 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.
> 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.
> 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.
> 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