insurance.instalment-plan Unreviewed

export function instalmentPlan(premium: Money, deposit: Money, instalmentCount: number, creditChargeBasisPoints: number, firstInstalmentMonth: number): InstalmentPlan

/** The deposit, what is financed, what it costs and how it is repaid. */
export interface InstalmentPlan {
  readonly deposit: Money;
  /** premium minus deposit */
  readonly amountFinanced: Money;
  /** amountFinanced times the flat rate, rounded half-up */
  readonly creditCharge: Money;
  /** monthly, in order; the first carries any odd pennies */
  readonly instalments: readonly Money[];
  /** deposit plus every instalment */
  readonly totalPayable: Money;
  /** the APR of the credit, by the FCA's total charge for credit rules */
  readonly apr: AprResult;
}

import { instalmentPlan } from "#fune/insurance.instalment-plan@^1";

import { apr } from "./lending_apr.ts";  ← from lending.apr ^1.0.0 · built alongside by fune
import { type CreditFlow } from "./lending_apr_types.ts";
import { type Money, assertSameCurrency, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { applyRate } from "./money_apply_rate.ts";  ← from money.apply-rate ^1.0.0 · built alongside by fune
import { type InstalmentPlan } from "./insurance_instalment_plan_types.ts";

/**
 * A premium paid by monthly instalments.
 *
 * The credit charge is a flat percentage of the amount financed (premium less
 * deposit), the way UK insurers quote it. The instalments are the amount
 * financed plus the charge, split so every penny is accounted for: equal
 * instalments rounded down, with the odd pennies on the first. The APR is
 * then worked from those exact cash flows by lending.apr, because a flat
 * 10% repaid over ten months costs far more than 10% a year.
 */
export function instalmentPlan(
  premium: Money,
  deposit: Money,
  instalmentCount: number,
  creditChargeBasisPoints: number,
  firstInstalmentMonth: number
): InstalmentPlan {
  assertSameCurrency(premium, deposit);
  if (!Number.isInteger(instalmentCount) || instalmentCount < 1) {
    throw new RangeError(`instalmentCount must be a whole number of 1 or more, received ${instalmentCount}`);
  }
  if (!Number.isInteger(creditChargeBasisPoints) || creditChargeBasisPoints < 0) {
    throw new RangeError(`creditChargeBasisPoints must be a whole number of 0 or more, received ${creditChargeBasisPoints}`);
  }
  if (!Number.isInteger(firstInstalmentMonth) || firstInstalmentMonth < 0) {
    throw new RangeError(`firstInstalmentMonth must be a whole number of 0 or more, received ${firstInstalmentMonth}`);
  }
  if (deposit.minor < 0) {
    throw new RangeError(`deposit must not be negative, received ${deposit.minor}`);
  }
  if (deposit.minor >= premium.minor) {
    throw new RangeError("the deposit leaves nothing to pay by instalments");
  }
  if (instalmentCount === 1 && firstInstalmentMonth === 0) {
    throw new RangeError("a single instalment at inception is payment in full, not credit");
  }
  const c = premium.currency;
  const financed = money(premium.minor - deposit.minor, c);
  const charge = applyRate(financed, creditChargeBasisPoints, "half-up");
  const repayable = financed.minor + charge.minor;
  const each = Math.floor(repayable / instalmentCount);
  if (each < 1) {
    throw new RangeError("each instalment must be at least one minor unit");
  }
  const first = repayable - each * (instalmentCount - 1);
  const instalments: Money[] = [];
  const repayments: CreditFlow[] = [];
  for (let i = 0; i < instalmentCount; i++) {
    const amount = money(i === 0 ? first : each, c);
    instalments.push(amount);
    repayments.push({ period: firstInstalmentMonth + i, amount });
  }
  return {
    deposit,
    amountFinanced: financed,
    creditCharge: charge,
    instalments,
    totalPayable: money(deposit.minor + repayable, c),
    apr: apr([{ period: 0, amount: financed }], repayments, 12),
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript 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 insurance.instalment-plan

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./insurance.instalment-plan-1.0.1-typescript.fune, or fetch it from a terminal with fune pull insurance.instalment-plan@1.0.1:typescript.

The whole function, every language, is one file too: insurance.instalment-plan-1.0.1.fune, 27,422 bytes, sha256 73ebf4fcf9f102c86ff18e2e44f3495f7f985cc4dd9631f7b89d73928641c6d3. It installs into a project of any language.

// fune: before insurance.instalment-plan

// fune: after insurance.instalment-plan

// fune: replace lending.apr in insurance.instalment-plan
// fune: replace money.amount in insurance.instalment-plan
// fune: replace money.apply-rate in insurance.instalment-plan

// fune: step insurance.instalment-plan after <n|label>

More from the author

UK insurers price monthly payment as a **flat charge** on the amount financed ("pay monthly: 9.9% charge"), so that is what the function takes:

amountFinanced = premium - deposit creditCharge = amountFinanced x creditChargeBasisPoints / 10000, half-up instalments = (amountFinanced + creditCharge) over instalmentCount months

A flat rate is not an annual rate, and consumer credit must be disclosed with its **APR**, so the plan also carries the APR worked from the exact cash flows by `lending.apr` (FCA CONC App 1.2.6R): the amount financed advanced at month 0, each instalment at its month, a year of 12 months. A flat 10% repaid over ten months is an APR of 23.5%, because on average only about half the money is borrowed for the whole time. The function does not go the other way (take an APR and derive the charge): the insurer sets the flat charge, and the APR is the disclosure measure computed from it. To price to a target APR, try charges and compare.

The deposit is paid at the start and is not credit, so it is left out of the APR. Only the charge for paying by instalments is in it; any other fee paid up front would be a repayment at month 0 and belongs in a call to `lending.apr` directly.

## Instalments to the penny

Every instalment is the repayable total divided by the count, rounded down, and the pennies left over go on the **first** instalment, so the schedule adds up exactly: 100.00 over three is 33.34, 33.33, 33.33. `firstInstalmentMonth` says when the first is taken: 0 at inception (common with no deposit), 1 a month later. A single instalment at inception is not credit and is refused.

## Notes

- `premium` should include IPT: IPT is charged on the premium, and the instalment charge for paying an insurer by instalments is itself part of the taxable premium (HMRC IPT03400). Where the finance is arranged by a third-party premium finance company it is not; apply `insurance.ipt` to suit. - Whether an instalment agreement is regulated credit (and so needs the APR disclosed) depends on how it is arranged; see the FCA's CONC and PERG 2.

## Before you rely on this

**Not professional advice.** This capability calculates insurance 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 an actuary 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 actuary 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