Australian payslip schema

Set schema to au.payslip.v2 and send the payslip data in payslip_non_pii. The schema is closed to undocumented fields, but some defined fields accept printed strings. Closed does not mean free-text-free or guarantee that values contain no personal data. Your integration must keep employee PII out of every non-PII field; the API does not detect PII in accepted string values.

Conventions

• ✓ Send each field that your payslip shows.
• ✓ Send pay_frequency from the pay calendar in your payroll system. Refer to Pay frequency.
• ✓ Send each amount, rate and quantity as a decimal string. Refer to Amounts, rates and quantities.
• ✓ Send currency on each payslip. Refer to Currency.
• ✓ Keep personal data out of every field. Send the employee name, the address and the bank details in the encrypted PII.
• ✓ Write each date as YYYY-MM-DD.

A payslip in New Zealand uses nz.payslip.v2, which has a different field list. Refer to the nz.payslip.v2 schema.

The code sets below use the ATO Single Touch Payroll Phase 2 categories.

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. PAYG withholding is not a deduction

Send PAYG withholding in paygw, also when the payslip prints it as “Tax” or under “Deductions”. deductions[] is for post-tax deductions only.

A payslip that prints tax under Deductions

Gross                3,600.00
Deductions
  PAYG withholding     752.00     -> paygw: "752.00"
  Health fund           45.50     -> deductions: [{ type: "other_post_tax", amount: "45.50" }]
Net                  2,802.50

2. There are two gross figures

gross is the gross before salary sacrifice. Send the taxable earnings that the payslip shows as taxable_gross.

Which number goes where

Gross (before sacrifice)   3,600.00   -> gross:         "3600.00"
Salary sacrifice to super    200.00   -> salary_sacrifice[].amount: "200.00"
Taxable gross (printed)    3,400.00   -> taxable_gross: "3400.00"

3. A number field takes no formatting

Send the number only. Remove the currency symbol, the separators and the unit.

Send a plain decimal string

"gross": "3600.00"       valid
"gross": "$3,600.00"     rejected: no currency symbol
"gross": "3,600.00"      rejected: no thousands separator
"gross": 3600.00         rejected: send a string

4. Free text becomes an enum

The schema has no field for a pay-code name. Map each pay code to its STP category, for example “Salary” to ordinary. If a pay code has no category, refer to Itemising earnings.

The record contains no pay-code names

"Salary"                 -> { type: "ordinary",   amount: "3040.00" }
"Time and a half"        -> { type: "overtime",   amount: "240.00" }
"Tool allowance"         -> { type: "allowance",  allowance_type: "tools", amount: "40.00" }
"Annual Leave Taken"     -> { type: "paid_leave", leave_type: "other_paid_leave", amount: "280.00" }

5. The STP Phase 2 Gross amount is not gross

gross is the total of the earnings lines. Send each pay code in the STP Phase 2 Gross amount as an ordinary line. Send each other pay code as its own line, and include it in gross.

STP Phase 2 amounts on one payslip

Gross (STP Phase 2)
  Ordinary hours         2,800.00   -> { type: "ordinary",   amount: "2800.00" }
  Shift penalty            240.00   -> { type: "ordinary",   amount: "240.00" }
Overtime                   240.00   -> { type: "overtime",   amount: "240.00" }
Allowance (TD)              40.00   -> { type: "allowance",  allowance_type: "tools", amount: "40.00" }
Paid leave (O)             280.00   -> { type: "paid_leave", leave_type: "other_paid_leave", amount: "280.00" }
Total                    3,600.00   -> gross: "3600.00"

Validation error reference

If the API rejects a payload, it returns VALIDATION_FAILED and lists the applicable fields in field_errors. The table shows each message from the payslip schema and the usual cause of that message.

