lending.early-settlement Unreviewed

def early_settlement(advances: Sequence[DatedAmount], repayments: Sequence[DatedAmount], apr_basis_points: int, notice_received_iso: str, requested_settlement_iso: Optional[str], deferral: SettlementDeferral) -> EarlySettlement

@dataclass(frozen=True)
class DatedAmount:
    """An amount on a date."""

    date: str
    #: greater than zero
    amount: Money

SettlementDeferral = Literal["none", "one-month", "thirty-days"]

@dataclass(frozen=True)
class EarlySettlement:
    """The figure to quote and how it was reached."""

    #: the date the rebate is calculated to
    settlement_date: str
    #: what the debtor pays to settle, rounded down to the minor unit
    settlement_amount: Money
    #: the scheduled repayments on or after the settlement date
    remaining_repayments: Money
    #: remainingRepayments minus settlementAmount, never negative
    rebate: Money

from fune.lending.early_settlement import early_settlement  # lending.early-settlement@^1

from typing import Optional, Sequence

from .dates_add_days import add_days  ← from dates.add-days ^1.0.0 · built alongside by fune
from .dates_add_months import add_months  ← from dates.add-months ^1.0.0 · built alongside by fune
from .dates_days_between import days_between  ← from dates.days-between ^1.0.0 · built alongside by fune
from .lending_early_settlement_types import DatedAmount, EarlySettlement, SettlementDeferral
from .math_fractional_power import FIXED_SCALE, pow_fixed, root_fixed  ← from math.fractional-power ^1.0.0 · built alongside by fune
from .money_amount import money  ← from money.amount ^1.0.0 · built alongside by fune


def _settlement_date(
    advances: Sequence[DatedAmount],
    repayments: Sequence[DatedAmount],
    notice_received_iso: str,
    requested_settlement_iso: Optional[str],
    deferral: SettlementDeferral,
) -> str:
    """The settlement date: 28 days after the creditor receives the notice
    (regulation 5(1)(a)), or a later date the notice names, then deferred by a
    month or 30 days where the creditor elects and regulation 6 allows it
    (credit repaid over more than a year from the first drawdown)."""
    date = add_days(notice_received_iso, 28)
    if requested_settlement_iso is not None:
        days_between(requested_settlement_iso, requested_settlement_iso)
        if requested_settlement_iso > date:
            date = requested_settlement_iso
    if deferral == "none":
        return date
    if deferral not in ("one-month", "thirty-days"):
        raise ValueError('unknown deferral "%s": expected none, one-month or thirty-days' % (deferral,))
    first = min(a.date for a in advances)
    last = max(r.date for r in repayments)
    if last <= add_months(first, 12):
        raise ValueError("deferral is only allowed when the credit is repaid over more than a year (regulation 6)")
    return add_months(date, 1) if deferral == "one-month" else add_days(date, 30)


