The Moonworkers API for UK payroll

The employer rate of National Insurance sits at 15% from 6 April 2026, and a Full Payment Submission must reach HMRC on or before payday, every payday, or a penalty follows. Those two facts sit at the centre of what any UK payroll system has to get right, and getting them right at scale is exactly what the Moonworkers API is built for. It is an HMRC-recognised UK payroll engine exposed as a REST API, designed for other software platforms to call rather than for an end user to log into.

The distinction matters. Most UK payroll products are a website or a desktop application first, with an API added later as a thin layer. Moonworkers inverts that order. The API is the product, and the compliance work (PAYE, Real Time Information, National Insurance, auto-enrolment, statutory pay) runs inside it. A host platform sends employee and pay data, and the engine returns exact deductions, files with HMRC, and generates the statutory documents.

This guide explains what the Moonworkers API covers, how it connects to HMRC, what a payrun looks like end to end, and who embeds it. It is written for developers, product teams and payroll bureaux weighing up whether to build UK payroll themselves or plug into an engine that already holds the HMRC badge.

Key takeaways

• The Moonworkers API is an HMRC-recognised payroll API, an embeddable engine rather than a bureau service or a UI-first application.
• It covers the full UK statutory stack: PAYE income tax, National Insurance, student loans, statutory pay, auto-enrolment and Real Time Information.
• It files FPS and EPS submissions to HMRC, handles corrections and late reasons, and ingests inbound HMRC notices through the Data Provisioning Service.
• It produces the statutory documents (payslips, P60, P45, P11 and P11D) and pension contribution files in the open PAPDIS standard.
• A single integration can serve many employers, which suits HR platforms, ERPs and multi-client payroll bureaux.
• HMRC recognition is the market entry threshold, so the criteria that actually separate engines are developer experience, embeddability and independence from any parent suite.

What the Moonworkers API is

A payroll engine, not a bureau or a front-end tool

A payroll bureau takes the payroll job off an employer's hands and runs it as a managed service. A UI-first SaaS gives the employer a website to log into and operate payroll themselves. The Moonworkers API is neither. It is the calculation and compliance layer that sits underneath a host platform, so the host's own users never have to leave their product or open a separate payroll account.

That model rests on being recognised by HMRC. Recognition is a scheme that tests commercial software against a range of payroll scenarios and confirms it can report Real Time Information through the Government Gateway ^[1]. HMRC publishes the list of recognised products, and reporting PAYE information in real time is a legal obligation for employers with staff on a payroll ^[2]. An engine that a platform embeds has to clear that bar before it can submit anything on a customer's behalf.

HMRC recognition is the baseline, not the headline

A team evaluating a payroll API often treats HMRC recognition as a differentiator. It is not. Every serious UK payroll product carries the badge, because without it the software cannot file RTI at all ^[1]. Recognition confirms the software calculates income tax, National Insurance, statutory payments and student loans correctly and submits the right RTI messages ^[3].

Because recognition is universal, the criteria that decide a build-versus-integrate question lie elsewhere: whether the API is genuinely embeddable, whether a developer can self-serve against documentation and a sandbox, and whether the engine is independent of a wider accounting or HR suite. Moonworkers positions recognition as the floor and competes on those higher criteria instead. The public API documentation lets a developer browse endpoints before writing a line of integration code.

What the API calculates: gross to net

PAYE income tax and tax codes

The core of any payroll engine is turning gross pay into net pay. Moonworkers applies the current PAYE tax tables to each employee's tax code and pay period. For the 2026-27 tax year the Personal Allowance is £12,570, the basic rate of 20% applies up to £50,270, the higher rate of 40% runs to £125,140, and the additional rate of 45% applies above that ^[4]. Scottish and Welsh variations are handled through the tax code prefix.

Tax codes drive the calculation, and the engine reads them the way HMRC intends. The standard code is `1257L`, while `BR`, `D0` and `D1` apply flat rates with no allowance, and a `K` prefix signals that deductions exceed the allowance ^[5]. HMRC also caps any single PAYE deduction at 50% of gross pay, a safety rule the engine enforces so a large `K` code or back-tax recovery never over-deducts ^[4].

National Insurance for employees, employers and directors

