Extract NZ Payday Filing Data: Payroll PDF to IR EI Return

New Zealand payday filing requires an Employment Information (EI) return for every pay run. Electronic filers have 2 working days from payday to submit; paper filers have 10 working days. Electronic filing becomes mandatory once annual PAYE plus ESCT reaches NZD 50,000. For filers without an integrated payroll gateway, the upload route is myIR's express file transfer, which accepts CSV or XML files matching IRD's payday filing file upload specification. These filing deadlines and the electronic-filing threshold come directly from Inland Revenue's payday filing rules.

The EI return is the form. It replaced the older monthly IR348 employer monthly schedule when payday filing became compulsory in 2019, and it sits alongside the IR345 employer deductions form on which the matching PAYE, child support, KiwiSaver, ESCT, and student loan amounts are paid across to IRD.

What this article covers, and what almost nothing else on the SERP covers, is the bridging step: how to take a NZ payday filing payroll PDF to EI return-ready CSV when your payroll does not run through Xero Payroll NZ, FlexiTime, iPayroll, Smartly, or MYOB NZ. Those products file directly through IRD's gateway service, and if you are using one of them you should let it file. Everyone else — small employers on a spreadsheet, multinationals whose global payroll system spits out a multi-page PDF, businesses mid-migration, accountants verifying a client's filings — is doing manual format conversion against the IRD file upload specification, and is doing it inside a 2-working-day deadline. That is the workflow this guide walks: every per-employee field the EI return (formerly IR348 employer information return) still asks for, where the value sits on a payroll-run PDF, and how the payday filing CSV format IRD expects gets built out of it.

Who needs the bridging workflow: outside the integrated payroll gateway

Integrated NZ payroll products — Xero Payroll NZ, FlexiTime, iPayroll, Smartly, MYOB NZ, Datacom, PayHero — connect directly to IRD's payday-filing gateway service. The gateway submission happens at the moment the pay run is posted, the EI return is built from the payroll data the system already holds, and the file goes to IRD without anyone touching a CSV. If you are on one of these systems and the gateway service is enabled on your account, the rest of this article is not for you. Run the pay, let the gateway file, move on.

This workflow is for employers, bookkeepers, multinationals, migration teams, and advisers who have payroll PDFs, spreadsheets, or non-IRD CSV exports but no enabled payroll-gateway filing path. They all face the same constraint: there is a payroll-run PDF or source spreadsheet on one side, an IRD-specification EI return file on the other, and 2 working days to bridge the gap.

The EI return field map: from payroll-run PDF to IRD CSV

The EI return is a flat file with one header record identifying the employer and the pay period, followed by one detail record per employee paid in that period. The header carries the employer's IRD number, the pay-period start date, the pay-period end date, the payday date itself, and totals that the employee detail rows must sum to. Each detail row carries the per-employee fields below.

The table maps every per-employee column the IRD file upload specification expects, where you find the value on a typical payroll-run PDF, the format IRD requires, and the gotcha that catches people out. Order follows the IRD specification's column order, which is also the order you will be working through when you build a row.

EI return field	Where on the payroll PDF	IRD-required format	Common gotcha
Employee IRD number	Employee header on each payslip, or employee master listing	8 or 9 digits, no spaces or hyphens	Must pass the IRD modulus 11 checksum; a transposed digit fails validation at upload
Tax code	Employee header (M, ME, S, SH, ST, SB, plus non-declaration variants; WT for schedular payments)	Permitted code from the IRD list, exact match	The student-loan suffix codes (M SL, ME SL) appear with a space in some payroll PDFs and without one in others; use the exact form the IRD specification lists
Start date in pay period	Only populated for an employee's first pay-run in the period; otherwise leave blank	DD-MM-YYYY per the file specification	Populating it on every row instead of only the first pay flags every existing employee as a new starter
End date in pay period	Only populated for an employee's final pay-run when they leave; otherwise leave blank	DD-MM-YYYY per the file specification	Same shape as the start-date trap; populating on continuing employees creates spurious leavers
Gross earnings	Period column on the payslip (not YTD)	Numeric, two decimal places, no currency symbol	The payslip's YTD column is the single biggest source of over-statement on manual filings
Earnings not liable for ACC earners' levy	Payslip detail where applicable (typically pension or specific allowance lines)	Numeric, two decimal places, often zero	Default is zero; only populate where the earnings genuinely sit outside the ACC-leviable base
PAYE deducted	Period PAYE column on the payslip, including any tax on schedular payments routed through the same row	Numeric, two decimal places	If the run includes a lump sum, PAYE here must already reflect the extra-pay rate calculation; see the disambiguation rules
Child support deductions	Period child-support column on the payslip	Numeric, two decimal places, zero where none	Mis-coded child support that paid through the wrong column on the payroll system arrives here as zero
Student loan deductions	Period student-loan column on the payslip	Numeric, two decimal places, zero where none	A student-loan tax-code suffix without an actual deduction value signals a payroll calculation error worth checking before filing
KiwiSaver employee deduction	Period KiwiSaver employee column on the payslip	Numeric, two decimal places, zero where the employee is not in KiwiSaver	This is the employee's own contribution from their gross pay, not the employer's
KiwiSaver employer contribution	Period KiwiSaver employer column on the payslip; gross figure before ESCT	Numeric, two decimal places	This is the gross compulsory employer contribution, separate from the employee deduction; the two are not the same number and are not to be added together
ESCT deducted	Period ESCT column on the payslip	Numeric, two decimal places	ESCT is per-employee at that employee's ESCT rate; not a flat percentage across the workforce
Payroll giving	Period payroll-giving column where the employee participates	Numeric, two decimal places, zero where none	Easy to omit because most employers do not run a payroll-giving scheme; if any employee does, the column must be populated for that row
Lump-sum-pay indicator	Set to Y when the row contains a bonus, commission, redundancy, retiring allowance, or back-pay; otherwise N	Single character, Y or N	Setting the indicator without populating a lump-sum amount, or vice versa, fails IRD validation

