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.
