Work out your take-home pay
Income tax, National Insurance and net pay for any UK salary, 2026-27.
Around 30.3 million people are paid through PAYE Real Time Information in the UK each month, and every one of them has a statutory right to an itemised pay statement at or before the moment they are paid [1] [2]. A payslip is not a formatting nicety. It is a legal document defined by the Employment Rights Act 1996, and since 6 April 2019 the right extends to every worker, not only to those classified as employees [3].
This article is written for developers and product teams. It explains what a payslip API is, the exact fields a UK payslip must carry by law, how those fields map to an API resource, how the document is rendered to PDF, and how payslip generation connects to the Real Time Information a payroll engine sends to HMRC.
A payslip API sits at the end of the payroll calculation chain. The engine works out gross pay, tax, National Insurance and every deduction, then a payslip endpoint turns those figures into a document that satisfies the itemised pay statement rules. Getting the fields wrong is not a cosmetic bug: an unnotified deduction can be challenged at an employment tribunal, which may order repayment of deductions made in the 13 weeks before a claim [4].
Key takeaways
- A payslip is a statutory itemised pay statement under the Employment Rights Act 1996, owed to every worker at or before payday [2] [3].
- By law a payslip must show gross pay, the amount and purpose of every variable and fixed deduction, net pay, and hours worked where pay varies by time [2] [5].
- A payslip API models the pay statement as a resource, usually returning both structured JSON and a rendered PDF.
- Electronic payslips are lawful, so a payslip API can deliver by download, email or portal rather than paper [6].
- Payroll records behind each payslip must be kept for 3 years from the end of the tax year, and HMRC can charge up to £3,000 for inadequate records [7].
What a payslip API actually does
A payslip API exposes the pay statement as a resource that a calling platform can create and retrieve over HTTP. In a well-designed engine, the payslip is not generated in isolation. It is the readable output of a completed payrun, so the calling platform posts pay data, the engine calculates the statutory figures, and the payslip endpoint assembles them into a document that carries every field the law requires [2].
The value of the model is that the hard part stays inside the engine. Tax bands, National Insurance thresholds, statutory pay rates and student loan plans all change at least once a year, and the calling platform should never hard-code them. When the engine holds the HMRC specification, a client platform posts gross pay and receives a payslip that already reflects the current tax code, the correct National Insurance category and the right deductions for the period [8].
Payslip as a resource, not a template
REST maps payslip actions onto standard HTTP verbs. A POST to a payrun creates the pay statements for that period, a GET reads a single payslip by its identifier, and a GET on a collection lists every payslip in a payrun. Each payslip resource typically carries a structured body (the figures as JSON) and a link or endpoint that returns the same statement rendered as a PDF for distribution to the worker.
Separating the data from the rendering matters in production. The JSON representation lets the host platform display figures inside its own interface, drive analytics, or feed a general ledger, while the PDF is the legal artefact the worker receives. A platform building a payslip screen never has to parse a PDF to read a net-pay figure, because the same value is available as a typed field in the JSON [9].
Why payslips fit the API model
Payslips are unusually well suited to an API because the content is deterministic and rule-bound. Given the same inputs (gross pay, tax code, National Insurance category and year-to-date figures) the statement is fixed by HMRC's published routines. That determinism is what lets an engine guarantee the same figures on every call, and it is why a platform can trust a payslip API to be the single source of truth for a value like income tax deducted at the basic rate of 20% on earnings above the Personal Allowance of £12,570 [10].
The second reason is that payslip generation and HMRC reporting draw on the same underlying payrun. The figures printed on the payslip are the figures reported to HMRC on the Full Payment Submission, which is why an engine that treats both as outputs of one calculation keeps them consistent by construction [11]. Moonworkers exposes this through its HMRC-recognised payroll API, where the payslip and the RTI submission come from the same payrun rather than two separate processes.
The legal fields a UK payslip must carry
No payslip API is compliant unless the document it produces contains the statutory minimum. The Employment Rights Act 1996 sets out the itemised pay statement, and the 2018 amendment order added the hours requirement for workers whose pay varies by time [3] [5].
The table below sets out the mandatory content and how each field usually appears in a payslip API response.
| Statutory field | What the law requires | Typical API field |
|---|---|---|
| Gross pay | The total pay before deductions | `grossPay` |
| Variable deductions | Amount and purpose of each (tax, NI, student loan) | `deductions[]` with `type` and `amount` |
| Fixed deductions | Amount and purpose, or a reference to a standing statement | `deductions[]` or `fixedDeductionStatementRef` |
| Net pay | The amount actually payable | `netPay` |
| Part-payment methods | Amount and method where pay is split across methods | `payments[]` with `method` and `amount` |
| Hours worked | Total hours where pay varies by time worked | `hoursWorked` |
Sources: GOV.UK payslip guidance and the Employment Rights Act 1996 [2] [3].
Deductions and their purposes
The single most common payslip failure is a deduction shown without its purpose. The Act makes an unnotified deduction one that is made without the employer giving the particulars required, so a line reading only "deduction: £40" is not compliant [4]. A payslip API should therefore model every deduction as a typed object carrying both a label and an amount, so the rendered document can print "PAYE income tax", "National Insurance" or "Plan 2 student loan" rather than an unlabelled figure [12].
Fixed deductions have a second lawful route. An employer may list them on every payslip, or set them out once in a standing statement of fixed deductions issued before the first payslip and reissued at least every 12 months [2]. A payslip API that supports both patterns lets the host platform choose, but the safer default is to itemise every deduction on the statement itself, because it removes any dependence on a separate document being current.
Hours worked, the field platforms forget
Since 6 April 2019, a payslip must show the total number of hours worked where the pay varies as a consequence of the time worked, for example an hourly worker or a salaried worker paid extra for overtime [5]. The hours can be shown as a single total or broken down at different rates. A payslip API should expose an hours field on the pay statement and populate it whenever the pay is time-variable, because a fixed-salary payslip that omits hours is fine, while a variable-pay payslip that omits them is not [6].
Rendering the payslip: JSON, PDF and delivery
Once the fields are correct, the payslip API has to turn them into a document a worker can read and a business can store. Two representations do most of the work: a structured body for machines and a rendered PDF for people.
From structured data to a PDF
The rendering step takes the JSON pay statement and lays it out as a document. The engine owns the template, so the calling platform does not have to know how to position a National Insurance line or format a year-to-date column. A GET on the payslip's PDF endpoint returns the finished artefact, which the host platform can then store, email or expose in its own interface. Because the PDF is generated from the same figures as the JSON, the two never drift apart [9].
For occasional or one-off needs, a rendering-only service can produce a single compliant statement without a full payroll integration. Moonworkers offers this through its instant payslip generator and its online payslip generator, which apply the same statutory fields to a single statement for a sole trader or an ad-hoc employer.
Electronic delivery is lawful
Employers can print payslips or send them electronically, so a payslip API is free to deliver by secure download, email attachment or a worker portal [6]. The legal test is that the itemised statement reaches the worker at or before payday, not that it arrives on paper. Acas confirms that it is not enough to make payslips available on request; the worker must be given the statement [13]. A payslip API should therefore treat delivery as an explicit step with a recorded timestamp, so the host platform can prove the statement was issued on time.
Retention and the audit trail
Every payslip sits on top of payroll records that HMRC requires to be kept for 3 years from the end of the tax year they relate to, and HMRC may estimate what is owed and charge a penalty of up to £3,000 where records are inadequate [7]. Separately, records that show minimum wage compliance must be kept for 6 years [14]. A payslip API that stores every generated statement, with its figures and its issue timestamp, gives the host platform the audit trail it needs to satisfy both retention rules. Most modern UK payroll software keeps this history automatically.
How payslip generation connects to HMRC
The figures on a payslip are the same figures a payroll engine reports to HMRC, which is why payslip generation cannot be treated as a standalone document feature. It is the human-readable face of the data the engine files under Real Time Information [11].
The payslip and the FPS carry the same numbers
The Full Payment Submission (FPS) reports each employee's pay and deductions and must reach HMRC on or before the day the employee is paid [11]. The pay, tax, National Insurance and student loan figures on the FPS are exactly the ones printed on the payslip, because both are outputs of the same payrun. An engine that generates the payslip and the FPS from one calculation removes the most common reconciliation error, where a corrected payslip and an already-filed submission disagree [15].
HMRC recognition is the baseline
Software that files RTI must be recognised by HMRC. Recognition confirms that a product meets HMRC's specifications for sending Full Payment Submissions and other RTI messages, and recognised products appear on the GOV.UK register of payroll software [16] [17]. For a platform embedding payslip generation, HMRC recognition is a baseline any serious engine already holds, so the buying decision turns on developer experience, breadth of statutory coverage and how cleanly the payslip data maps to the host product, not on the badge itself.
One payrun, two audiences
The cleanest architecture treats the payrun as the source of truth and the payslip and the FPS as two views of it. The worker reads the payslip; HMRC reads the FPS; the host platform reads the JSON. A payslip API built this way, and paired with a payroll REST API that files RTI as part of the payrun, keeps all three consistent without the host platform writing any tax logic of its own.
Check the figures behind a payslip
Before wiring a payslip API into a product, a developer often wants to confirm the net-pay maths for a given gross salary. The Moonworkers UK salary calculator applies the 2026-27 PAYE and National Insurance rules to any gross figure, which is a quick way to sanity-check the values a payslip endpoint should return.
£ per month
e.g. 1257L, S1257L, BR, D0
S = Scotland · C = Wales · W1/M1 = non-cumulative
Enter a salary or hourly rate above
About this calculator
This calculator gives you a close estimate of your UK payroll deductions for 2026-27, using HMRC's exact percentage method. It covers the vast majority of employees on standard tax codes, but it won't match your payslip to the penny in every case. Edge cases it does not cover include in-year tax code changes, K-code carry-forwards, Week 53 adjustments, payrolled benefits in kind, and multi-employment NI deferral. Powered by the same engine as the Moonworkers Payroll API.
Frequently asked questions
Why might the result differ from my payslip?
This calculator uses your current gross pay and tax code to produce an estimate. Your employer may apply adjustments not covered here, such as mid-year tax code changes, K-code carry-forwards, or benefits in kind processed through payroll. For most employees on a standard tax code these differences are negligible.
What tax code should I enter?
Use the tax code shown on your most recent payslip or the PAYE Coding Notice (P2) from HMRC. If you're not sure, 1257L is the standard code for most employees resident in England, Wales, or Northern Ireland. Use S1257L for Scotland or C1257L for Wales if you pay Scottish or Welsh income tax.
Which NI category applies to me?
Most employees use Category A. Use M if you are under 21, H if you are an apprentice under 25, or C if you are over State Pension age. Your employer is responsible for assigning the correct category — if in doubt, check your payslip.
Which student loan plan am I on?
Your plan depends on when and where you studied. Plan 1 covers students who started before September 2012. Plan 2 is for English and Welsh students who started from September 2012 to July 2023. Plan 5 applies to English students who started from August 2023. Plan 4 covers Scottish students. You can check your plan at gov.uk or on your payslip.
What is the YTD cumulative PAYE mode?
HMRC's standard method calculates income tax on your total earnings to date each period, then subtracts tax already paid. If you're mid-year and want to see exactly what tax should be deducted in a specific period, expand the Year-to-date section and enter your running totals from previous periods only.
Conclusion
A payslip API is where payroll compliance becomes visible. The calculation may be invisible to the worker, but the itemised statement is the document the law cares about, and it has to carry gross pay, every labelled deduction, net pay and hours where pay varies by time. Treating the payslip as a structured resource, rendered to PDF from the same figures the engine reports to HMRC, is what keeps the worker's copy and the tax filing in step.
The direction of travel is towards payslips that are generated, delivered and stored entirely through software, with the paper version an exception rather than the norm. As more HR, ERP and accounting platforms embed payroll rather than build it, the payslip endpoint becomes a small but load-bearing part of a larger compliance surface, and the platforms that win are the ones whose payslip data maps cleanly onto the product their users already know.
Frequently asked questions
What fields must a UK payslip include by law?
A payslip must show gross pay, the amount and purpose of every variable and fixed deduction, the net amount payable, and the amount and method of any part-payments where pay is split across methods [2]. Since 6 April 2019 it must also show the total hours worked where the pay varies according to time worked, such as an hourly worker or paid overtime [5]. A payslip API should expose each of these as a discrete field so the rendered document is compliant.
Can a payslip be delivered electronically through an API?
Yes. Employers may print payslips or send them electronically, so an API can deliver by secure download, email or a worker portal [6]. The legal requirement is that the itemised statement reaches the worker at or before payday, and Acas is clear that merely making payslips available on request is not enough [13]. Recording an issue timestamp on delivery helps prove the statement was provided on time.
How long do the records behind a payslip need to be kept?
HMRC requires payroll records to be kept for 3 years from the end of the tax year they relate to, and may charge a penalty of up to £3,000 where records are inadequate [7]. Records used to show minimum wage compliance must be kept for 6 years [14]. A payslip API that stores each generated statement with its figures and timestamp provides the audit trail both rules require.
Does a payslip API need HMRC recognition?
The payslip itself is governed by employment law, but the payroll engine that produces it must be HMRC-recognised if it also files Real Time Information, because recognition certifies that the software meets HMRC's specification for sending Full Payment Submissions and other RTI messages [16]. Recognised products are listed on the GOV.UK register [17]. In practice the payslip and the RTI submission share the same figures, so an engine that holds recognition and generates both from one payrun keeps them consistent.