National Insurance runs alongside income tax and has its own thresholds. Employees pay 8% on earnings between the Primary Threshold and the Upper Earnings Limit, and 2% above it, while employers pay 15% above the Secondary Threshold of £5,000 a year ^[6]. The engine applies the correct category letter for each worker, including the zero-rate reliefs for employees under 21, apprentices under 25 and armed forces veterans ^[6]. Many smaller employers can also reduce their annual employer National Insurance bill through the Employment Allowance, which the engine reflects through the Employer Payment Summary ^[25].

Directors are a common source of error, because their National Insurance is assessed on an annual basis even when they are paid monthly ^[7]. A payroll engine that treats a director like an ordinary monthly employee will miscalculate their contributions across the year. Moonworkers applies the annual earnings-period method for directors so a low-salary director-shareholder is assessed correctly ^[7].

Student loans and postgraduate loans

Student loan repayments are collected through payroll for employees on a repayment plan. The deduction is 9% of earnings above the plan threshold, calculated per pay period and rounded down to the nearest pound ^[8]. The engine holds the four undergraduate plans plus the postgraduate loan, each with its own threshold, and applies the right one from the employee record or an inbound HMRC notice ^[8].

Priority order matters when an employee has both a student loan and a postgraduate loan. HMRC requires the postgraduate loan to be handled alongside the plan-type loan, each against its own threshold, rather than in plan-number order ^[8]. Getting that wrong under-collects or over-collects, so the engine sequences the two deductions to HMRC's rules and reflects them on the payslip and the FPS ^[3].

Statutory pay and leave

Family statutory payments and average weekly earnings

Statutory maternity, paternity, adoption, shared parental, parental bereavement and neonatal care pay all follow the same shape: a percentage of average weekly earnings for an opening period, then a flat weekly rate ^[9]. Statutory Maternity Pay, for example, is 90% of average weekly earnings for the first six weeks, then the lower of the flat rate or 90% of average weekly earnings ^[9]. The engine calculates average weekly earnings from the relevant reference period so eligibility and the payment amount are both derived, not entered by hand.

Recovery is part of the same calculation. An employer can reclaim a large share of family-related statutory pay, and smaller employers can reclaim more than they paid through Small Employers' Relief, which the engine tracks against the Employer Payment Summary ^[10]. Because the recovery flows into the EPS rather than the FPS, an engine has to route the figures to the correct submission ^[11].

Statutory Sick Pay after the 2026 reform

Statutory Sick Pay changed structurally on 6 April 2026. Under the Employment Rights Act 2025 the waiting days were removed, so SSP is due from the first day of sickness rather than the fourth, and the earnings floor was removed so lower-paid workers now qualify ^[12]. The engine applies the flat weekly rate or the percentage of average weekly earnings for workers below the flat rate, and starts the entitlement on day one ^[12].

Unlike family-related payments, SSP is not recoverable from HMRC, so the employer absorbs the full cost ^[10]. That makes accurate SSP calculation a direct cost-control issue as much as a compliance one. An engine that starts SSP on the wrong day or applies an outdated earnings test either overpays the employer's own money or underpays a worker who is now entitled ^[12].

Real Time Information to HMRC

FPS, EPS and submission deadlines

Real Time Information is the reporting regime that sits behind PAYE. Every time an employer pays staff, a Full Payment Submission has to reach HMRC on or before the payday, reporting pay, tax, National Insurance and deductions for each employee ^[3]. The Moonworkers API builds and files the FPS directly from a finalised payrun, so the submission is a by-product of running payroll rather than a separate manual step.

The Employer Payment Summary is the second RTI message, used to tell HMRC about reductions such as statutory payment recovery or to report that no employees were paid in a period ^[11]. An EPS is generally due by the 19th of the following tax month ^[11]. The engine creates and submits both message types, and lists prior submissions so a platform can show its users a clear filing history.

Corrections, late reasons and penalties

Payroll is rarely perfect on the first pass, so the API supports corrections as first-class operations. It can create an FPS correction and convert a correction into a submission, which matters because HMRC expects errors to be put right through the RTI channel rather than left to a year-end adjustment ^[3]. Where an FPS is sent after payday, HMRC expects a late-reporting reason code, which the engine can attach to the submission.

