payroll.student-loan Unreviewed

pub fn student_loan(earnings: &Money, plan: &str, frequency: &str, pay_date: &str) -> Money

// StudentLoanPlan is a string in Rust, one of: "plan-1", "plan-2", "plan-4", "plan-5", "postgraduate".
// Parameters take it as &str and results hold it as String.

fune!(payroll.student-loan@^1);  // then call student_loan(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::money_amount::{money, money_from_value, money_to_value, Money};  ← from money.amount ^1.0.0 · built alongside by fune
use super::payroll_student_loan_data::{
    STUDENT_LOAN_THRESHOLDS, STUDENT_LOAN_THRESHOLDS_HISTORY, STUDENT_LOAN_THRESHOLDS_HORIZON,
};

fn is_iso_date(value: &str) -> bool {
    let bytes = value.as_bytes();
    bytes.len() == 10
        && bytes[4] == b'-'
        && bytes[7] == b'-'
        && bytes
            .iter()
            .enumerate()
            .all(|(i, b)| i == 4 || i == 7 || b.is_ascii_digit())
}

/// The student or postgraduate loan deduction for one pay period.
///
/// The period threshold is the annual one scaled exactly by weeks/52 or
/// months/12 (Education (Student Loans) (Repayment) Regulations 2009 reg.
/// 44(2)), not HMRC's printed weekly and monthly figures, which are that
/// fraction cut to the penny. The deduction then drops its pence (reg. 44(3)),
/// so the whole calculation stays in integers: pence times the period
/// denominator.
///
/// # Panics
/// Panics on non-GBP or negative earnings, an unknown plan or frequency, or a
/// date no threshold covers.
pub fn student_loan(earnings: &Money, plan: &str, frequency: &str, pay_date: &str) -> Money {
    if earnings.currency != "GBP" {
        panic!("student loan deductions must be in GBP, received {}", earnings.currency);
    }
    if earnings.minor < 0 {
        panic!("earnings must not be negative, received {}", earnings.minor);
    }
    if !matches!(plan, "plan-1" | "plan-2" | "plan-4" | "plan-5" | "postgraduate") {
        panic!("unknown student loan plan \"{}\"", plan);
    }
    let (periods, per_year): (i128, i128) = match frequency {
        "weekly" => (1, 52),
        "fortnightly" => (2, 52),
        "four-weekly" => (4, 52),
        "monthly" => (1, 12),
        other => panic!("unknown pay frequency \"{}\"", other),
    };
    if !is_iso_date(pay_date) {
        panic!("payDate must be an ISO date (YYYY-MM-DD), received \"{}\"", pay_date);
    }

    let rule = STUDENT_LOAN_THRESHOLDS.iter().find(|r| {
        r.plan == plan && pay_date >= r.valid_from && r.valid_to.map_or(true, |to| pay_date <= to)
    });
    let rule = match rule {
        Some(r) => r,
        None => {
            if let Some(horizon) = STUDENT_LOAN_THRESHOLDS_HORIZON {
                if STUDENT_LOAN_THRESHOLDS_HISTORY != "full" && pay_date < horizon {
                    panic!(
                        "no student loan threshold for {} on {}: this build was installed with history={}, so it only carries rules from {}. Reinstall with history=full for earlier tax years.",
                        plan, pay_date, STUDENT_LOAN_THRESHOLDS_HISTORY, horizon
                    );
                }
            }
            panic!("no student loan threshold for {} on {}", plan, pay_date)
        }
    };

    // Everything below is in pence x per_year, so the threshold is exact.
    let excess = earnings.minor as i128 * per_year - rule.annual_threshold as i128 * periods;
    if excess <= 0 {
        return money(0, "GBP");
    }
    let pounds = (excess * rule.basis_points as i128) / (10000 * per_year * 100);
    money((pounds * 100) as i64, "GBP")
}

pub fn fune_vector(args: &[Value]) -> Value {
    money_to_value(&student_loan(
        &money_from_value(&args[0]),
        args[1].as_str(),
        args[2].as_str(),
        args[3].as_str(),
    ))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add payroll.student-loan

The manifest, vectors and README with only the Rust implementation. Install it without the registry with fune add ./payroll.student-loan-1.0.2-rust.fune, or fetch it from a terminal with fune pull payroll.student-loan@1.0.2:rust.

The whole function, every language, is one file too: payroll.student-loan-1.0.2.fune, 26,022 bytes, sha256 676554a300c7212bc0f9a40a01e8e3840edacbd66b950e7d088c60c0bd40fb0d. It installs into a project of any language.

// fune: before payroll.student-loan

// fune: after payroll.student-loan

// fune: replace money.amount in payroll.student-loan
// fune: replace payroll.tax-period in payroll.student-loan

// fune: step payroll.student-loan after <n|label>

More from the author

- **Earnings are NI-able pay**, the figure employer Class 1 NICs are worked out on, not taxable pay: pension contributions under a net pay arrangement do not reduce it. - **The period threshold is exact.** Regulation 44(2) of the Education (Student Loans) (Repayment) Regulations 2009 scales the annual threshold by weeks/52 or months/12 of the earnings period. HMRC's printed weekly and monthly figures (£517.30, £2,241.66 for plan 1 in 2026-27) are that fraction cut to the penny, and on rare pay amounts the difference moves the deduction by a pound; a vector pins the case. Fortnightly is 2/52 and four-weekly 4/52 of the annual threshold. - **Pence are ignored** (reg. 44(3)): the deduction is always whole pounds, rounded down. HMRC's own worked example (£700 a week repays £16, £2,800 a month repays £50, plan 1, 2026-27) is a vector. - **One plan per call.** An employee repaying a postgraduate loan and a plan 1, 2, 4 or 5 loan has both deducted, concurrently (reg. 44(2A)): call twice. With two undergraduate plans and no SL1 yet, HMRC says to use the plan with the lowest threshold; picking that is the caller's job. - **Plan 5** repayments start in 2026-27 (threshold £25,000); asking for plan 5 before 6 April 2026 is an error. - The deduction is never negative. Refunds, under- and over-deduction recovery and the court-order ordering rules are out of scope.

## Sources

- The Education (Student Loans) (Repayment) Regulations 2009, reg. 44: https://www.legislation.gov.uk/uksi/2009/470/regulation/44 - HMRC, "Special rules for student loans" (thresholds from April 2026, plan 5, the £700 / £2,800 worked example): https://www.gov.uk/guidance/special-rules-for-student-loans - HMRC, "Rates and thresholds for employers" 2023 to 2024, 2024 to 2025, 2025 to 2026 and 2026 to 2027 (annual thresholds and the 9% / 6% rates): https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2026-to-2027

1.0.1 fixes Python accepting a trailing newline or non-ASCII digits in payDate; adds tests.

## 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.2 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files