About STP Phase 2

STP Phase 2 (PAYEVNT.0004) introduced disaggregated reporting, meaning employees and pay events carry a lot more structured metadata. This page is a reference for the codes you'll pass to the API.

Authoritative source: ATO STP Phase 2 Employer Reporting Guidelines.

Employment basis

Used on employee.employment_basis.

Code Label Description
F Full-time Permanent full-time employment
P Part-time Permanent part-time employment
C Casual Casual employment
L Labour hire Supplied by a labour hire agency

Income type

Used on employee.income_type. Also drives the income type on pay events.

Code Label When to use
SAW Salary and wages Default for most employees
CHP Closely held payee Employees directly related to the employer (e.g. family member of a business owner)
WHM Working holiday maker Employees on 417 or 462 visas. Requires income_type_country.
SWP Seasonal worker program SWP visa holders
VOL Voluntary agreement Contractor under voluntary withholding agreement
JPD Joint petroleum development Workers in the JPDA zone

If income_type is WHM, you must also set income_type_country to a valid ISO 3166 alpha-3 country code (e.g. GBR, FRA, USA).

Tax treatment code

Used on employee.tax_treatment_code. This is the 8-character code that replaces the old payment summary tax category system.

The code has four positions encoding different aspects of the employee's tax situation:

Position 1: Category
Position 2: Option
Position 3-4: Tax rate / adjustment
Position 5-8: STSL / MLS flags

Common codes:

Code Meaning
RTRR0000 Regular employee, claims tax-free threshold, no STSL debt
RTNR0000 Regular employee, no tax-free threshold claimed
RTRS0000 Regular employee, tax-free threshold, STSL debt
RTNS0000 Regular employee, no tax-free threshold, STSL debt
SSRR0000 Seniors and pensioners offset, single, regular rate
HRRT0000 Horticulturists / shearers
WPLS0000 Working holiday maker, low tax rate
VCRR0000 Voluntary agreement, commissioner's rate
NCRR0000 Non-resident, regular
DBRR0000 Death benefit recipient, regular
NFFF0000 No TFN claimed

The full table is in the ATO's PAYEVNT.0004 schema documentation. When in doubt, RTRR0000 is the right default for most full-time Australian residents.

If your employees don't have TFNs recorded, use one of:

  • NFFF0000 — no TFN quoted, apply highest withholding
  • NAFF0000 — applied for, interim

Pay frequency

Used on pay_event.pay_frequency.

Code Label
weekly Weekly
fortnightly Fortnightly
monthly Monthly
quarterly Quarterly

Event type

Used on pay_event.event_type.

Code When to use
pay_event Normal pay event — the default. Use for every regular pay run.
update_event Correcting a previously-submitted pay event. Provides updated YTD figures without changing the original pay_event's metadata.
full_file_replacement Replacing an entire previously-submitted pay event (e.g. it was fundamentally wrong).

Cessation reason

Used on employee.cessation_reason when terminating an employee.

Code Meaning
V Voluntary cessation
I Ill health
D Deceased
R Redundancy / workplace cessation
F Dismissal
C Contract cessation
T Transfer
O Other

ETP code

Used on pay_event_item.etp_code for employment termination payments.

Code Meaning
R Redundancy, invalidity, early retirement
O Other
S Pre-1 July 1983 portion
P Death benefit (dependant)
N Death benefit (non-dependant)
B Contract cessation

Allowance types (advanced)

STP Phase 2 requires allowances to be disaggregated by type. The current API treats allowances as a lump sum under task_allowances; fine-grained allowance typing is on the roadmap. For now, report the total under task_allowances and break down in the XBRL via a custom field if your use case requires it — contact support@beeswaxapp.com for guidance.

Reference: STP Phase 2 allowance types.

ABN format

ABNs are 11 digits with a specific checksum. Beeswax STP validates the 11-digit format on employer creation but does not currently run the checksum algorithm — that's on the roadmap. Garbage ABNs will fail at the ATO submission step with a clear error.

Official validation algorithm: ABN specification.

TFN format

TFNs are 8 or 9 digits, no letters. Beeswax STP accepts any string and stores it encrypted; we don't currently validate the checksum. The ATO rejects invalid TFNs on submission.

ATO substitution values for special cases:

Value Meaning
000000000 No TFN quoted
111111111 Applied for (interim)
333333333 Under 18, earning less than the weekly threshold
444444444 Recipient of certain Centrelink pensions

State codes

Australian states and territories for employer.state and employee.state:

Code Name
ACT Australian Capital Territory
NSW New South Wales
NT Northern Territory
QLD Queensland
SA South Australia
TAS Tasmania
VIC Victoria
WA Western Australia

Further reading