def early_settlement(
    advances: Sequence[DatedAmount],
    repayments: Sequence[DatedAmount],
    apr_basis_points: int,
    notice_received_iso: str,
    requested_settlement_iso: Optional[str],
    deferral: SettlementDeferral,
) -> EarlySettlement:
    """The amount a debtor pays to settle a regulated consumer credit agreement
    early, and the rebate, per the Consumer Credit (Early Settlement)
    Regulations 2004, regulation 4(1).

    The rebate is the scheduled repayments falling due after the settlement
    date less  sum A_i (1 + r)^a_i - sum B_j (1 + r)^b_j  over the advances and
    the repayments made before the settlement date, each carried forward to
    the settlement date at the APR. That difference is the settlement figure.
    Times are days / 365 of a year.
    """
    if len(advances) == 0:
        raise ValueError("advances must not be empty")
    if len(repayments) == 0:
        raise ValueError("repayments must not be empty")
    b = apr_basis_points
    if isinstance(b, bool) or not isinstance(b, int) or b < 0 or b > 1000000:
        raise ValueError("aprBasisPoints must be between 0 and 1000000, received %r" % (b,))
    currency = advances[0].amount.currency
    for flow in list(advances) + list(repayments):
        days_between(flow.date, flow.date)
        if flow.amount.currency != currency:
            raise ValueError("currency mismatch: %s and %s" % (currency, flow.amount.currency))
        if flow.amount.minor <= 0:
            raise ValueError("every amount must be greater than zero, received %r" % (flow.amount.minor,))
    date = _settlement_date(advances, repayments, notice_received_iso, requested_settlement_iso, deferral)
    # (1 + APR)^(1/365), once; each flow is then a whole power of it.
    daily = root_fixed(FIXED_SCALE * (10000 + b) // 10000, 365)

    def carried(flow: DatedAmount) -> int:
        return flow.amount.minor * pow_fixed(daily, days_between(flow.date, date))

    owed = 0
    drawn = False
    for advance in advances:
        if advance.date < date:
            owed += carried(advance)
            drawn = True
    if not drawn:
        raise ValueError("no credit was advanced before the settlement date %s" % (date,))
    remaining = 0
    for repayment in repayments:
        if repayment.date < date:
            owed -= carried(repayment)
        else:
            remaining += repayment.amount.minor
    # Rounded down: the rebate must be at least the one the formula gives.
    formula = owed // FIXED_SCALE if owed > 0 else 0
    settlement = min(formula, remaining)
    return EarlySettlement(
        settlement_date=date,
        settlement_amount=money(settlement, currency),
        remaining_repayments=money(remaining, currency),
        rebate=money(remaining - settlement, currency),
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 6 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add lending.early-settlement

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./lending.early-settlement-1.0.1-python.fune, or fetch it from a terminal with fune pull lending.early-settlement@1.0.1:python.

The whole function, every language, is one file too: lending.early-settlement-1.0.1.fune, 98,562 bytes, sha256 0c7f98fcae78d3b8c877e90e6d3d6858547820c7c16f61b1da4451db3c34e1aa. It installs into a project of any language.

# fune: before lending.early-settlement

# fune: after lending.early-settlement

# fune: replace dates.add-days in lending.early-settlement
# fune: replace dates.add-months in lending.early-settlement
# fune: replace dates.days-between in lending.early-settlement
# fune: replace math.big-integer in lending.early-settlement
# fune: replace math.fractional-power in lending.early-settlement
# fune: replace money.amount in lending.early-settlement

# fune: step lending.early-settlement after <n|label>

More from the author

## The rules it applies

- **Regulation 4(1), the rebate.** The rebate is "the difference between the total amount of the repayments of credit that would fall due for payment after the settlement date if early settlement did not take place and the amount given by the following formula":

Σ A_i (1 + r)^a_i − Σ B_j (1 + r)^b_j

A_i are the advances and B_j the repayments made before the settlement date; a_i and b_j are the times from each to the settlement date; r is "the periodic rate equivalent of the APR". So the formula is the balance outstanding at the settlement date, carried forward at the APR, and that is the settlement figure; the rebate is what it saves against paying the schedule out. - **Regulation 5(1)(a), the settlement date.** 28 days after the creditor receives the debtor's notice under section 94(1) of the Consumer Credit Act 1974, or any later date the notice names. An earlier date in the notice does not shorten the 28 days. - **Regulation 6, deferment.** Where the credit is repaid over a period of more than a year after the relevant date, the creditor may defer the settlement date by one month, or elect 30 days where a month would be more or less than 30 days. `deferral` is that election; asking for it on an agreement of a year or less is an error. A month is a calendar month, clamped at the month end (31 January + 1 month is 28 February), as dates.add-months does.

## How it is computed

Time is measured in days and a year is 365 days, so each amount is carried forward by (1 + APR)^(days / 365). That fractional power is irrational; it is computed in 18-place fixed point with math.fractional-power (the daily factor (1 + APR)^(1/365) once, then a whole power of it per flow), the same floors in the same order in every language, accurate to around 10^-15 of the amount. The formula's result is rounded **down** to the minor unit, because regulation 2(1) requires a rebate "at least equal" to the calculated one, so the debtor is never asked for a fraction of a penny more.

- Repayments dated before the settlement date are treated as made, on their due dates, which is the creditor's election in regulation 4(2); arrears are not modelled, so add any missed instalments to the figure yourself. - Repayments dated on or after the settlement date are the ones settled early; their total is `remainingRepayments`. - The settlement amount never exceeds `remainingRepayments`, and the rebate is never negative.

## What a specialist should check

- **Rate and time basis.** "The periodic rate equivalent of the APR" is read as (1 + APR)^(days/365), using the APR as disclosed (rounded to one decimal place). Some creditors use monthly periods with part-months, or the unrounded APR; the answers differ by pennies. - **Leap years.** 365 days throughout, as in lending.apr. - **A repayment due on the settlement date itself** is treated as settled early (included in `remainingRepayments`, excluded from the formula). The regulations speak of repayments "before" and "after" the settlement date and are silent on the day itself. - **What is in the total charge for credit.** Regulation 3 allows some items (taxes, linked transactions, broker fees attributable to the period before settlement) to be excluded from the rebate; the flows passed in are taken as given. - **Scope.** Regulation 2(2) excludes running-account credit (credit cards, overdrafts) and some land mortgages; partial early settlement (section 94(3), regulation 4A) is not implemented. - **Relevant date.** Regulation 6 measures "more than a year" from the relevant date; this uses the first advance's date as that date.

## Before you rely on this

**Not professional advice.** This capability calculates lending figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a consumer-credit compliance specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified consumer-credit compliance specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files