Message	Usual cause
Unrecognized key: “…”	The payload contains a field that is not in the schema. The schema is closed. Remove the field. A leave balance, a fund name and an award code each cause this message.
Invalid discriminator value. Expected ‘paid_leave’ | ‘allowance’ | …	The payload contains a pay-code name in the earnings type field. Map the pay code to one of the ten types.
must be a decimal number, for example 1234.56	An amount, rate or quantity is empty, or it contains a separator, a currency symbol, a bracket, a unit or a word. Send a plain decimal string.
Invalid input: expected string, received number	An amount, rate or quantity is a JSON number. Send it as a string.
Invalid input: expected string, received object	An amount, rate or quantity is an object. Send it as a string.
Invalid input: expected string, received undefined	A required amount is missing, for example net. Add it.
Too small: expected string to have >=1 characters	A text field, for example award, is an empty string. Send the printed text, or remove the field.
currency must be an ISO 4217 currency code	The currency field is missing, or it does not contain an accepted ISO 4217 code. Send a code such as AUD or NZD.
USI must be a fund ABN plus 3-digit product suffix (14 digits) or a SPIN	The usi field contains an 11-digit ABN. Send contributions to a self-managed fund with no fund identifier.
period_end must not be before period_start	period_end is before period_start. Examine the two dates.
other_category is required on an ‘other’ allowance	An allowance of the type other has no descriptor. Select one of the six other_category values.
other_category applies only to allowance_type ‘other’	The payload contains a descriptor on an allowance that is not of the type other.
<field> must be YYYY-MM-DD	The date is not in ISO format, or the date does not exist. The API rejects 2026-02-31 and 31/03/2026.

Core fields

Each payslip requires these 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 the employee is paid.
currency	string	The ISO 4217 code of the payslip currency, for example AUD. Refer to Currency.
gross	decimal string	Total gross before salary sacrifice. The earnings lines add up to this amount.
paygw	decimal string	PAYG withholding, including the tax withheld from each ETP. Its own field, never also a deductions line.
net	decimal string	Net pay, as shown on the payslip.

A payload that contains only the core fields is valid. Use it only for a payslip that shows no other data.

A minimal payslip_non_pii