Getting this wrong carries a cost. HMRC charges late-filing penalties that scale with the size of the PAYE scheme, and it can add further penalties and charge interest where filing failures persist ^[13]. Because the engine files on or before payday from the finalised payrun and supports corrections in the same channel, it is built to keep an employer inside the on-time window rather than chasing penalties afterwards ^[13].

Inbound HMRC notices and NINO verification

RTI is a two-way exchange. HMRC issues coding notices such as the P6 and P9, and student loan notices such as the SL1 and SL2, through the Data Provisioning Service, and a payroll system is expected to act on them ^[14]. The Moonworkers API ingests these notices and applies the new tax code or student loan instruction to the affected employee, so the next payrun reflects HMRC's latest position without manual re-keying ^[14].

The engine also submits National Insurance number verification requests. Where a new employee's National Insurance number is missing or in doubt, an employer can ask HMRC to confirm or supply it, and HMRC replies through the same data channel ^[15]. Automating that verification keeps employee records clean, which in turn keeps the FPS free of the mismatches that trigger HMRC queries ^[3].

Auto-enrolment and pensions

Assessing workers on every payrun

Auto-enrolment duties run on the same cycle as payroll. An employer has to assess each worker every time payroll is processed, deciding whether the worker must be automatically enrolled, can opt in, or should simply be told of the right to join ^[16]. An eligible jobholder is broadly a worker aged between 22 and State Pension age earning above the earnings trigger, and the assessment cannot be deferred to a quarterly review ^[16].

The Moonworkers API performs this assessment inside the payrun and records the outcome. Minimum contributions are set at 8% of qualifying earnings in most schemes, of which at least 3% comes from the employer, applied to the qualifying earnings band ^[17]. By assessing and calculating in the same pass, the engine keeps enrolment status, contributions and the payslip consistent for every worker ^[17].

Contribution files and the PAPDIS standard

Once contributions are calculated they have to reach the pension provider, and the UK has an open standard for that exchange. The Payroll and Pension Data Interface Standard, PAPDIS, defines a single file format that covers the data every provider needs, so payroll software can produce one file rather than a bespoke layout per scheme ^[18]. The engine can generate a PAPDIS file and, where a provider is connected directly, submit contributions programmatically.

This matters for a platform serving many employers across different schemes. Rather than build a separate integration for each pension provider, a host can rely on the engine to output the standard file or call a connected provider ^[18]. Auto-enrolment is a legal duty with its own regulator, so producing provider-ready contribution data on time is part of the compliance surface, not an optional extra ^[16].

The payrun lifecycle and documents

From draft payrun to finalised RTI

A payrun in the API moves through a clear lifecycle. It can be created and refreshed as inputs change, individual employees can be excluded or reintegrated, and a payment can be reset before the run is committed. Only when the run is finalised does the engine lock the figures and prepare the FPS, which keeps draft calculations separate from the numbers actually reported to HMRC ^[3].

The lifecycle also allows a finalised run to be reopened where a genuine correction is needed, feeding back into the RTI correction flow rather than forcing a workaround ^[13]. Alongside the payrun, the engine can produce a payrun journal for posting into an accounting ledger and payment instructions for paying employees, so the run connects to both the accounting and banking sides of a business ^[19]. This is the layer an SME payroll platform needs to expose to its users as a simple, reliable pay cycle.

Payslips, P60, P45, P11 and P11D

Every pay cycle produces documents, and the engine generates them as part of the run. Employees are entitled to an itemised payslip showing gross pay, deductions and net pay, and the API can produce, email and download payslips individually or in bulk ^{[19] [26]}. For platforms that only need one-off documents, Moonworkers also offers an instant payslip generator built on the same engine.

Year-end and leaver documents follow the same pattern. The P60 is the year-end certificate every employer must give to each employee still on the payroll at the end of the tax year ^[20], and the P45 is issued when an employee leaves ^[21]. The engine also produces the P11 deductions working sheet and the P11D for expenses and benefits, so the reporting documents an employer is legally required to produce are covered end to end ^[22].

Architecture and integration

Authentication, security and access

Because a payroll engine handles pay data and files on an employer's behalf, access control is central. The Moonworkers API uses OAuth2 for authorisation and supports two-factor authentication, and it stores the Government Gateway credentials needed to submit RTI to HMRC ^[14]. That combination lets a host platform delegate access cleanly while the engine holds the HMRC submission credentials securely.

