New Zealand payslip schema

Set schema to nz.payslip.v2 and send the payslip data in payslip_non_pii. The schema is closed to undocumented fields, but accepts printed strings. Your integration must keep employee PII out of every non-PII field; the API does not detect PII in accepted string values. Put identifying information in the encrypted PII payload instead.

Conventions

• ✓ Send each field that your payslip shows.
• ✓ Send each amount, rate and quantity as a decimal string. Refer to Amounts, rates and quantities.
• ✓ Send currency on each payslip. Refer to Currency.
• ✓ Send tax_code, pay_cycle and employment_type as printed text. Send what the payslip shows. Do not map these values to a code set.
• ✓ Write each date as YYYY-MM-DD.

The earnings, allowance and deduction code sets below use the Inland Revenue Employment Information categories.

Source: Inland Revenue, Payday filing

Amounts, rates and quantities

Send each amount, rate and quantity as a JSON string that contains a plain decimal number.

An amount

"gross": "3600.00"

• ✓ Use digits and a decimal point. Put a minus sign at the start of a negative value.
• ✓ Do not send a thousands separator, currency symbol, bracket, unit, plus sign or exponent.
• ✓ Send a string, not a JSON number.
• ✓ Any number of decimal places is valid. The API stores the string as you send it. "1.50" and "1.5" are different values.
• ✓ Every field accepts a negative value, hours and quantities included.

The SDKs check the format of each number before they send the request.

From the printed payslip to the string

printed          send
$3,600.00        "3600.00"
3,600.00         "3600.00"
(123.45)         "-123.45"
NIL              "0.00"
-                "0.00"
76.00 hrs        "76"
12%              "12"
47.3684          "47.3684"

Send a nil line as zero, for example "0.00".

A rate of four decimal places, and a nil line

{
  "period_start": "2026-03-21",
  "period_end": "2026-04-03",
  "payment_date": "2026-04-04",
  "currency": "AUD",
  "gross": "3600.00",
  "paygw": "752.00",
  "net": "2848.00",
  "base_rate": {
    "amount": "47.3684",
    "per": "hour"
  },
  "earnings": [
    {
      "type": "ordinary",
      "units": "76",
      "rate": "47.3684",
      "amount": "3600.00"
    },
    {
      "type": "overtime",
      "amount": "0.00"
    }
  ]
}

Currency

Send currency on each payslip. Use the three-letter alphabetic code of the payslip currency, for example AUD or NZD. Write the code in capital letters.

The API accepts each current ISO 4217 currency code. It does not accept fund codes or codes that have no minor unit, for example XAU, XTS and XXX. SIX, the ISO 4217 maintenance agency, publishes the list on its data standards page.

The currency does not set the number of decimal places in an amount.

Common mapping mistakes

These mistakes put a correct figure in the wrong field.

1. Family violence leave is ordinary pay

Do not map paid family violence leave to a leave type. The schema has no code for it, and you must not put it in other_paid_leave. Include the amount in ordinary pay.

A payslip with paid family violence leave

Ordinary hours       2,400.00
Family violence        600.00     -> earnings: [{ type: "ordinary", amount: "3000.00" }]
Gross                3,000.00        (one ordinary line of 3,000.00, with no leave line)

2. Each statutory deduction has its own field

PAYE, student loan, child support, KiwiSaver and ESCT each have their own field. deductions[] holds the other post-tax deductions.

A payslip that prints everything under Deductions

Gross                3,000.00
Deductions
  PAYE                   660.00   -> paye: "660.00"
  Student loan           100.00   -> student_loan: "100.00"
  KiwiSaver 3.5%         105.00   -> kiwisaver_employee_deduction: "105.00"
  Child support           50.00   -> child_support: "50.00"
  Health fund             35.00   -> deductions: [{ type: "other_post_tax", amount: "35.00" }]
Net                  2,050.00

Send paye on every payslip. Send "0.00" when the pay has no PAYE.

3. An employee share scheme benefit has its own field

Send it as employee_share_scheme, and not in gross or an earnings line.

4. A KiwiSaver rate is the printed rate

Send the rate as a decimal string without the percent sign, for example "3.5" for 3.5%.

Source: Inland Revenue, KiwiSaver for employers

Core fields

Each registration must contain these six fields.

Field	Type	Meaning
period_end	date	Last day of the pay period (YYYY-MM-DD). Must not be before period_start when you send it.
payment_date	date	The day that you pay the employee.
currency	string	The ISO 4217 code of the payslip currency, for example NZD. Refer to Currency.
gross	decimal string	Taxable gross earnings and schedular payments. Does not include an employee share scheme benefit.
paye	decimal string	PAYE, or tax on schedular payments. Its own field, never also a deductions line.
net	decimal string	Net pay, as shown on the payslip.