{
  "period_end": "2026-04-03",
  "payment_date": "2026-04-04",
  "currency": "AUD",
  "gross": "3600.00",
  "paygw": "752.00",
  "net": "2848.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 across the financial year, including this pay run.
ytd_paygw	decimal string	Year-to-date PAYG withholding, including this pay run.
pay_frequency	enum	One of the values in Pay frequency.
employment_basis	enum	STP2 employment basis. Independent of engagement_type.
engagement_type	enum	One of permanent or fixed_term. A Fair Work notion with no STP2 counterpart.
award	string	The award or agreement line as your payslip prints it.
base_rate	object	A base rate that is not on an earnings line. Refer to Base rate.
taxable_gross	decimal string	The taxable earnings that the payslip shows.
stsl_withholding	decimal string	The HELP/STSL component printed on the payslip. Already inside paygw.
earnings	array	Itemisation of gross.
salary_sacrifice	array	Salary sacrifice lines. Each line has a type and an amount, and can have a year-to-date amount.
deductions	array	Post-tax deduction lines. Each line has a type and an amount, and can have a year-to-date amount.
superannuation	array	Superannuation contribution lines. Each line has a contribution type and amount. It can also have a rate, year-to-date amount and USI.
reimbursements	decimal string	Non-taxable reimbursements. Not part of gross.
ytd	object	Further year-to-date totals: taxable, super, non_taxable, post_tax_deductions, reimbursements.

The award field

Send the award or agreement line as the payslip prints it, with the classification, as one string.

Examples of a printed award line

"Clerks - Private Sector Award 2020 Level 3"
"Manufacturing and Associated Industries Award 2020 C10"
"Example Software Pty Ltd Enterprise Agreement 2024"
"Award free"

Keep personal data out of this field. An agreement title contains the name of the employer. It must not contain the name of the employee.

STP Phase 2 to au.payslip.v2

This table shows where to send each STP Phase 2 category in au.payslip.v2. Each earnings[] line is part of gross.

STP2 category	Send as	Refer to
Gross	earnings[] type ordinary. Send one line for each pay code.	Mapping mistake 5
Paid leave (C, U, P, W, A, O)	earnings[] type paid_leave, with leave_type	Paid leave
Allowances (CD, AD, LD, MD, RD, TD, KN, QN, OD)	earnings[] type allowance, with allowance_type. Add other_category for OD.	Allowances
Overtime	earnings[] type overtime	Earnings line types
Bonuses and commissions	earnings[] type bonus_commission	Earnings line types
Directors’ fees	earnings[] type directors_fees	Earnings line types
Community Development Employment Projects (CDEP) payments	earnings[] type other	Earnings line types
Exempt foreign employment income	earnings[] type other	Earnings line types
Lump sum A (R, T), B, D, E	earnings[] type lump_sum, with lump_sum_type	Lump sums
Lump sum W	earnings[] type return_to_work	Lump sums
ETP (R, O, S, P, D, N, B, T)	earnings[] type etp, with etp_type and etp_component. Send one line for each component.	Employment termination payments
Salary sacrifice (S, O)	salary_sacrifice[] type super (S) or other (O)	Salary sacrifice, Mapping mistake 2
PAYG withholding	paygw. Include the tax withheld from each ETP.	Core fields
Deductions (F, W, D, G)	deductions[], with type	Deductions
Employer superannuation	superannuation[], with contribution_type	Superannuation contributions
Employment basis (F, P, C, L, V, D, N)	employment_basis	Employment basis
A pay code with no STP2 category	earnings[] type other	Itemising earnings

Code sets

Map your existing Single Touch Payroll Phase 2 categories to the accepted values below. PAYG withholding has its own field. deductions[] contains post-tax deductions only.

Earnings line types

Each earnings[] line has a type and an amount. A line can also contain units, rate and ytd_amount. Four types have additional codes. A line cannot contain the codes of another type.

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

type	Meaning
ordinary	Ordinary hours.
overtime	Overtime.
bonus_commission	Bonuses and commissions.
directors_fees	Directors’ fees.
return_to_work	Return-to-work payments.
other	A pay code that fits no other type.
paid_leave	Paid absence. Carries a leave_type from the leave set below.
allowance	Allowance. Carries an allowance_type from the allowance set below.
lump_sum	Lump sum A, B, D or E. Carries a lump_sum_type from the lump sum set below.
etp	Employment termination payment. Carries an etp_type and an etp_component. Refer to the ETP section below.

Paid leave

Use these values in leave_type on a paid_leave line.

leave_type	STP2 code	Meaning
cash_out_in_service	C	Leave cashed out while still employed.
unused_on_termination	U	Unused leave paid out on termination.
paid_parental	P	Paid parental leave.
workers_compensation	W	Absence paid under workers compensation.
ancillary_defence	A	Ancillary and defence leave.
other_paid_leave	O	The ATO general code: annual, personal, long service, RDO, TOIL, and each other paid absence.

ATO reference: STP Phase 2 reporting quick reference guide

Lump sums

Send a lump_sum_type on each lump_sum line. Use one of these values. Send lump sum W as a return_to_work line.

lump_sum_type	STP2 code	Meaning
a_redundancy	R	Lump sum A, paid for genuine redundancy, invalidity or an early retirement scheme.
a_other	T	Lump sum A, paid for other reasons.
b	B	Lump sum B.
d	D	Lump sum D.
e	E	Lump sum E.

Employment termination payments

Send an etp_type on each etp line. Use one of these values.

etp_type	STP2 code	Meaning
redundancy	R	Genuine redundancy, invalidity, an early retirement scheme, or compensation for personal injury, unfair dismissal, harassment or discrimination.
other	O	A life benefit for other reasons.
redundancy_split	S	A later payment of a type R ETP, in a later financial year.
other_split	P	A later payment of a type O ETP, in a later financial year.
death_dependant	D	Death benefit to a dependant.
death_non_dependant	N	Death benefit to a non-dependant.
death_non_dependant_split	B	A later payment of a type N ETP, in a later financial year.
death_trustee	T	Death benefit to the trustee of a deceased estate.

Send an etp_component on each etp line. Use taxable or tax_free. Send each component of an ETP as its own etp line.

Include the tax withheld from each ETP in paygw.

ATO reference: When an employee transfers or leaves

Allowances

Use these values in allowance_type on an allowance line.

allowance_type	STP2 code	Meaning
cents_per_km	CD	Cents-per-kilometre allowance.
award_transport	AD	Award transport payments.
laundry	LD	Laundry allowance.
overtime_meal	MD	Overtime meal allowance.
travel	RD	Travel allowance.
tools	TD	Tools allowance.
tasks	KN	Task allowance.
qualifications	QN	Qualification allowance.
other	OD	This type requires other_category. No other type accepts other_category.

Send other_category on each allowance of the type other. Use a value below. The API rejects other_category on other allowance types.

other_category	STP2 code	Meaning
home_office	H1	Home office costs.
non_deductible	ND	Non-deductible amounts.
transport_fares	T1	Transport fares.
uniform	U1	Uniform costs.
private_vehicle	V1	Private vehicle use.
general	G1	The general descriptor.

ATO reference: Allowances

An 'other' allowance line

{
  "type": "allowance",
  "allowance_type": "other",
  "other_category": "home_office",
  "amount": "80.00"
}

Deductions

These types are for post-tax deductions only. PAYG withholding is not a deduction.

type	STP2 code	Meaning
union_professional_fees	F	Union and professional association fees.
workplace_giving	W	Workplace giving.
child_support_deduction	D	Child support deduction.
child_support_garnishee	G	Child support garnishee.
other_post_tax		Any other post-tax deduction, for example a health fund or a social club.

ATO reference: Other components of your STP reporting

Salary sacrifice

The type field accepts super or other.

Send each pre-tax deduction as a salary_sacrifice line. Use super for a contribution to superannuation and other for each other pre-tax deduction.

Also send salary-sacrificed superannuation as a superannuation line. Refer to Superannuation contributions.

Superannuation contributions

These types are for employer contributions only. Send a post-tax contribution from the employee as a deduction (other_post_tax), and not as a superannuation line.

Send one line for each contribution type. Use the ATO category of the contribution, also when the payslip prints it under a different heading.

contribution_type	Meaning
superannuation_guarantee	The superannuation guarantee amount. If the payroll pays a higher compulsory rate as one pay code, send one superannuation_guarantee line with that rate.
resc	Reportable employer superannuation contributions (RESC), other than salary sacrifice. Do not include salary sacrifice in resc.
salary_sacrifice	Salary-sacrificed superannuation contributions.
other	An employer contribution that is not superannuation guarantee, RESC or salary sacrifice. For example, an amount above the superannuation guarantee under an award or enterprise agreement.

Send salary-sacrificed superannuation on two lines:

• ✓ A salary_sacrifice line with type super. This line is the pre-tax deduction.
• ✓ A superannuation line with contribution type salary_sacrifice. This line is the contribution to the fund.

ATO references: Other components of your STP reporting, Reportable employer super contribution types

Employment basis

Send engagement_type (permanent or fixed_term) in its own field.

employment_basis	STP2 code
full_time	F
part_time	P
casual	C
labour_hire	L
voluntary_agreement	V
death_beneficiary	D
non_employee	N

ATO reference: How to report employment and tax information

Pay frequency

The pay_frequency field accepts weekly, fortnightly, four_weekly, semi_monthly, monthly or quarterly.

Send semi_monthly for a half-monthly or twice-monthly pay calendar.

If a pay is not in a pay calendar, do not send pay_frequency.

Itemising earnings

Send an earnings line for each pay code on the payslip. The lines add up to gross.

If a pay code has no category, send it as an other line.

Send each lump sum with its lump_sum_type, and each etp line with its etp_type and etp_component. Refer to Lump sums and Employment termination payments.

The earnings on a payslip for a genuine redundancy

[
  {
    "type": "ordinary",
    "amount": "3000.00"
  },
  {
    "type": "lump_sum",
    "lump_sum_type": "a_redundancy",
    "amount": "4000.00"
  },
  {
    "type": "lump_sum",
    "lump_sum_type": "d",
    "amount": "5000.00"
  },
  {
    "type": "etp",
    "etp_type": "redundancy",
    "etp_component": "taxable",
    "amount": "8000.00"
  }
]

The gross of this payslip is 20000.00, the total of the four lines.

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.

Identifying a superannuation fund

A superannuation line can contain usi, or no identifier. The schema has no field for a fund ABN and no field for a fund name.

• ✓ usi is an APRA-product Unique Superannuation Identifier: the fund ABN with a 3-digit product suffix (14 digits), or a SPIN such as STA0100AU. It does not accept an 11-digit ABN.
• ✓ A 14-digit usi starts with the fund ABN, so the schema has no separate fund_abn field. A record that contains one is rejected.
• ✓ A self-managed fund has no USI. Send its contributions with no fund identifier.

Year-to-date figures

Send each year-to-date figure that your payslip shows. There are three places for a year-to-date figure:

• ✓ ytd_gross and ytd_paygw hold the two principal totals.
• ✓ ytd_amount on an earnings, salary_sacrifice, deductions or superannuation line holds the figure for that line.
• ✓ The ytd object holds the further totals: taxable, super, non_taxable, post_tax_deductions and reimbursements.

Each year-to-date figure includes the pay run that you register.

What the schema does not carry

The schema does not contain these fields. The API rejects them. Remove them from your payload.

Not in the schema	Why
Leave balances	The schema has no leave-balance field.
Super fund names	Identify a fund with a usi, or send no identifier.
Employee names, addresses and bank details	Send personal data in the encrypted PII payload.
Award codes and classification levels	Send the printed line as award.
Income stream types, tax treatment codes	The schema has no field for these.

Encrypted PII fields

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

AU2: all fields populated

AU2|Ana Leota|Senior Developer|Engineering|12 345 678 901|062-000|****5678|A Leota|12 Example St, Sydney NSW 2000

AU2: some fields omitted

AU2|Ana Leota|||Example Software Pty Ltd|062-000|****5678||

#	Field	Example
1	employee_name	Ana Leota
2	position	Senior Developer
3	department	Engineering
4	employer_identity	12 345 678 901
5	bsb	062-000
6	account_number	****5678
7	account_name	A Leota
8	address	12 Example St, Sydney NSW 2000

For employer_identity, send the employer ABN. If the payslip shows no ABN, send the employer name.

The SDKs write employer_identity for you. Give the employer name and the employer ABN. The SDK writes the ABN if it is present, and the name if not.

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 example

This fortnightly payslip shows hourly pay, an allowance, paid leave, salary sacrifice to superannuation, a post-tax deduction and a reimbursement.

payslip_non_pii

{
  "period_start": "2026-03-21",
  "period_end": "2026-04-03",
  "payment_date": "2026-04-04",
  "currency": "AUD",
  "pay_frequency": "fortnightly",
  "gross": "3600.00",
  "taxable_gross": "3400.00",
  "paygw": "752.00",
  "net": "2682.50",
  "ytd_gross": "43200.00",
  "ytd_paygw": "9024.00",
  "earnings": [
    {
      "type": "ordinary",
      "units": "76",
      "rate": "40.00",
      "amount": "3040.00",
      "ytd_amount": "36480.00"
    },
    {
      "type": "overtime",
      "units": "4",
      "rate": "60.00",
      "amount": "240.00"
    },
    {
      "type": "allowance",
      "allowance_type": "tools",
      "amount": "40.00"
    },
    {
      "type": "paid_leave",
      "leave_type": "other_paid_leave",
      "amount": "280.00"
    }
  ],
  "salary_sacrifice": [
    {
      "type": "super",
      "amount": "200.00"
    }
  ],
  "deductions": [
    {
      "type": "other_post_tax",
      "amount": "45.50"
    }
  ],
  "superannuation": [
    {
      "contribution_type": "superannuation_guarantee",
      "amount": "398.40",
      "rate": "12",
      "usi": "STA0100AU"
    },
    {
      "contribution_type": "salary_sacrifice",
      "amount": "200.00"
    }
  ],
  "reimbursements": "80.00",
  "employment_basis": "full_time",
  "engagement_type": "permanent",
  "award": "Clerks - Private Sector Award 2020 Level 3",
  "stsl_withholding": "120.00",
  "base_rate": {
    "amount": "40.00",
    "per": "hour"
  },
  "ytd": {
    "taxable": "40800.00",
    "super": "4780.80",
    "non_taxable": "960.00",
    "post_tax_deductions": "546.00",
    "reimbursements": "960.00"
  }
}

Versioning

Records that you register with v2 stay valid, and a verifier can still verify them.

The single registration endpoints accept each supported schema id. The schema field selects which schema applies to your payload. Batch registration examines the schema id of each record. An unsupported version fails that record only, and not the full batch.