# payroll.national-insurance
Status: needs review by a qualified payroll professional before it is published.
Employee (primary) and employer (secondary) Class 1 National Insurance on one
payment, by HMRC's **exact percentage method**, for any category letter HMRC
published for the tax year of the pay date. Tax years 2023-24 to 2026-27 are
carried as dated data.
## How it is worked out
- **Thresholds for the earnings period.** Weekly and monthly figures are the
ones HMRC publishes. Fortnightly and four-weekly pay use two and four times
the weekly figures, which is HMRC's instruction for pay in multiples of a
week (CA38, "Adapting these tables for pay intervals other than weekly or
monthly"). Note that regulation 11 of the Social Security (Contributions)
Regulations 2001 derives multiples of a week from the annual figure (annual
/ 52 x weeks, rounded up to a pound), which for the four-weekly primary
threshold gives £967 rather than 4 x £242 = £968. This package follows CA38;
a reviewer should confirm which one HMRC's own software uses.
- **Employee:** the main rate on earnings above the primary threshold up to the
upper earnings limit, and the additional rate above it. Earnings between the
lower earnings limit and the primary threshold are charged at 0% but still
count for State Pension, which is what `lowerEarningsLimitReached` reports
(earnings at or above the LEL).
- **Employer:** three bands above the secondary threshold: up to the Freeport
/ Investment Zone upper secondary threshold, from there to the upper
secondary threshold (the same figure as the UEL, and the one that applies to
under-21s, apprentices under 25 and veterans), and above it. Each category
letter carries its own rate for each band; for letters A, B, C and J they
are all the same.
- **Rounding:** primary and secondary are worked out separately on the exact
earnings, and each total is rounded once to the nearest penny with less
than half a penny disregarded (so exactly half a penny goes up): SSCR 2001
reg. 12(1), NIM11002. HMRC's printed tables round to table steps and can
differ by a few pence; the vectors include a case where they do.
- **2023-24** had a mid-year change: the main primary rate fell from 12% to 10%
(and 5.85% to 3.85% for B and I) for payments made on or after 6 January 2024.
The pay date chooses.
## Directors
Pass `director` (earnings and NI already paid this tax year) to use the annual
earnings period: contributions are worked out on the year-to-date earnings at
the annual thresholds, and the result is that total less what was already
paid. In 2023-24 directors on the annual method pay the published whole-year
blended rates (11.5% main, 5.35% reduced) instead of the two part-year rates.
Out of scope: the pro-rata annual earnings period for a director appointed
during the year, and the "alternative arrangements" year-end recalculation
(run the annual method on the final payment to get it).
## Not covered
Category X (no liability), Class 1A and 1B, the Employment Allowance, the
Apprenticeship Levy, aggregation of several jobs, and category letter changes
in the middle of a period. Negative earnings (corrections) are refused.
## Sources
- HMRC, "Rates and thresholds for employers 2023 to 2024", "... 2024 to 2025",
"... 2025 to 2026", "... 2026 to 2027":
https://www.gov.uk/guidance/rates-and-thresholds-for-employers-2023-to-2024 (and the
-2024-to-2025, -2025-to-2026, -2026-to-2027 pages). Every threshold, rate and
category letter in data/ comes from these pages, including the 2023-24
director rates and the 6 January 2024 change.
- HMRC, NIM11002 "Class 1: calculating & recording earnings, NICs & NIC
rebates: exact percentage method":
https://www.gov.uk/hmrc-internal-manuals/national-insurance-manual/nim11002
- The Social Security (Contributions) Regulations 2001, regs. 11 and 12:
https://www.legislation.gov.uk/uksi/2001/1004/regulation/11
- HMRC, CA38 "National Insurance contributions tables A, D, F, H, J, L, M, N, V
and Z" 2025 to 2026 (multiples of a week; the worked example above the UEL):
https://www.gov.uk/government/publications/ca38-national-insurance-contributions-tables-a-and-j
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 professional 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 professional 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.