new over-refunded balance status

Author: simontreanor

CHANGELOG.md

@@ -8,6 +8,17 @@
 
 ---
 
+## [2.5.5] - 2025-06-05
+
+### Fixed
+
+- Reverting some of the changes made in 2.5.2, which sought to eliminate discrepancies caused by small amounts of interest at the end of a schedule.
+The problem was misidentified as being due to interest/principal forgiveness whereas it was actually caused by unusual edge case of having over-refunded
+the customer. A solution has now been implemented by introducing a new balance status `OverRefunded` to describe precisely this scenario and prevent any
+interest being accrued from this point on in a schedule, as the resulting positive balance is not the fault of the customer.
+
+---
+
 ## [2.5.4] - 2025-06-04
 
 ### Fixed

io/out/ActualPayment/ActualPaymentTestExtra008.md

@@ -151,7 +151,7 @@
         <td class="ci07"><i>n/a</i></td>
         <td class="ci08">-2.85</td>
         <td class="ci09"><i>refunded</i></td>
-        <td class="ci10">open</td>
+        <td class="ci10">over-refunded</td>
         <td class="ci11">-0.1335</td>
         <td class="ci12">-0.1335</td>
         <td class="ci13">-0.17</td>
@@ -168,11 +168,11 @@
         <td class="ci04">19</td>
         <td class="ci05">0.00</td>
         <td class="ci06"><i>n/a</i></td>
-        <td class="ci07">0.00</td>
-        <td class="ci08">0.00</td>
+        <td class="ci07">0.02</td>
+        <td class="ci08">0.02</td>
         <td class="ci09"><i>generated</i></td>
         <td class="ci10">closed</td>
-        <td class="ci11">0.0376</td>
+        <td class="ci11">0.0000</td>
         <td class="ci12">0.0000</td>
         <td class="ci13">0.00</td>
         <td class="ci14">0.02</td>
@@ -184,7 +184,7 @@
 <h4>Final Stats</h4>
 <table>
     <tr>
-        <td>Generated settlement: <i>0.00 on day 573</i></td>
+        <td>Generated settlement: <i>0.02 on day 573</i></td>
         <td>Final balance status: <i>closed</i></td>
     </tr>
     <tr>

io/out/ActualPayment/ActualPaymentTestExtra009.md

@@ -131,7 +131,7 @@
         <td class="ci07"><i>n/a</i></td>
         <td class="ci08">-57.05</td>
         <td class="ci09"><i>refunded</i></td>
-        <td class="ci10">open</td>
+        <td class="ci10">over-refunded</td>
         <td class="ci11">-3.1740</td>
         <td class="ci12">-3.1740</td>
         <td class="ci13">-3.18</td>
@@ -148,11 +148,11 @@
         <td class="ci04">21</td>
         <td class="ci05">0.00</td>
         <td class="ci06"><i>n/a</i></td>
-        <td class="ci07">1.92</td>
-        <td class="ci08">1.92</td>
+        <td class="ci07">0.63</td>
+        <td class="ci08">0.63</td>
         <td class="ci09"><i>generated</i></td>
         <td class="ci10">closed</td>
-        <td class="ci11">1.2852</td>
+        <td class="ci11">0.0000</td>
         <td class="ci12">0.0000</td>
         <td class="ci13">0.00</td>
         <td class="ci14">0.63</td>
@@ -164,7 +164,7 @@
 <h4>Final Stats</h4>
 <table>
     <tr>
-        <td>Generated settlement: <i>1.92 on day 643</i></td>
+        <td>Generated settlement: <i>0.63 on day 643</i></td>
         <td>Final balance status: <i>closed</i></td>
     </tr>
     <tr>

io/out/GeneratedDate.html

@@ -1 +1 @@
-<p>Generated: <i>2025-06-05 11:19:01 +01:00</i> using library version: <i>2.5.4</i></p>
+<p>Generated: <i>2025-06-05 14:28:24 +01:00</i> using library version: <i>2.5.4</i></p>

src/Amortisation.fs

@@ -35,13 +35,16 @@ module Amortisation =
         | OpenBalance
         /// due to an overpayment or a refund of charges, a refund is due
         | RefundDue