The IRD specification is strict on field length, column order, and date and number formats. The file fails validation as a whole if any single row is malformed, so even one badly-typed row blocks the entire upload. The KiwiSaver, ESCT, and student loan payday filing fields are where most of the per-employee detail concentrates, and they reward careful per-row treatment rather than copying down formulas.

Once the detail rows are built, the header totals must reconcile to the sum of the corresponding detail-row columns: total PAYE, total child support, total student loan, total KiwiSaver employee, total KiwiSaver employer, and total ESCT. The IR345 employer deductions form for the same period reports the same totals from the employer side, so the header totals doubling as a cross-check before upload is worth the few seconds it takes.

The broader skill of pulling structured payroll data out of PDFs — the move that sits underneath this whole exercise — has its own discipline. Readers building an ongoing manual workflow rather than a one-off filing may find the wider walkthrough on how to extract payroll data from PDF to Excel a useful companion to this NZ payroll PDF to IRD EI return mapping; the EI return is one of several places that work feeds into.

Disambiguation rules that trip up manual filers

The field map covers what each column is. A handful of cross-field rules determine which value to use when the payroll PDF and the IRD specification do not line up cleanly, and these are where manual filings most commonly go wrong.

Period-only versus year-to-date. Almost every numeric field on the EI return is for the pay period only. Payslip PDFs almost always show two columns side by side: a period column (sometimes labelled "this pay" or "current") and a year-to-date column. The YTD column is cumulative and grows with every pay-run; the period column is what IRD wants. The single biggest manual-filing error is copying the YTD figure into gross earnings, which over-states the return — by orders of magnitude once a few months of YTD have accumulated. Read the period column every time, even when the payslip layout puts the YTD column closer to the field label.

Lump sums and extra pays. Bonuses, commissions, redundancy payments, retiring allowances, back-pay, and similar one-off payments are extra pays. The PAYE on an extra pay is calculated using the extra-pay tax rate logic — a rate that depends on the employee's annualised ordinary earnings band plus the lump sum itself — rather than the rate implied by the employee's normal tax code. The EI return separates extra pays into a lump-sum-pay indicator and the lump sum amount. Filers who fold the lump sum into ordinary gross earnings and leave the indicator at N report the row as ordinary pay; the PAYE line then reconciles against the wrong calculation. The rule: if the row contains an extra pay, set the indicator to Y, populate the lump sum amount, and confirm the PAYE figure was calculated using the extra-pay rate before it gets typed into the file.

KiwiSaver employee deduction versus KiwiSaver employer contribution. These are two separate columns on the EI return, not one. The employee deduction is taken from the employee's gross pay at their elected rate (default 3%, with elections of 4%, 6%, 8%, or 10%). The employer contribution — the compulsory employer contribution, or CEC — is paid by the employer in addition to gross pay, at a minimum of 3% of the employee's gross taxable earnings. ESCT is then deducted from that employer contribution at the employee's ESCT rate and reported in its own column. Filers who report only the employee number, only the employer number, or who add them into a single value all report incorrectly. IRD reconciles these totals against the IR345 employer deductions form for the same period, where the same KiwiSaver and ESCT amounts are also reported, and a mismatch surfaces there.

