Hi Adam,
Thank you for your detailed reply. This requirement comes from regulatory 
limits on loan interest and related charges that apply to our project. Once a 
loan becomes delinquent or is classified as a non-performing loan (NPL), we 
want to apply a loan-level cap to the combined amount of covered ordinary 
interest, penalties, and fees. The cap prevents those amounts from accumulating 
beyond the applicable limit. The obligation to repay principal is separate from 
the cap.
In light of your feedback, we reviewed the rules in our initial email against 
the regulatory requirements. Our current understanding is as follows.
1. Calculating the cap and applying it within a cap period
The cap amount is calculated by multiplying the applicable principal balance at 
the time of activation by a configured percentage:

  *   Single-installment loans: Use the overdue outstanding principal at 
activation.
  *   Multi-installment loans: Use the total outstanding principal of the loan 
at activation, including principal on future installments that have not yet 
been billed or fallen due.

For multi-installment loans, this replaces the approach in our initial email, 
which used only the outstanding principal on overdue installments.
The cap stays fixed throughout a continuous period of delinquency. Principal 
repayments do not lower it, and additional installments becoming overdue do not 
trigger a recalculation.
Under this revised rule, an additional installment becoming overdue would 
therefore not cause the scenario you described, where a recalculated cap falls 
below cumulative usage after a principal repayment.
One question remains open: if eligible unpaid amounts already exceed the cap at 
initial activation, should the system only stop adding new charges, or should 
it also reduce existing unpaid amounts?
2. Return to performing status and subsequent delinquency
When the borrower pays all amounts due and the loan returns to performing 
status, the current cap period ends. If the loan becomes delinquent again, a 
new cap period begins, and the cap is recalculated using the applicable 
principal balance at that time.
As long as no principal is added and the cap percentage stays the same, the cap 
for a subsequent period can only stay the same or decrease.
On your question about whether usage carries forward, our current proposal is:

  *   Track cumulative usage and repayments separately for each cap period.
  *   Do not carry cumulative usage or repayments directly from one period into 
the next.
  *   Initialize usage for the new period with eligible amounts that have 
already been incurred and remain unpaid at activation. Amounts paid before 
activation do not count toward the new period.
  *   Retain the complete record of each previous period for audit and 
traceability.

The proposal therefore applies a cap per cap period, rather than a single 
lifetime cap on all charges for the loan.
3. Tracking one cap amount and two buckets per period
To distinguish cumulative usage from the current unpaid balance, we plan to 
track three values:
Item
Definition
Cap Amount
The maximum combined amount of covered non-principal items for the current 
period.
Total Receivable Bucket
The cumulative amount of covered items counted in the current period, net of 
applicable waivers and including amounts already repaid. This represents 
cumulative usage for the period.
Repaid Amount Bucket
The portion of the Total Receivable Bucket that the borrower has already paid.
Both buckets exclude principal. Once the cap is enforced, the expected 
relationships are:

  *   Total Receivable Bucket ≤ Cap Amount
  *   Outstanding Amount = Total Receivable Bucket − Repaid Amount Bucket

Here, Total Receivable Bucket means the cumulative net amount counted toward 
the cap. It includes amounts already paid, so it differs from the current 
unpaid balance.
4. Repayments, waivers, and reaching the cap
When the borrower pays covered interest, penalties, or fees, the Total 
Receivable Bucket stays unchanged and the Repaid Amount Bucket increases. 
Repayment changes the split between paid and unpaid amounts without reducing 
cumulative usage or freeing up capacity for new charges.
When an eligible unpaid amount is waived, the Total Receivable Bucket decreases 
and the Repaid Amount Bucket stays unchanged. Under the proposed rule, new 
charges can use the capacity freed up by a waiver.
5. When interest counts toward the cap and how same-day items are ordered
Your question about the definition of incurred interest is particularly 
helpful. In this proposal, incurred interest means interest that has fallen due 
and is payable.
6. Three-installment loan examples
Assume a loan is repayable in three installments, each with 1,000 in principal 
and 200 in interest. The cap percentage is 100%. For these examples only, 
assume that each installment’s interest is added to the Total Receivable Bucket 
once it is billed.
Example 1: The first installment becomes overdue before the next two are billed
When the first installment’s principal of 1,000 becomes overdue, the total 
outstanding principal is still 3,000. The cap for this period is therefore 
3,000.
The Total Receivable Bucket starts at 200, representing the first installment’s 
interest, and the Repaid Amount Bucket starts at zero. Interest on subsequent 
installments is added when billed, provided the current cap period is still 
active and there is sufficient capacity.
Example 2: Repayment, waiver, and reaching the cap
Assume the loan remains delinquent, the cap is 3,000, and the Total Receivable 
Bucket has reached 500.
Action
Total Receivable Bucket
Repaid Amount Bucket
Outstanding Amount
No payment yet
500
0
500
Borrower pays 100 toward interest, penalties, or fees
500
100
400
Lender then waives 50 in unpaid penalties
450
100
350
If the Total Receivable Bucket later reaches 3,000, the cap has been reached. 
If the borrower has paid 1,000 by then, 2,000 remains outstanding. Further 
repayments increase only the Repaid Amount Bucket. The Total Receivable Bucket 
stays at 3,000, so those repayments do not allow additional covered charges.
Example 3: The loan returns to performing status and later becomes delinquent 
again
Assume the borrower pays all amounts due for each overdue installment before 
the next installment falls due, bringing the loan back to performing status 
each time.
Scenario
Total outstanding principal
Cap treatment
First installment becomes overdue
3,000
Start the first period with a cap of 3,000
Borrower pays all principal, interest, penalties, and fees due on the first 
installment; the loan returns to performing status
2,000
End the first period
Second installment becomes overdue
2,000
Start the second period with a cap of 2,000
Borrower pays all amounts due on the second installment; the loan returns to 
performing status
1,000
End the second period
Third installment becomes overdue
1,000
Start the third period with a cap of 1,000
The caps for the three periods are 3,000, 2,000, and 1,000, respectively. The 
amounts in each bucket are tracked separately for each period, and historical 
records are retained.
We plan to implement these rules in a customization of Apache Fineract 1.15.0 
and would appreciate your advice on the following:

  1.  Can Fineract’s existing extension mechanisms support this kind of 
loan-level cap? Are there suitable extension points or recommended approaches 
for implementing it in a custom module?
  2.  Across interest calculation, charge application, repayments, waivers, and 
transaction reprocessing, which parts could be implemented through extensions, 
and which might require changes to the core implementation?
  3.  Are there any interfaces, classes, examples, related implementations, or 
design discussions applicable to 1.15.0 that we could refer to?

We’ll continue refining the policy details that are still open, and we’d 
welcome your feedback on any gaps or inconsistencies in the current rules.
Thank you again for your help.


________________________________
发件人: Ádám Sághy <[email protected]>
发送时间: 2026年11月9日 17:13
收件人: [email protected] <[email protected]>
抄送: [email protected] <[email protected]>
主题: Re: [Design advice] Configurable cap on loan interest, penalties and fees 
in Fineract 1.15.0


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:

  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