The minimum payload

{
  "period_end": "2026-04-19",
  "payment_date": "2026-04-22",
  "currency": "NZD",
  "gross": "3000.00",
  "paye": "660.00",
  "net": "2135.00"
}

Other fields

Send each of these fields that your payslip shows.

Field	Type	Meaning
period_start	date	First day of the pay period (YYYY-MM-DD).
ytd_gross	decimal string	Year-to-date gross, including this pay run.
ytd_paye	decimal string	Year-to-date PAYE, including this pay run.
pay_cycle	string	The pay cycle as your payslip prints it.
tax_code	string	The tax code as your payslip prints it.
employment_type	string	The employment type as your payslip prints it.
hours_paid	decimal string	The hours that you paid the employee for this paydate.
base_rate	object	A base rate that is not on an earnings line. Refer to Base rate.
earnings_not_liable_for_acc	decimal string	Earnings that the ACC earners’ levy does not apply to.
earnings	array	Itemisation of gross. See the code sets below.
employee_share_scheme	decimal string	An employee share scheme benefit. Not part of gross.
prior_period_gross_adjustment	decimal string	A correction to the gross of a prior period.
prior_period_paye_adjustment	decimal string	A correction to the PAYE of a prior period.
payroll_donation_tax_credit	decimal string	The payroll donation tax credit.
student_loan	decimal string	Standard student loan repayment.
slcir	decimal string	Student loan deduction that the Commissioner directs.
slbor	decimal string	Extra student loan deduction that the borrower asks for.
child_support	decimal string	Child support deduction.
kiwisaver_employee_deduction	decimal string	The KiwiSaver deduction from the employee.
kiwisaver_employee_rate	decimal string	The employee contribution rate, as the payslip prints it.
kiwisaver_employer_contribution	decimal string	The net employer contribution, exclusive of ESCT.
esct	decimal string	Employer superannuation contribution tax.
deductions	array	Post-tax deduction lines. Each line has a type and an amount, and can have a year-to-date amount.
reimbursements	decimal string	Non-taxable reimbursing payments. Not part of gross.
leave_balances	object	The leave entitlement of the employee. Each balance has an amount and a unit.
ytd	object	Other year-to-date totals. See the field list below.

Code sets

tax_code, pay_cycle and employment_type have no code set. Send the text that your payslip prints.

earnings[].type

Value	Meaning
ordinary	Ordinary pay.
overtime
penal_rate
piece_work
bonus_commission
extra_pay	An Inland Revenue lump sum (extra pay).
schedular_payment	A schedular payment.
directors_fees
pay_as_you_go_holiday_pay	The 8% holiday pay that you pay with each pay. Not leave that the employee takes.
leave_compensation_payment	The Employment Leave Act 2026 replacement for the 8%.
annual_holiday_cash_out	Annual holiday that the employee cashes up.
alternative_holiday_cash_out
holiday_pay_on_termination	Holiday pay that you pay when employment ends.
other	A pay code that fits no other type.
paid_leave	Leave that the employee takes. Carries a leave_type.
allowance	A taxable allowance. Carries an allowance_type.

Send the number without the unit, for example "76" for 76.00 hrs. The schema has no unit field.

earnings[].leave_type

For leave that the employee takes. There is no family violence code. See the mapping mistakes above. A public holiday uses public_holiday, whether or not the employee worked it. A day in lieu shows in leave_balances.alternative.

Value	Meaning
annual_holiday	Annual holiday that the employee takes.
public_holiday
alternative_holiday
sick_leave
bereavement_leave
other_paid_leave	Each other kind of paid leave that the employee takes.

earnings[].allowance_type

For a taxable allowance. A non-taxable reimbursing payment goes in reimbursements.

Value	Meaning
meal
travel
accommodation
vehicle
phone
tools
uniform
on_call
shift
first_aid
higher_duties
qualification
other	Each other taxable allowance.

deductions[].type

Value	Meaning
union_fees
payroll_donation	The donation. The tax credit has its own field.
attachment_order	A District Court attachment order.
ir_arrears	An Inland Revenue arrears deduction notice.
other_post_tax	Each other post-tax deduction, for example a health fund.

Base rate

Send base_rate if the payslip shows a base rate that is not on an earnings line, for example “Base Pay Rate: $450.00 Per Day”.

• ✓ amount is the rate, as a decimal string.
• ✓ per is the period of the rate. It accepts hour, day, week, fortnight, month or year.
• ✓ Send units, rate and amount on the ordinary earnings lines.

A daily base rate and its earnings line

"base_rate": { "amount": "450.00", "per": "day" },
"earnings": [
  { "type": "ordinary", "units": "10", "rate": "450.00", "amount": "4500.00" }
]