ESCT rate per employee. ESCT is not a single rate across the workforce. Each employee has their own rate, set at the start of the tax year based on their prior-year salary plus employer KiwiSaver contributions, with thresholds tiered from 10.5% up to 39%. New employees get a rate based on estimated annual earnings until the first full year is reportable. Manual filers who default everyone to one rate — usually 33% as a "safe" choice — under-deduct on lower-paid staff and over-deduct on higher-paid staff. Either direction generates a year-end reconciliation issue that is easier prevented than corrected.

Child support and student loan deduction priority. When an employee has both a child-support deduction notice and a student-loan repayment obligation alongside PAYE, the order in which deductions come out of gross pay matters. Child support follows IRD's deduction priority rules, with protected net earnings limiting what can be taken from each pay. Student loan deductions interact with the relevant tax code suffix and the standard repayment threshold for the period. The EI return reports the actual amounts deducted in the period; the priority rule matters because what your payroll calculation produced has to match what you file. Re-deriving deductions from the gross pay in the EI return without applying the priority rule will give a different number from the payslip.

Working-day calculation for the deadline. The 2-working-day filing deadline is calendar-aware. Working days exclude weekends and New Zealand public holidays. A pay run on a Friday is due by the close of Tuesday, not Sunday. A pay run on the working day before a long weekend may not be due until the Wednesday or Thursday after, depending on the public-holiday calendar. The provincial anniversary days matter for filers in those provinces. Manual filers who count calendar days end up filing late on the long-weekend pay-runs every quarter; build the working-day calculation into the schedule, not the calendar one.

Schedular payments and the WT tax code in the same EI return

Contractors who have given the payer a completed IR330C tax-rate notification are reported on the same EI return as employees, with the tax code WT (withholding tax). Schedular payments do not generate a separate return; the EI return covers employees and IR330C contractors together.

For a WT row, the populated fields are the contractor's IRD number, the WT tax code, the gross schedular payment as gross earnings, and the withholding tax as the PAYE figure. KiwiSaver employee deduction, KiwiSaver employer contribution, ESCT, child support, student loan, and payroll giving do not apply to schedular payments and stay zero or null per the IRD specification. Start-date and end-date in period are populated only if the contractor is reportable as a starter or leaver for the period, which is unusual for one-off engagements and more common for long-running contractor relationships.

The practical consequence: a small employer with one occasional contractor still uses the EI return for that contractor's pay. There is no lower-volume route or simpler alternative form. The same 2-working-day filing deadline applies, the same myIR upload route applies, and the same IRD validation rules apply. A row that misses the WT code, or that puts KiwiSaver and ESCT beside withholding tax, will fail upload validation.

The contractor-side mechanics — what rate the contractor can elect on their IR330C, what the no-notification default rate is, how the AP-side withholding workflow runs alongside invoice processing — sit one step away from the EI return surface and have their own depth. Readers who need to understand how the rate flowing into the WT row was set, or who run the AP side rather than the payroll side, will get more from the dedicated walkthrough on NZ schedular payments and IR330C contractor withholding than from re-deriving the rules here.

Uploading via myIR express file transfer

myIR's express file transfer is the upload route for filers without a gateway service connection. It sits inside the employer's myIR account, under the payroll account specifically. From the payroll account home, the option to file an EI return by file upload appears alongside the option to file by manual entry; the file upload path is the one to use when you have built a CSV or XML to the IRD specification.

Two file format choices are available. CSV per IRD's payday filing CSV format is the more common choice for filers building the file by hand or in a spreadsheet — column-and-row layout, one detail row per employee, header record at the top. XML per the same specification is more common for filers generating the file from a script or from middleware between systems. Both must conform exactly to the file upload specification's record layout: column order, mandatory fields, field length limits, date format, number format. Either format passes through the same myIR express file transfer payday filing route once submitted.

File naming matters. The IRD specification sets a naming convention that combines the employer's IRD number, the payday date, and a sequence indicator for the period. A file with a non-conforming name fails validation before any record is read, which is among the most common rejection causes — and one of the most frustrating, because the records inside the file may have been correct.

Beyond the filename, the rejection causes that surface most often at upload are:

• An employee IRD number that fails the modulus 11 checksum (the IRD number's check digit is computed from the other digits; a transposed number breaks the check)
• A date format mismatch — the file specification's date format is strict, and a YYYY-MM-DD or MM/DD/YYYY field where DD-MM-YYYY is required will fail the row
• A pay-period end date earlier than the pay-period start date, usually a header transposition
• Header totals that do not match the sum of the corresponding detail-row columns
• A lump-sum-pay indicator set to Y without a lump sum amount populated, or vice versa
• A tax code outside the permitted list (a stray space, a misspelt code, a code from another jurisdiction copied in by accident)

A failed upload returns an error message identifying the row and the rule that broke. Fix the row, re-upload the same file with the correction, and the file passes through validation again. The 2-working-day clock is on the original payday, not on the upload attempt, so each rejection costs real time inside the window.

Amendments after a successful filing follow a separate path. When an EI return has been filed and an error is later found, the correction goes through the same myIR upload route, but the file is marked as a replacement for the original payday rather than as an additional return. The replacement overwrites the original record set in IRD's system; payments adjust accordingly through the IR345 employer deductions form for the period in which the error sat. There is no separate "correction" form to submit alongside the replacement.

Verifying client filings against payslip PDFs

When a chartered accountant or bookkeeper inherits a client's payroll workings, or when a quarterly review covers a stack of already-filed payday returns, the most efficient check is not a full re-build of the return. The job is to reconcile what was filed against the payslip PDFs that were the source of the figures, and to flag mismatches by category rather than re-do the calculation.

A defensible reconciliation order — the order in which errors typically surface, working from the cheapest checks to the costliest:

1. Header check. The IRD number on the EI return matches the client's IRD number. The pay-period start date, pay-period end date, and payday date on the return match the payslip batch. Most clients run a regular fortnightly or monthly cycle, so a payday date that does not fit the expected cadence is the first thing worth questioning.
2. Employee count and identity. Every employee with a payslip PDF for the period has a corresponding row on the return. Every WT-coded contractor with a schedular-payment payslip has a corresponding row. No employees appear on the return who are not on the payslip set. Mis-coded leavers and ghost employees both surface here.
3. Gross earnings per employee. The period column on the payslip — not the YTD column — matches the gross earnings on the return row. This is where the single most common manual-filing error surfaces; if you find period-versus-YTD substitution on one row, check every row in the period for the same mistake.
4. PAYE per employee. The period PAYE column on the payslip matches the PAYE figure on the return. Variances on lump-sum rows are expected because of extra-pay rates; variances on ordinary-pay rows are not.
5. KiwiSaver employee deduction and the separate employer contribution. The payslip's two KiwiSaver lines — the employee's own deduction and the employer's compulsory contribution — match their respective columns on the return as two distinct numbers. ESCT reconciles against the employer contribution at the rate that applied for that employee. For accountants checking a client's payday filing against payslips, this is the step that catches combined KiwiSaver figures most reliably.
6. Other deductions. Child support, student loan, and payroll giving each map to their column on the return. Deductions on the payslip that do not appear on the return signal a tax-code mis-set or a column omission; deductions on the return that do not appear on the payslip signal the opposite — usually a stale calculation carried forward from a prior period.
7. Lump-sum rows. Any payslip showing a bonus, commission, redundancy, or back-pay should have the lump-sum-pay indicator set to Y on the corresponding return row, with the lump sum amount populated. An indicator left at N on a row that visibly contains an extra pay is a misclassification worth raising with the client.
8. Header totals to IR345. The sum of detail-row PAYE, child support, student loan, KiwiSaver employee, KiwiSaver employer, and ESCT reconcile to the IR345 employer deductions form for the period. A mismatch between EI return totals and IR345 totals is the cleanest signal that one of the two was filed wrong.

Two things this reconciliation cannot catch from PDFs alone. Each employee's ESCT rate correctness depends on prior-year salary data the payslips do not show, so flag ESCT for separate review against the employee master rather than treat the column as reconciled. Working-day calculation for the original filing deadline is also outside what the payslips reveal — a return that reconciles cleanly against payslips can still have been filed late, and the late-filing penalty is its own check.

Reducing the manual-extraction bottleneck

Inside the 2-working-day window, the bottleneck for non-gateway filers is the manual transcription itself. The myIR upload is fast. IRD validation is mechanical and runs in seconds. What consumes the working days is reading gross earnings, PAYE, KiwiSaver employee deduction, KiwiSaver employer contribution, ESCT, child support, student loan, and the lump-sum indicator off each payslip in turn, and typing them into the right columns of the CSV in the right format. For a 20-employee fortnightly payroll that is around 240 numeric fields per pay-run, plus the header reconciliation, plus the format checks. A bookkeeper with five clients on the same fortnight is working that 240-field exercise five times in two days.

That is the workflow AI-powered payroll PDF data extraction shortens: upload the payroll-run PDF, ask for the EI-return columns, export CSV or Excel, then review the rows against the payslip totals before myIR upload. Source-page references give the bookkeeper a check trail without turning the 2-working-day deadline into a transcription race.

If the source files are individual payslips rather than a payroll-run report, the companion workflow is NZ payslip data extraction, because the EI return still depends on the same per-period payroll fields.