Payroll data is also personal data, which brings UK data protection duties into scope. An organisation processing employee pay information has obligations under UK data protection law, and both the host platform and the engine sit within that framework ^[23]. Building on a recognised engine with structured authentication reduces the surface a host platform has to secure itself, though the host remains responsible for its own handling of the data it sends ^[23].

One integration, many employers

A single Moonworkers integration can run payroll for many employers under the same connection, which is what separates an embeddable engine from a single-company tool. That design suits a payroll bureau running tens or hundreds of client schemes from one platform, and it suits an HR product delivering payroll to its whole customer base ^[2]. The accountant and bureau workflow is built on the same API that powers a single SME's payroll.

The multi-employer model also carries sector coverage. Construction businesses, for example, operate under the Construction Industry Scheme with its own deduction and statement rules, which the engine handles natively rather than treating as an add-on ^[24]. A platform serving mixed sectors can therefore rely on one integration for standard PAYE payroll and construction subcontractor payments alike ^[24].

Work out take-home pay before integrating

Before wiring the API into a product, a team often wants to see the gross-to-net logic on a single salary. Moonworkers exposes the same engine through a UK salary calculator, which applies the 2026-27 PAYE and National Insurance rules to any gross figure and shows the resulting deductions ^[4].

Conclusion

The Moonworkers API packages the whole UK payroll obligation, from the first gross-to-net calculation to the final year-end certificate, into an engine that other software can embed. The compliance work does not become simpler because it is behind an API, but it becomes something a platform can rely on rather than rebuild: the tax tables, the National Insurance categories, the RTI messages, the inbound HMRC notices, the auto-enrolment assessment and the statutory documents are all handled in one place, and kept current as the rules change each April.

For a product team, the decision is less about whether payroll is hard, which it plainly is, and more about where that difficulty should live. The direction of travel across HR platforms, ERPs and bureau tooling is towards embedding compliance plumbing rather than owning it. An engine that is recognised by HMRC, exposed as a documented REST API and able to serve many employers from one integration is built for exactly that shift. Readers weighing a build against an integration can explore the endpoint reference in the Redoc API documentation and read the companion guide on what a payroll API is.

Frequently asked questions

Is the Moonworkers API recognised by HMRC for RTI submissions?

Yes. Moonworkers is an HMRC-recognised payroll engine, which is the prerequisite for submitting Real Time Information through the Government Gateway ^[1]. Recognition confirms the software calculates PAYE, National Insurance, statutory payments and student loans correctly and can file the required RTI messages ^[3]. It is the market entry threshold rather than a premium feature, so every serious UK payroll product carries the same badge.

What is the difference between a payroll API and an embedded payroll engine?

A payroll integration API usually lets an existing payroll product sync data with adjacent tools, so the product cannot be used without the host software. An embedded payroll engine is the payroll product itself, exposed for another platform to call from inside its own interface, with the end user never seeing the underlying vendor ^[2]. The Moonworkers API is the second kind: the engine other platforms embed to deliver UK payroll to their own customers.

Can one integration handle payroll for multiple employers?

Yes. A single connection to the Moonworkers API can run payroll for many separate employers, which is what makes it suitable for payroll bureaux and HR platforms rather than only single companies ^[2]. Each employer's Real Time Information is filed under its own PAYE scheme, and the engine keeps the schemes distinct while sharing one integration ^[3].

Does the API handle auto-enrolment and pension contributions?

Yes. The engine assesses each worker for auto-enrolment on every payrun, applying the age and earnings tests that determine enrolment status ^[16]. It calculates contributions against the qualifying earnings band, where the total minimum is usually 8% with at least 3% from the employer, and it can output a PAPDIS file or submit to a connected provider ^[17].

Image prompt (Imagen): Reportage shot, two software developers reviewing UK payroll integration code on a large monitor in a bright modern office, one pointing at an API response on screen, soft daylight through floor-to-ceiling windows, mid-afternoon, palette of cool grey, matte black, muted teal, exposed concrete and a green plant out of focus in the background, off-centre composition with the screen in the right third, shot on a Sony A7 IV at 35mm f/2.8, photojournalism, gentle film grain, natural skin tones, no AI artefacts, no warped hands, no warped text, landscape orientation 16:9.