+        /// a refund was made but this left a positive principal balance, meaning the customer has been over-refunded
+        | OverRefunded
 
         /// HTML formatting to display the balance status in a readable format
         member bs.Html =
             match bs with
             | ClosedBalance -> "closed"
             | OpenBalance -> "open"
             | RefundDue -> "refund due"
+            | OverRefunded -> "over-refunded"
 
     /// a breakdown of how an actual payment is apportioned to principal, fee, interest and charges
     type Apportionment = {
@@ -430,10 +433,15 @@ module Amortisation =
             decimal feeTotal / decimal principal |> Percent.fromDecimal
 
     /// gets the balance status based on the principal balance
-    let getBalanceStatus principalBalance =
-        if principalBalance = 0L<Cent> then ClosedBalance
-        elif principalBalance < 0L<Cent> then RefundDue
-        else OpenBalance
+    let getBalanceStatus principalBalance previousBalanceStatus =
+        if principalBalance = 0L<Cent> then
+            ClosedBalance
+        elif principalBalance < 0L<Cent> then
+            RefundDue
+        elif principalBalance > 0L<Cent> && previousBalanceStatus = RefundDue then
+            OverRefunded
+        else
+            OpenBalance
 
     /// determines whether a schedule is settled within any grace period (e.g. no interest may be due if settlement is made within three days of the advance)
     let isSettledWithinGracePeriod (p: Parameters) =
@@ -500,8 +508,8 @@ module Amortisation =
 
     /// determines any payment due on the day
     let calculatePaymentDue si originalPayment rescheduledPayment extraPaymentsBalance interestPortionL minimumPayment =
-        // if the balance is closed or a refund is due, no payment is due
-        if si.BalanceStatus = ClosedBalance || si.BalanceStatus = RefundDue then
+        // if the balance is not open, no payment is due
+        if si.BalanceStatus <> OpenBalance then
             0L<Cent>
         // otherwise, calculate the payment due based on scheduled payments and various balances
         else
@@ -606,7 +614,9 @@ module Amortisation =
         =
         let dailyInterestRates = getDailyInterestRates p previousDay currentDay
 
-        if previous.PrincipalBalance <= 0L<Cent> then
+        if previous.BalanceStatus = OverRefunded then
+            0m<Cent>
+        elif previous.PrincipalBalance <= 0L<Cent> then
             dailyInterestRates
             |> Array.map (fun dr -> {
                 dr with
@@ -629,10 +639,11 @@ module Amortisation =
         initialInterestBalanceM
         actuarialInterestM //this can be higher than the capped actuarial interest because it can include an adjustment that sucks in all the lost interest from rounding
         =
-        match interestMethod with
-        | Interest.Method.Actuarial -> actuarialInterestM
-        | Interest.Method.AddOn when previousBalanceStatus = ClosedBalance -> 0m<Cent>
-        | Interest.Method.AddOn ->
+        match previousBalanceStatus, interestMethod with
+        | _, Interest.Method.Actuarial -> actuarialInterestM
+        | ClosedBalance, _
+        | OverRefunded, _ -> 0m<Cent>
+        | _ ->
             cumulativeActuarialInterestM + cappedActuarialInterestM
             |> fun i ->
                 if i > initialInterestBalanceM then
@@ -642,20 +653,16 @@ module Amortisation =
             |> min cappedActuarialInterestM
 
     /// ignores small amounts of interest that have accumulated by the last day of the schedule, with the allowance being proportional to the length of the schedule
-    let calculateFinalInterestReduction currentDay maxAppliedPaymentDay appliedPaymentCount interestM =
-        if currentDay = maxAppliedPaymentDay then
-            let valueMinusForgiven =
-                Interest.ignoreFractionalCents appliedPaymentCount interestM
-
-            {|
-                Reduction = interestM - valueMinusForgiven |> max 0m<Cent>
-                InterestForgiven = valueMinusForgiven = 0m<Cent>
-            |}
+    let calculateFinalInterestReduction
+        (currentDay: int<OffsetDay>)
+        maxAppliedPaymentDay
+        appliedPaymentCount
+        interestM
+        =
+        if interestM > 0m<Cent> && currentDay = maxAppliedPaymentDay then
+            interestM - Interest.ignoreFractionalCents appliedPaymentCount interestM
         else
-            {|
-                Reduction = 0m<Cent>
-                InterestForgiven = false
-            |}
+            0m<Cent>
 
     /// calculates any new interest accrued since the previous item, according to the interest method supplied in the schedule parameters
     let calculateInterestAdjustment
@@ -666,14 +673,13 @@ module Amortisation =
         cumulativeActuarialInterestM
         initialInterestBalanceM
         (basicParameters: BasicParameters)
-        interestForgiven
         =
         match basicParameters.InterestConfig.Method with
-        | Interest.Method.AddOn when interestForgiven -> 0m<Cent>
         | Interest.Method.AddOn when
             previousBalanceStatus <> ClosedBalance
             && (currentGeneratedPayment = ToBeGenerated || settlement <= 0L<Cent>)
             && previousBalanceStatus <> RefundDue
+            && previousBalanceStatus <> OverRefunded
             && cappedNewInterestM = 0m<Cent>  // cappedNewInterest check here avoids adding an interest adjustment twice (one for generated payment, one for final payment)
             ->
             cumulativeActuarialInterestM - initialInterestBalanceM
@@ -855,18 +861,18 @@ module Amortisation =
                     initialInterestBalanceM
                     actuarialInterestM
 
-            let cappedNewInterestM, finalInterestReductionM, interestForgiven =
+            let cappedNewInterestM, finalInterestReductionM =
                 let cni =
                     Interest.Cap.cappedAddedValue
                         p.Basic.InterestConfig.Cap.TotalAmount
                         p.Basic.Principal
                         totals.CumulativeInterest
                         newInterestM
 
-                let sr =
+                let fir =
                     calculateFinalInterestReduction currentDay maxAppliedPaymentDay appliedPaymentCount cni
 
-                cni - sr.Reduction, sr.Reduction, sr.InterestForgiven
+                cni - fir, fir
 
             let finalInterestReductionL =
                 finalInterestReductionM |> Cent.fromDecimalCent interestRounding
@@ -951,7 +957,6 @@ module Amortisation =
                     totals'.CumulativeActuarialInterestM
                     initialInterestBalanceM
                     p.Basic
-                    interestForgiven
 
             // refine the capped new interest value using any interest adjustment
             let cappedNewInterestM' = cappedNewInterestM + interestAdjustmentM
@@ -1060,7 +1065,7 @@ module Amortisation =
             let offsetDate = p.Basic.StartDate.AddDays(int currentDay)
 
             // determine the principal balance
-            let balanceStatus = getBalanceStatus principalBalance'
+            let balanceStatus = getBalanceStatus principalBalance' previous.BalanceStatus
 
             // calculate the interest balance as a decimal
             let interestBalanceM =
@@ -1074,17 +1079,15 @@ module Amortisation =
             let createScheduleItem isSettlement =
                 // refine the payment status based on the balance status and whether this is a settlement
                 let paymentStatus =
-                    match previous.BalanceStatus, isSettlement with
-                    | ClosedBalance, _ when current.PaymentStatus.IsInformationOnly -> InformationOnly
-                    | ClosedBalance, _ -> NoLongerRequired
-                    | _, true -> Generated
-                    | RefundDue, _ when netEffect' < 0L<Cent> -> Refunded
-                    | RefundDue, _ when netEffect' > 0L<Cent> -> Overpayment
-                    | RefundDue, _ when current.PaymentStatus.IsInformationOnly -> InformationOnly
-                    | RefundDue, _ -> NoLongerRequired
+                    match current.PaymentStatus, previous.BalanceStatus, isSettlement with
+                    | InformationOnly, _, _ -> InformationOnly
+                    | _, ClosedBalance, _ -> NoLongerRequired
+                    | _, _, true -> Generated
+                    | _, RefundDue, _ when netEffect' < 0L<Cent> -> Refunded
+                    | _, RefundDue, _ when netEffect' > 0L<Cent> -> Overpayment
+                    | _, RefundDue, _ -> NoLongerRequired
                     | _ when
-                        current.PaymentStatus <> InformationOnly
-                        && paymentDue' = 0L<Cent>
+                        paymentDue' = 0L<Cent>
                         && madePaymentTotal = 0L<Cent>
                         && pendingPaymentTotal = 0L<Cent>
                         && GeneratedPayment.total current.GeneratedPayment = 0L<Cent>
@@ -1094,10 +1097,16 @@ module Amortisation =
 
                 // refine the settlement figure if necessary by subtracting any payment made on the same day, or nullifying it if there are payments pending (settlement cannot be made in this case)
                 let settlementFigure =
-                    match pendingPaymentTotal, current.PaymentStatus, p.Basic.InterestConfig.Method with
-                    | pp, _, _ when pp > 0L<Cent> -> 0L<Cent>
-                    | _, NotYetDue, _
-                    | _, _, Interest.Method.AddOn -> generatedSettlementPayment'
+                    match
+                        previous.BalanceStatus,
+                        pendingPaymentTotal,
+                        current.PaymentStatus,
+                        p.Basic.InterestConfig.Method
+                    with
+                    | OverRefunded, _, _, _ -> previous.PrincipalBalance
+                    | _, pp, _, _ when pp > 0L<Cent> -> 0L<Cent>
+                    | _, _, NotYetDue, _
+                    | _, _, _, Interest.Method.AddOn -> generatedSettlementPayment'
                     | _ -> generatedSettlementPayment' - netEffect'
 
                 // deteremine the settlement balances or carried balances
@@ -1336,7 +1345,7 @@ module Amortisation =
             |> applyPayments p actualPayments
             |> calculate p basicSchedule.Stats
             |> if p.Advanced.TrimEnd then
-                   Map.filter (fun _ si -> si.PaymentStatus <> NoLongerRequired || si.BalanceStatus = RefundDue)
+                   Map.filter (fun _ si -> si.PaymentStatus <> NoLongerRequired)
                else
                    id
             |> calculateStats

tests/ActualPaymentTestsExtra.fs

@@ -775,11 +775,11 @@ module ActualPaymentTestsExtra =
                 Window = 19
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
-                GeneratedPayment = GeneratedValue 0L<Cent>
-                NetEffect = 0L<Cent>
+                GeneratedPayment = GeneratedValue 2L<Cent>
+                NetEffect = 2L<Cent>
                 PaymentStatus = Generated
                 BalanceStatus = ClosedBalance
-                ActuarialInterest = 3.76m<Cent>
+                ActuarialInterest = 0m<Cent>
                 NewInterest = 0m<Cent>
                 NewCharges = [||]
                 PrincipalPortion = 2L<Cent>
@@ -867,7 +867,7 @@ module ActualPaymentTestsExtra =
             schedules.AmortisationSchedule.ScheduleItems |> Map.maxKeyValue
 
         let expected =
-            573<OffsetDay>,
+            643<OffsetDay>,
             {
                 OffsetDayType = OffsetDayType.SettlementDay
                 OffsetDate = Date(2025, 6, 2)
@@ -876,16 +876,16 @@ module ActualPaymentTestsExtra =
                 Window = 21
                 PaymentDue = 0L<Cent>
                 ActualPayments = [||]
-                GeneratedPayment = GeneratedValue 1_91L<Cent>
-                NetEffect = 1_91L<Cent>
+                GeneratedPayment = GeneratedValue 63L<Cent>
+                NetEffect = 63L<Cent>
                 PaymentStatus = Generated
                 BalanceStatus = ClosedBalance
-                ActuarialInterest = 1_28.52m<Cent>
-                NewInterest = 1_28m<Cent>
+                ActuarialInterest = 0m<Cent>
+                NewInterest = 0m<Cent>
                 NewCharges = [||]
                 PrincipalPortion = 63L<Cent>
                 FeePortion = 0L<Cent>
-                InterestPortion = 1_28L<Cent>
+                InterestPortion = 0L<Cent>
                 ChargesPortion = 0L<Cent>
                 FeeRebate = 0L<Cent>
                 PrincipalBalance = 0L<Cent>