How to Extract NZ Payslip Data for Holidays Act Remediation

In New Zealand, pay-as-you-go holiday pay must equal at least 8% of gross earnings and appear as an identifiable component of pay — a separately labelled line on the payslip with its own pay code. The eligibility rule is narrow. According to Employment New Zealand's pay-as-you-go annual holiday payments guidance, pay-as-you-go (PAYG) annual holiday pay is only lawful for employees working so irregularly or intermittently that 4 weeks of annual holidays is impracticable, or for employees on a genuine fixed-term agreement of less than 12 months. Anywhere else, that 8% line either belongs in the leave-when-taken regime or is unlawful.

That single rule is what three different audiences land on the same NZ payslip to verify, and it is where any project to extract NZ payslip data for Holidays Act compliance, remediation, or migration begins. A NZ employee opens their slip to check whether the 8% is there, what it is labelled, and whether the labelling matches their employment shape. A Holidays Act remediation analyst pulls historic gross earnings, ordinary-time hours, and contracted-hours data out of years of legacy payslips to feed a BAPW, AWE, OWP, RDP, and ADP recalculation. A payroll migration consultant pulls closing leave balances and YTD totals out of the last payslip per employee so the new system carries the right opening figures from cutover day one.

Each audience has its own dedicated section below, so a reader who is only here for the 8% PAYG diagnostic, or only here for the remediation field map, or only here for the migration extract, can skim past what is not theirs. What every audience shares is the document itself and the structural reality that makes extraction work non-trivial. New Zealand has no statutory payslip — payslips are the de facto compliance document because employers must keep wage-time records — and the layout reality across Smartly, FlexiTime, iPayroll, Datacom Datapay, IMS Payroll, Crystal Payroll, MYOB IMS, Xero Payroll, ADP, and assorted legacy in-house formats is that no two layouts agree on where the gross-earnings categories sit, how the deduction stream is ordered visually, or where the leave balances live on the page.

The article walks the data-extraction layer for all three projects: what is on a NZ payslip, the 8% PAYG identifiability test for employee verification, the BAPW / AWE / OWP / RDP / ADP map for remediation, the leave-balance and YTD map for migration, and the cross-layout extraction approach for the mixed PDF history any real project carries. The downstream work — the remediation recalculation engine, the migration cutover plan, the legal advice an employee may need on an underpayment claim — belongs with the specialist disciplines that own it. The article's contribution is the extraction layer that feeds them all.

What appears on a New Zealand payslip and why no two layouts agree

New Zealand does not require an employer to issue a payslip. What the law does require is that wage-time records — hours worked, pay rates, leave taken, leave balances, gross and net pay — are kept and disclosed to an employee on request. Payslips are the de facto compliance document because they are how almost every payroll system surfaces those records each cycle, but because no statute prescribes the form, no canonical layout exists. Every extraction project across NZ payroll inherits this: the same fields exist on every compliant slip, but where they sit, what they are labelled, and how they are grouped varies vendor by vendor.

