payroll.minimum-wage-check Unreviewed

def minimum_wage_check(pay: Money, minutes_worked: int, birth_date: str, period_start: str, apprenticeship_start: Optional[str]) -> MinimumWageCheck

WageBand = Literal["national-living-wage", "age-21-to-22", "age-18-to-20", "under-18", "apprentice"]

@dataclass(frozen=True)
class MinimumWageCheck:
    """The rate that applied and whether the pay meets it."""

    band: WageBand
    hourly_rate: Money
    #: hourlyRate x minutes / 60, rounded up to the penny
    required: Money
    #: what is owed; 0 when compliant
    shortfall: Money
    compliant: bool

from fune.payroll.minimum_wage_check import minimum_wage_check  # payroll.minimum-wage-check@^1

from typing import List, Optional

from .dates_add_months import add_months  ← from dates.add-months ^1.0.0 · built alongside by fune
from .dates_age import age  ← from dates.age ^1.0.0 · built alongside by fune
from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune
from .payroll_minimum_wage_check_data import NMW_RATES, NMW_RATES_HISTORY, NmwRate  ← this capability’s own data, compiled from data/rates.json into the same file by fune build
from .payroll_minimum_wage_check_types import MinimumWageCheck


def _rates_in_force(period_start: str) -> List[NmwRate]:
    rows = [r for r in NMW_RATES if period_start >= r.valid_from and (r.valid_to is None or period_start <= r.valid_to)]
    if rows:
        return rows
    if NMW_RATES_HISTORY != "full":
        earliest = min((r.valid_from for r in NMW_RATES), default=None)
        if earliest is not None and period_start < earliest:
            raise ValueError(
                "no minimum wage rate for %s: this build was installed with history=%s, "
                "so it only carries rates from %s. Reinstall with history=full to check older pay."
                % (period_start, NMW_RATES_HISTORY, earliest)
            )
    raise ValueError("no minimum wage rate for %s" % (period_start,))


def minimum_wage_check(
    pay: Money,
    minutes_worked: int,
    birth_date: str,
    period_start: str,
    apprenticeship_start: Optional[str],
) -> MinimumWageCheck:
    """Minimum wage check for one pay reference period. The rate and the age
    are both taken on the first day of the period, never on the pay date.
    """
    if pay.currency != "GBP":
        raise ValueError("the minimum wage is in GBP, received %s" % (pay.currency,))
    if isinstance(minutes_worked, bool) or not isinstance(minutes_worked, int) or minutes_worked < 0:
        raise ValueError("minutesWorked must be a whole number of minutes, not negative, received %s" % (minutes_worked,))
    years = age(birth_date, period_start)
    if years < 16:
        raise ValueError("a worker aged %d is below school leaving age: no minimum wage applies" % (years,))
    if apprenticeship_start is not None and apprenticeship_start > period_start:
        raise ValueError("apprenticeshipStart %s is after periodStart %s" % (apprenticeship_start, period_start))
    rows = _rates_in_force(period_start)
    apprentice_rate = apprenticeship_start is not None and (
        years < 19 or period_start < add_months(apprenticeship_start, 12)
    )
    chosen: Optional[NmwRate] = None
    for row in rows:
        if apprentice_rate:
            if row.band == "apprentice":
                chosen = row
        elif row.band != "apprentice" and row.min_age <= years and (chosen is None or row.min_age > chosen.min_age):
            chosen = row
    if chosen is None:
        raise ValueError("no minimum wage rate for %s" % (period_start,))
    required = round_div(chosen.rate_minor * minutes_worked, 60, "up")
    shortfall = max(0, required - pay.minor)
    return MinimumWageCheck(
        band=chosen.band,  # type: ignore[arg-type]
        hourly_rate=money(chosen.rate_minor, "GBP"),
        required=money(required, "GBP"),
        shortfall=money(shortfall, "GBP"),
        compliant=shortfall == 0,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 4 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 payroll.minimum-wage-check

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

The whole function, every language, is one file too: payroll.minimum-wage-check-1.0.1.fune, 29,454 bytes, sha256 fc3c52f01a77aa82e360aff88540ad9814e2f3bdffcb2d9b283ef1710c867cc4. It installs into a project of any language.

# fune: before payroll.minimum-wage-check

# fune: after payroll.minimum-wage-check

# fune: replace dates.add-months in payroll.minimum-wage-check
# fune: replace dates.age in payroll.minimum-wage-check
# fune: replace math.round-div in payroll.minimum-wage-check
# fune: replace money.amount in payroll.minimum-wage-check

# fune: step payroll.minimum-wage-check after <n|label>

More from the author

**Apprentice rate** (NMW Regulations 2015 reg 5): applies to an apprentice who is under 19, or who is in the first 12 months of the apprenticeship. Pass `apprenticeshipStart` for apprentices, null otherwise. When the apprentice rate applies, the age rates do not (reg 4A(2)).

**Required pay** is `rate x minutes / 60` rounded **up** to the penny: pay in whole pence meets the exact requirement only if it reaches that figure.

Age bands: 2023-24 had the National Living Wage from 23 and a separate 21-22 rate; from 1 April 2024 the National Living Wage starts at 21. A worker under 16 (below school leaving age in this simplification) is an error; the precise school-leaving date differs across the UK and is the caller's to apply.

Not covered: what counts as pay or working time (salaried hours, sleep-ins, the accommodation offset, deductions that reduce pay for minimum wage purposes). Callers supply both numbers already adjusted.

Rates (per hour, from 1 April):

| Year | NLW | 21-22 | 18-20 | Under 18 | Apprentice | |---|---|---|---|---|---| | 2023 | £10.42 (23+) | £10.18 | £7.49 | £5.28 | £5.28 | | 2024 | £11.44 (21+) | - | £8.60 | £6.40 | £6.40 | | 2025 | £12.21 | - | £10.00 | £7.55 | £7.55 | | 2026 | £12.71 | - | £10.85 | £8.00 | £8.00 |

Sources: - GOV.UK, "National Minimum Wage and National Living Wage rates", https://www.gov.uk/national-minimum-wage-rates (current and previous rates) - GOV.UK, "Calculating the minimum wage: pay counted during a pay reference period", https://www.gov.uk/guidance/calculating-the-minimum-wage/calculating-the-minimum-wage - The National Minimum Wage Regulations 2015 (SI 2015/621) regs 4, 4A, 5, 6, https://www.legislation.gov.uk/uksi/2015/621 - The National Minimum Wage (Amendment) Regulations 2026 (SI 2026/357), https://www.legislation.gov.uk/uksi/2026/357/made - GOV.UK, "Rates and thresholds for employers" 2023-24 to 2026-27, https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027

## Before you rely on this

**Not professional advice.** This capability calculates payroll figures from published rules. It is a software component for developers, not tax or legal 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 payroll 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 payroll 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.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

Legislation: Crown copyright and database right.

1.0.1 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files