base_rate replaces hourly and annual_rate. If you send them, change to base_rate.

Leave balances

leave_balances holds leave entitlement, and not pay. Each balance has an amount and a unit. Send the unit that the payslip prints.

leave_balances

{
  "annual": { "amount": "4", "unit": "weeks" },
  "annual_accrued_this_period": { "amount": "6.15", "unit": "hours" },
  "sick": { "amount": "10", "unit": "days" },
  "alternative": { "amount": "8", "unit": "hours" }
}

The unit can be hours, days or weeks. There is no family violence balance.

Year-to-date totals

Send each year-to-date total that your payslip shows. ytd_gross and ytd_paye hold the principal totals. The ytd object holds the totals below. ytd_amount on an earnings or deductions line holds the total for that line.

Field	Type	Meaning
student_loan	decimal string	Year-to-date student loan repayments.
kiwisaver_employee	decimal string	Year-to-date KiwiSaver employee deductions.
kiwisaver_employer	decimal string	Year-to-date net KiwiSaver employer contributions, exclusive of ESCT.
child_support	decimal string	Year-to-date child support deductions.
non_taxable	decimal string	Year-to-date non-taxable payments.
post_tax_deductions	decimal string	Year-to-date post-tax deductions.
reimbursements	decimal string	Year-to-date reimbursing payments.

Each total includes the pay run that you register.

What is not carried

• Personal data. Send the name, the IRD number, the address and the bank details in the encrypted PII.
• Paid family violence leave, in each form. There is no leave code, and no balance.
• A KiwiSaver scheme identifier. There is no field for one.
• The child support variation code. The deduction carries its amount only.

Encrypted PII fields

Send the personal details on the payslip in the encrypted PII, not in payslip_non_pii. New Zealand payslips use the NZ2 format. For the string format, the rules for every format and encryption, refer to PII and encryption.

NZ2: all fields populated

NZ2|Ana Leota|123-456-789|Senior Developer|Engineering|Example Software Limited|12-3456-0123456-00|A Leota|12 Example Street, Te Aro, Wellington 6011

#	Field	Example
1	employee_name	Ana Leota
2	ird_number	123-456-789
3	position	Senior Developer
4	department	Engineering
5	employer_name	Example Software Limited
6	account_number	12-3456-0123456-00
7	account_name	A Leota
8	address	12 Example Street, Te Aro, Wellington 6011

The encrypted PII contains one bank account. Cash and cheque are not bank accounts.

• ✓ Send the bank account that receives the largest part of the pay. For example, if the payslip shows 75% of the pay in cash and 25% to a bank account, send the bank account.
• ✓ If two or more bank accounts receive equal quantities of the pay, send the first of these accounts that the payslip shows.
• ✓ If no bank account receives pay, send empty bank fields.

Complete examples

A salaried employee who is paid each two weeks, with KiwiSaver and a student loan.

Salaried, fortnightly

{
  "period_start": "2026-04-06",
  "period_end": "2026-04-19",
  "payment_date": "2026-04-22",
  "currency": "NZD",
  "pay_cycle": "Fortnightly",
  "tax_code": "M SL",
  "employment_type": "Permanent",
  "hours_paid": "80",
  "gross": "3000.00",
  "paye": "660.00",
  "net": "2135.00",
  "ytd_gross": "3000.00",
  "ytd_paye": "660.00",
  "earnings": [
    {
      "type": "ordinary",
      "units": "76",
      "rate": "37.50",
      "amount": "2850.00"
    },
    {
      "type": "overtime",
      "units": "4",
      "rate": "37.50",
      "amount": "150.00"
    }
  ],
  "student_loan": "100.00",
  "kiwisaver_employee_deduction": "105.00",
  "kiwisaver_employee_rate": "3.5",
  "kiwisaver_employer_contribution": "105.00",
  "esct": "18.37",
  "leave_balances": {
    "annual": {
      "amount": "4",
      "unit": "weeks"
    },
    "sick": {
      "amount": "10",
      "unit": "days"
    }
  }
}

A casual employee who gets 8% holiday pay with each pay. The 8% is an earnings line, and not leave.

Casual, with pay-as-you-go holiday pay

{
  "period_start": "2026-04-06",
  "period_end": "2026-04-19",
  "payment_date": "2026-04-22",
  "currency": "NZD",
  "pay_cycle": "Ad hoc",
  "tax_code": "M",
  "employment_type": "Casual",
  "hours_paid": "32",
  "gross": "1036.80",
  "paye": "186.62",
  "net": "850.18",
  "earnings": [
    {
      "type": "ordinary",
      "units": "32",
      "rate": "30.00",
      "amount": "960.00"
    },
    {
      "type": "pay_as_you_go_holiday_pay",
      "amount": "76.80"
    }
  ]
}