The first structural feature to map on any NZ payslip is the period-versus-YTD split. Every slip shows current-period figures (this fortnight's gross, this fortnight's PAYE, this fortnight's KiwiSaver) and the same fields again as year-to-date totals. The two columns usually sit side by side, and on some layouts the YTD figures are visually larger than the period figures, on others the opposite. A remediation analyst extracting period gross earnings out of the YTD column corrupts every downstream calculation; a migration consultant extracting YTD figures out of the period column understates the new system's opening position by months. The columns are usually labelled, but vendors disagree on whether to label them "This Pay" / "Year to Date", "Current" / "YTD", "Period" / "FYTD", or some abbreviation thereof. Any roster spanning multiple vendors needs the period-versus-YTD column mapping resolved per layout, not assumed from position.

Gross earnings on a compliant slip is broken into categories rather than a single total. The categories that matter for any extraction schema are ordinary time (the contractual base wage for hours worked at the standard rate), overtime (paid at penalty rates above contracted hours), allowances (tool allowance, vehicle allowance, on-call allowance, and similar recurring or one-off additions), commission and bonus payments, lump sum or extra pay (which carries its own PAYE rule under the IRD's extra-pay schedule), holiday pay paid out as leave taken (the leave-when-taken regime that is the default treatment under the 2003 Act), and the 8% identifiable component where PAYG applies. A "Total Earnings" line that flattens these into one figure is not enough for either remediation or migration work — both downstream uses need the breakdown.

The deduction stream on a NZ slip runs in a fairly consistent order across vendors. PAYE comes first, calculated on the gross figure with the employee's tax code applied. Then KiwiSaver employee contribution (the contributor's own contribution, abbreviated CEC on some layouts), then student loan repayment (where the tax code carries an SL suffix), then child support deduction (where the IRD has issued a deduction notice to the employer), then payroll giving (donations to approved donee organisations, with the tax credit applied at source). Each line should carry its own descriptor and its own period and YTD figures. KiwiSaver-employee, student loan, and child support amounts vary with gross earnings each period; payroll giving is usually a fixed amount the employee has nominated. Reading the reconciling CWPS deductions from Irish construction payslips walkthrough alongside this section is worthwhile for anyone doing deduction-line audits at scale, as the cross-jurisdictional pattern of reading a deduction line against a statutory rule is the same shape.

Two further lines that almost always appear on a NZ slip are not employee deductions at all, despite their visual placement near the deduction block. KiwiSaver employer contribution is the employer's matching contribution to the employee's KiwiSaver scheme — paid by the employer in addition to the employee's own contribution, not deducted from the employee's gross. Employer Superannuation Contribution Tax (ESCT) is the tax the employer pays on that employer contribution, again from the employer's own funds. Both lines appear on the payslip for transparency and because they affect the cost of employment that the employer is reporting in the period, but neither reduces the employee's net pay. An extraction schema that puts these lines into the same bucket as PAYE or KiwiSaver-employee inflates the total deductions figure and misstates net pay against the slip's own subtotal — a common error worth catching at the schema-design stage rather than during reconciliation.

The remaining fields most layouts carry are the tax code field and the IRD number. Tax codes follow the IRD's two-letter convention with optional suffixes — M is the primary-source code for a single source of income with no student loan, M SL is the same with a student loan, ME is for those receiving the independent earner tax credit, S / SH / ST are secondary-source codes for second jobs at different income brackets, and there are further variants for casual agricultural, election-day, and non-resident workers. The tax code matters for any reconciliation against the PAYE line and for migration extracts that have to seed the new system with the right code per employee. The IRD number is the employee's tax identifier and runs to either eight or nine digits. Below these sit the leave balances — annual leave shown in weeks under the 2003 Act (not days, because the entitlement is four weeks of an employee's ordinary working week), sick leave in days, alternative holidays accrued from working public holidays, bereavement leave, family violence leave, and parental-leave-to-date where applicable. The leave-balance block is the part of the payslip where layout drift hits hardest — vendors disagree on whether to show closing balances only or both opening and closing, on whether to break out the alternative-holidays line at all, and on how to label the entitlement-versus-accrual figures within annual leave itself.

One sibling document worth distinguishing at the start is the contractor payment. A person paid via the schedular-payment regime is not on PAYE and does not receive a standard payslip. The withholding mechanics, the documentation, and the extraction problem are different — covered in NZ schedular payments and contractor withholding tax — and conflating the two document types in a single extraction job will pollute both outputs. Confirm whether each person in the source data is an employee on PAYE or a contractor on schedular payments before deciding which extraction schema applies.

---

Verifying the 8% PAYG holiday pay identifiable component on a payslip

If you have searched for the 8% PAYG term, you are almost certainly trying to answer one question: is my payslip's holiday pay actually compliant? The rule has two tests, eligibility and identifiability, and the payslip itself can be read against both.

The first test is eligibility. PAYG is the exception, not the default. The default for almost every NZ employee is leave when taken, where annual leave accrues into a balance and is paid out at the relevant rate when the employee actually takes the leave. Casual employment with genuinely unpredictable hours can qualify for PAYG, and so can a fixed-term role explicitly less than 12 months that is not a disguised permanent agreement. A permanent salaried role does not qualify, regardless of whether the payslip carries an 8% line. If the underlying employment shape does not pass the eligibility test, the issue is not the labelling of the line — it is that PAYG is not lawful at all for that role, and the employer owes leave-when-taken instead.

The second test is identifiability, and this is where reading the actual payslip earns its place. Identifiable in the operational sense means a separately labelled line on the payslip, with its own pay code, paid in each pay cycle the employee earns wages — not a back-of-envelope share of an inflated hourly rate, not a year-end lump sum, not an unlabelled component of the gross figure. The labelling has to be visible. The pay code has to be distinct. The amount has to be the period's gross earnings multiplied by 8% (or more, if the employer pays a higher rate by contract), shown alongside the ordinary-time line, not inside it.

There are three failure modes to recognise. The first is the rolled-up rate — your hourly rate quietly already includes the 8%, with no separate line on the slip and no separate pay code, often presented in casual contracts as "your hourly rate of $X already includes holiday pay". This treatment fails identifiability on its own terms whether or not eligibility is met, and the requirement is read strictly in this respect: a rolled-up rate has been treated as a substantive failure rather than a presentation choice. The second is the year-end lump sum — a single payment in the final pay cycle of the year, or at contract end for a fixed-term role, intended to discharge the holiday-pay obligation in one settlement. This fails identifiability because PAYG must be paid each pay cycle the employee earns wages, not banked and paid as a lump. The third is the eligibility mismatch — the slip carries a labelled "Holiday Pay 8%" line that meets identifiability cleanly, but the employee is on a permanent salaried agreement where PAYG is not lawful at all. In that case the labelling is correct, the calculation is correct, and the entire arrangement is still wrong because the eligibility test fails. The cure is moving to leave when taken, not relabelling the line.

What a compliant 8% line looks like on a payslip is straightforward. The label varies — "Holiday Pay 8%", "8% PAYG", "Annual Leave 8%", "Holiday Pay (PAYG)" are all in current use across vendors — but the line is always separated from the ordinary-time line, has its own pay code visible where the layout surfaces codes, sits inside the gross-earnings block (because PAYG holiday pay is gross earnings for tax purposes), and pays the period's gross earnings multiplied by at least 8%. Read the period's ordinary-time and overtime gross, multiply by 0.08, and the answer should appear as a labelled line. If it does not, you have a finding.

The article does not advise on what to do with that finding — that is legal territory and depends on the contract, the employment history, and the size of the gap. What the Holidays Act does give you, regardless of the route you choose, is a wage-time records request as a starting point. Employers must produce the records on request, and an employee who suspects the 8% line is missing or buried can ask for the period-by-period gross earnings figures the records carry and check the calculation themselves. Where the records confirm a gap, the next step usually involves either a direct conversation with the employer, a referral to a Labour Inspector at MBIE, or — for larger or older underpayments — an underpayment claim with employment-law representation. The point of this section is the diagnostic, not the remedy. Read the slip, apply the eligibility test, apply the identifiability test, and you have your answer.

Mapping BAPW, AWE, OWP, RDP and ADP back to payslip fields for remediation

Holidays Act remediation projects exist because payroll systems have, for a decade or more, calculated leave entitlements using shortcuts the Act does not allow. The remediation engagement recalculates historic leave under the rates the Act actually mandates, produces a per-employee, per-leave-event back-pay figure, and feeds that figure back into a payment cycle. The recalculation methodology — which rate applies to which leave event, what window each rate is calculated over, how the calculations interact when an employee has multiple pay components — is the consultancy product the specialist firms sell. The data layer underneath it is what this section is about. Each rate has specific input requirements, and each requirement maps to specific fields on each historic payslip.

BAPW (Base Annual Pay for Wages) is the annualised base pay an employee is contractually entitled to, used as the baseline reference for some leave-pay calculations. The input is the contractual base wage component as paid each period across the relevant window — usually expressed as the ordinary-time line on each slip, multiplied through to an annual figure using the contracted hours. Allowances and overtime are not part of BAPW; they are extracted into other categories.

OWP (Ordinary Weekly Pay) is the ordinary weekly pay the employee receives in their contracted weekly cycle, used for annual leave taken where this rate exceeds AWE. The inputs are ordinary-time gross per period plus regularly recurring allowances treated as part of ordinary weekly pay, with overtime, one-off bonuses, and irregular allowances excluded. Categorisation here is the most common source of remediation error: a payroll system that pushed everything except PAYE into "Total Earnings" and never broke out the regular-versus-irregular distinction has no way to compute OWP correctly without going back to the underlying payslip data and reapplying the categorisation.

AWE (Average Weekly Earnings) is the trailing 52-week gross earnings divided by 52, used for annual leave taken where this rate exceeds OWP. AWE includes everything OWP excludes — overtime, one-off bonuses, lump sum or extra pay, the lot. The same period gross figures the slip carries, summed across the trailing 52 weeks, divided by 52. The remediation analyst extracting for AWE pulls the full gross-earnings figure per period across the window, with the categories preserved so the same dataset can also feed OWP without re-extraction.

RDP (Relevant Daily Pay) is what the employee would have earned on the specific day the leave is taken, used for sick leave, bereavement leave, alternative holidays, family violence leave, and public holidays. The inputs are the daily-equivalent fields where the payroll system surfaces them, or — more commonly — a derivation from period gross and contracted hours, mapping the period figure to the specific day pattern the employee was scheduled to work. RDP is the rate the Act prefers; ADP is the fallback where RDP cannot be determined or is not practicable.

ADP (Average Daily Pay) is the trailing 52-week gross earnings divided by the paid days in the same window, used where RDP is not practicable. The inputs are the same gross-earnings figure that feeds AWE plus a paid-days count per period — which is where many legacy payslip layouts run thin, because paid-days was historically a payroll-internal field that did not always surface on the slip. Extraction for ADP frequently has to reconcile the gross figure against the contracted-hours and pay-period structure to derive the paid-days count, rather than pulling it directly off the slip.

The categorisation discipline that makes or breaks all five extractions is consistent across them: gross earnings has to be split into the categories each rate uses. Ordinary time, overtime, allowances (with the regular-versus-irregular distinction preserved), commission, lump sum or extra pay, holiday pay paid as leave taken under the leave-when-taken regime, and the 8% PAYG component where applicable — each is its own category, and a remediation extract that produces only a "Total Earnings" column has to be reworked before any of the calculations can run.

The historic-coverage scope of a typical remediation project follows from the calculation windows. The trailing-52-week windows that AWE and ADP require depend on the date of each leave event, so an employee who took leave 18 different times across 7 years generates 18 different 52-week windows that overlap and shift across the period. In practice the extraction usually covers the full employment period rather than a snapshot — 6 to 10 years of historic payslips per employee is typical, and engagements covering 200, 1,000, or 10,000 employees are not unusual in the public-sector remediations that have driven much of the industry's volume. Rekeying at that scale is not viable; specialist remediation teams routinely use an automated payslip data extractor for bookkeepers and remediation analysts to convert the historic PDF roster into the categorised dataset the recalculation engine consumes.

A note on scope, since the remediation industry is its own discipline. Holidays Act remediation has been a multi-billion-dollar story across NZ public and private sector employers for over a decade — police, MBIE itself, hospital networks, councils, supermarkets, large corporates have all paid hundreds of millions in back-pay for miscalculated leave. Large engagements typically involve specialist consultants who own the recalculation methodology. Tonkin + Taylor's published remediation approach, for instance, names the data layer in a single sentence — the team rebuilt AWE, OWP, and RDP for all employees and relevant pay periods using gross and ordinary earnings plus historical contracted hours — and elaborates none of it, because the elaboration is the consulting product. This section fills the gap that sentence leaves: the field-by-field map back to the payslip itself.

Pulling leave balances and YTD totals for a payroll migration

A payroll system migration narrows the extraction problem in one direction and complicates it in another. The narrowing: the migration consultant usually only needs the last payslip per employee, not the full history. The complication: the source system is being decommissioned, the historic PDFs may be the only readable form of certain values, and the new system has to start day one with reconciled opening figures or the rest of the tax year produces wrong PAYE, wrong KiwiSaver, and wrong year-end reporting. Two categories of opening data come off that final slip — closing leave balances by leave type, and YTD totals across earnings, deductions, and tax — and both are usually only available in fully reconciled form on the legacy system's last payslip per employee.

The leave-balance extraction is the more visible of the two. Each leave type carries a closing-balance figure that the new system needs as its opening balance so accruals continue without resetting. For annual leave, the figure is in weeks under the 2003 Act — four weeks of an employee's ordinary working week is the entitlement, and the closing balance reflects what the employee has accrued and not yet taken, in weeks rather than days. For sick leave, the figure is in days — 10 days statutory minimum as of mid-2021, with any contractual top-up shown separately on a compliant slip. Alternative holidays (the lieu-day entitlement that accrues when an employee works on a public holiday) are counted in days — one full day per public holiday worked, regardless of how many hours of the day were worked. Bereavement leave is a per-event entitlement rather than a balance, but where the slip records bereavement-leave-taken-to-date in the leave year, that figure transfers across. Family violence leave (10 days per year since 2019) and parental-leave-to-date where applicable round out the leave-balance block. Each maps to a corresponding field on the new system, and each closing balance has to land on the right field on day one or the new system's accrual logic will spend the next year building on a wrong base.

YTD totals are the second category and the one where extraction errors create the most visible downstream pain. The new system needs YTD gross earnings (categorised the same way the period figures are, so the same categorisation discipline that mattered for remediation matters here too), YTD PAYE, YTD KiwiSaver employee contribution, YTD KiwiSaver employer contribution, YTD ESCT, YTD student loan, YTD child support, YTD payroll giving, and any YTD tax-credit fields the slip surfaces. These figures seed the new system's YTD position so that cumulative-PAYE calculations across the rest of the tax year stay correct, IRD payday-filing reports reconcile to the employee's total tax-year position, and the year-end summaries (IR348, employer monthly schedule, IR345 totals) reconcile across the cutover. A migration that drops or misallocates the YTD figures forces the new system to recalculate cumulative PAYE from a wrong base for every remaining pay cycle in the year — usually noticed first when an employee receives an unexpectedly large refund or shortfall at year-end, by which point the fix is reconciliation rather than prevention.

The disambiguation trap that catches more migration extractions than it should is the period-versus-YTD column read. Migration consultants extract YTD figures from the last payslip; remediation analysts extract period figures from every payslip in the window. Both columns sit on the same slip, both labelled some variant of "This Pay" / "YTD", and the labels vary across vendors. Reading the wrong column corrupts every downstream calculation — the migration consultant who reads period figures into YTD fields ships an employee into the new system with a YTD position that reflects only the final fortnight, and the remediation analyst who reads YTD figures into period fields produces gross earnings that double, triple, and quadruple across the trailing 52-week window. Confirm the labelling per layout before bulk extraction, especially across mixed legacy systems where one vendor labels the period column "Current" and another labels it "Period" and a third uses unlabelled columns whose meaning is implied by position alone.

A reconciliation check worth running before the cutover lands is the closing-balance reconciliation against prior payslips. The closing leave balances on the last payslip should reconcile to the cumulative leave taken and accrued during the year on the same employee's prior payslips — opening balance, plus accruals, minus leave taken, equals closing balance. Where they do not reconcile — usually because of mid-year leave-policy changes, anniversary-rollover bugs in the legacy system, unrecorded leave taken, or remediation adjustments applied to the balance without corresponding payslip entries — the migration consultant carries the reconciliation finding into the cutover plan rather than silently accepting the closing figure. Some discrepancies are routine (a known anniversary-rollover bug the legacy system has had for years); some are remediation findings that overlap with a separate Holidays Act engagement on the same employer. Either way, surfacing the reconciliation before cutover lets the receiving system start with documented opening figures rather than mystery numbers.

The mechanics of bulk extraction across an entire roster are themselves a known pattern — converting payroll PDFs to Excel at scale covers the cross-system shape independent of jurisdiction, and the same field discipline applies whether the source layout is from Smartly, FlexiTime, iPayroll, Datacom Datapay, IMS Payroll, Crystal Payroll, MYOB IMS, Xero Payroll, or a legacy in-house system that the migration is the reason to retire. The extraction schema this article maps — gross categorised, deduction stream broken out with the employer-cost lines flagged, leave balances by type, YTD figures aligned to the period figures — is the same schema for every vendor. Only the visual layout each schema field is read from differs, which is the cross-layout problem the next section addresses.

---

Working across Smartly, FlexiTime, iPayroll, Datacom and the rest of the NZ layout reality

Any real NZ payslip extraction project — whether the work is remediation, migration, or a roster-wide audit — meets the layout problem before the field problem. A typical roster carries payslips from Smartly, FlexiTime, iPayroll, Datacom Datapay, IMS Payroll, Crystal Payroll, MYOB IMS, Xero Payroll, ADP, and at least two or three legacy in-house formats kept for historical employees and never retired. Each renders the same NZ payslip semantics — the gross-earnings block, the deduction stream with employer-cost lines flagged, the leave-balance block, the period-and-YTD columns — in a different visual structure. The fields are the same; the labels, positions, groupings, and visual hierarchy are not.

The operational consequence is that a per-vendor template approach scales poorly past a handful of layouts. Every legacy in-house format has to be handled separately, every layout change a vendor has shipped over the period being extracted is its own template, and the marginal cost of adding the next legacy format never goes away. Bulk extraction across 30+ layouts in a single roster — the typical shape of a real Holidays Act remediation or a multi-entity migration — is a structurally different problem than extracting from a single known vendor format. The volume that drives most NZ remediation work makes the per-vendor template approach unworkable; the time spent maintaining templates exceeds the time that would have been spent rekeying.

The PDF-quality dimension layers on top of the layout dimension. Payslips from currently active vendors are usually native PDFs with extractable text underneath the visual rendering — a layout shift in the PDF still leaves the underlying text addressable. Payslips from decommissioned legacy systems are often something worse: scanned images of slips that were originally printed, photocopies of those scans, or photo-quality copies that an employee retained in some unstructured archive. The oldest years of a remediation project covering the full 2003-Act-era window routinely include scanned-image PDFs that have to be read as images, with the same field schema applied. Extraction has to handle native and scanned reliably, ideally without the practitioner having to triage the input first.

The approach that survives both dimensions is to define a single extraction schema once — the field map this article has walked, with gross earnings categorised, the deduction stream broken out, the employer-cost lines flagged, the leave balances by type, and the period-and-YTD columns separated — and let an extraction layer that interprets layouts learn the schema rather than learn each vendor's template. Practitioners describe what they need (the categorisation a remediation engine consumes, or the closing balances and YTD totals a migration cutover consumes), the extraction layer reads each slip into the same schema regardless of vendor, and the output is a single structured dataset across the entire mixed-format roster. A parallel example from another country's payslip ecosystem is worth noting for anyone running similar projects elsewhere: extracting Irish payslip data into spreadsheets covers the same cross-vendor schema discipline applied to a different statutory regime.

The schema-as-prompt approach is how AI-powered payslip data extraction across mixed payroll layouts handles this in practice — payroll documents are the second-strongest use case for the platform after invoices. A remediation team or migration consultant describes the schema once in natural language (the categorisation, the closing balances, the YTD column read), uploads a mixed-format batch of up to 6,000 files spanning native PDFs and scanned legacy archives, and downloads a structured Excel, CSV, or JSON file with the same schema applied across every slip in the roster. The output is consistent because the schema is consistent, and the schema is the prompt rather than a per-vendor template.

The honest scope boundary is worth restating to close. The article has walked the payslip extraction layer for the three audiences this work serves — the 8% PAYG identifiability test for the employee verifying their own slip, the BAPW, AWE, OWP, RDP, and ADP field map for the Holidays Act remediation analyst, and the leave-balance and YTD field map for the payroll migration consultant — and the cross-layout extraction approach for the project shape that real work takes. The recalculation engine the remediation team feeds, the cutover plan the migration team executes, and the legal advice an employee with an 8% identifiability finding may need next belong to specialist disciplines this article does not pretend to cover. The extraction layer is what feeds them all, and that is the layer this article maps.