Migrate to the v2 payslip schemas

Summary

Use this guide if you send au.payslip.v1 or nz.payslip.v1. For a new integration, go to the payslip data reference.

v2 accepts printed text in some non-PII fields: award in Australia, and pay_cycle, tax_code and employment_type in New Zealand. Keep employee PII out of these fields. The API checks the format of these fields, not whether their content identifies a person. Send identifying details only in the encrypted PII payload.

Change	Action
Amounts, rates and quantities are decimal strings	Send each one as a plain decimal string.
Amount fields have new names	Remove the _cents suffix.
currency accepts each ISO 4217 code	Send currency on each payslip.
Australia: fund_abn is removed	Remove fund_abn from each superannuation line.
New Zealand: payroll codes and KiwiSaver	Send the printed codes. Send each KiwiSaver value as a separate field.
New fields	Send award, rate and ytd_amount if your payslip prints them.

1. Amounts, rates and quantities are decimal strings

Why: Whole cents cannot hold a rate such as $47.3684. A decimal string keeps the exact value.

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

• 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.
• Every field accepts a negative value, units and hours included.

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

v1 and v2

v1   "gross_cents": 360000
v2   "gross": "3600.00"

v1   "rate_cents": 4737
v2   "rate": "47.3684"

v1   "units": 76
v2   "units": "76"

Take each number from your payslip data. Do not convert a v1 integer back to a decimal. Refer to Amounts, rates and quantities.

2. Amount fields have new names

Why: The values are not in cents, so the _cents suffix is removed.

Action: Rename each field in the tables below. A v1 field name in a v2 payload is a validation error. Fields that the tables do not show keep their v1 names.

Australia

v1 field	v2 field
gross_cents	gross
paygw_cents	paygw
net_cents	net
ytd_gross_cents	ytd_gross
ytd_paygw_cents	ytd_paygw
taxable_gross_cents	taxable_gross
stsl_withholding_cents	stsl_withholding
annual_rate_cents	annual_rate
reimbursements_cents	reimbursements
hourly.ordinary_rate_cents	hourly.ordinary_rate
hourly.amount_cents	hourly.amount
earnings[].amount_cents	earnings[].amount
earnings[].rate_cents	earnings[].rate
salary_sacrifice[].amount_cents	salary_sacrifice[].amount
deductions[].amount_cents	deductions[].amount
superannuation[].amount_cents	superannuation[].amount
ytd.taxable_cents	ytd.taxable
ytd.super_cents	ytd.super
ytd.non_taxable_cents	ytd.non_taxable
ytd.post_tax_deductions_cents	ytd.post_tax_deductions
ytd.reimbursements_cents	ytd.reimbursements

New Zealand

v1 field	v2 field
gross_cents	gross
paye_cents	paye
net_cents	net
ytd_gross_cents	ytd_gross
ytd_paye_cents	ytd_paye
annual_rate_cents	annual_rate
reimbursements_cents	reimbursements
earnings_not_liable_for_acc_cents	earnings_not_liable_for_acc
employee_share_scheme_cents	employee_share_scheme
prior_period_gross_adjustment_cents	prior_period_gross_adjustment
prior_period_paye_adjustment_cents	prior_period_paye_adjustment
payroll_donation_tax_credit_cents	payroll_donation_tax_credit
student_loan_cents	student_loan
slcir_cents	slcir
slbor_cents	slbor
child_support_cents	child_support
kiwisaver.employee_deduction_cents	kiwisaver_employee_deduction
kiwisaver.employee_rate_basis_points	kiwisaver_employee_rate
kiwisaver.employer_contribution_cents	kiwisaver_employer_contribution
kiwisaver.esct_cents	esct
leave_balances.*.value	leave_balances.*.amount

3. currency accepts each ISO 4217 code

Action: Send currency on each v2 payslip. The field is required.

• Use the three-letter alphabetic code of the payslip currency, for example AUD or NZD.
• v2 accepts each current ISO 4217 currency code, not only the ten v1 codes. 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.

Currency

v2   "currency": "AUD"

4. Australia: fund_abn is removed

Why: The ABN of a self-managed super fund can identify the employee. A 14-digit USI contains the ABN of the fund.

Action: Remove fund_abn from each superannuation line. The API rejects a record that contains it. Keep usi.

5. New Zealand: payroll codes and KiwiSaver

Payroll codes

Why: v2 stores tax_code, pay_cycle and employment_type as the payslip prints them.

Action: Remove your mapping step. Send the printed text.

Payroll codes

v1   "pay_cycle": "fortnightly", "tax_code": "M SL", "employment_type": "permanent"
v2   "pay_cycle": "Fortnightly", "tax_code": "MSL", "employment_type": "Permanent"

KiwiSaver

Why: Each KiwiSaver value is a separate field, so you can send only the values that the payslip prints.

Action: Replace the kiwisaver object with the four fields below. Send the rate as a percentage without the percent sign, not in basis points.

KiwiSaver

v1   "kiwisaver": {
       "employee_deduction_cents": 10500,
       "employee_rate_basis_points": 350,
       "employer_contribution_cents": 10500,
       "esct_cents": 1837
     }

v2   "kiwisaver_employee_deduction": "105.00",
     "kiwisaver_employee_rate": "3.5",
     "kiwisaver_employer_contribution": "105.00",
     "esct": "18.37"

6. New fields

Send each one that your payslip prints.

• award (Australia): the award or agreement line, as one string. Refer to The award field.
• rate on an Australian superannuation line.
• ytd_amount on an earnings, salary_sacrifice, deductions or superannuation line.
• other as an earnings type, for a pay code that has no other type. Refer to Itemising earnings.