Build the TFN Declaration Report into ATO XML

Skill: Convert new-employee TFN declaration data into the ATO electronic TFN declaration report

Region: Australia Category: Payroll — TFN Declaration (ATO; STP Phase 2 onboarding) Does: Takes new-employee Tax File Number declaration data and produces the ATO electronic TFN declaration report XML — payee TFN/exemption, residency, tax-free threshold, and study/training loan flags that set the payee's tax treatment. Standard: ATO TFN declaration electronic reporting; tax-treatment data also conveyed via STP Phase 2.

Under STP Phase 2, the payee's tax circumstances are usually reported through the employer's STP pay event (tax treatment code), and a separate TFN declaration report is often no longer lodged. Produce this report only where your process still lodges TFN declaration data electronically. Validate against the current ATO specification before lodging. The employee must still complete and the employer retain the TFN declaration.

When this applies

• A new payee provides a TFN declaration and the employer reports the tax-affecting details to the ATO (electronically, where still required) and configures payroll withholding.
• The same inputs drive the STP Phase 2 tax treatment code (see payroll/build-stp-pay-event.md).
• Not for the pay/withholding amounts themselves (those flow through STP).

Conversion procedure

1. Read the source. Accept the completed TFN declaration (form fields/CSV/JSON) plus the payer ABN and branch. Identify each payee.
2. Extract fields. Payee TFN (or an exemption code), name, date of birth, address, residency status, tax-free-threshold claim, study/training support loan (STSL) flag, and basis of payment. If the payer ABN, payee name, or TFN/exemption is missing, stop and ask.
3. Normalize. TFN digits only (or a valid exemption code). Dates YYYY-MM-DD. Booleans to yes/no (or the spec's Y/N).
4. Derive the residency/threshold/loan combination that sets the tax treatment; ensure the tax-free threshold is claimed with only one employer.
5. Emit the XML report per the structure and worked example.
6. Validate with the checklist.

Source → TFN declaration field map

Document structure

TFNDeclarationReport
├── Payer
│   ├── ABN
│   ├── BranchNumber
│   └── Name
└── Payee ...                 (one per declaration)
    ├── TFN                   (digits or exemption code)
    ├── Name / DateOfBirth / Address
    ├── ResidencyStatus       (resident / foreign / WHM)
    ├── TaxFreeThreshold      (yes/no)
    ├── StudyTrainingLoan     (yes/no)
    └── BasisOfPayment        (F/P/C/L/N)

Code tables

TFN exemption codes (when no TFN provided)

Basis of payment

Residency status

Calculation rules

• TFN is 9 digits (no spaces); if absent, use the appropriate exemption code above — never invent a TFN.
• Tax-free threshold should be yes for only one employer at a time; a foreign resident cannot claim it.
• The tax treatment derives from residency + threshold + STSL + medicare-levy variations; this report carries the declaration data that feeds it.
• Validate the TFN format/algorithm where your tooling supports it; flag invalid TFNs.

Worked example (end-to-end)

Input — new employee TFN declaration

Payer ABN 53004085616, branch 001, Sunrise Cafe Pty Ltd
Payee: Alex Tan, DOB 1995-03-12, TFN 123456782
Australian resident, claims tax-free threshold, has a HELP debt, part-time

After normalization (intermediate)

TFN 123456782 ; residency resident ; threshold yes ; STSL yes ; basis P
DOB 1995-03-12 ; ABN 53004085616 ; branch 001

Output — TFN declaration report XML

<?xml version="1.0" encoding="UTF-8"?>
<TFNDeclarationReport>
  <Payer>
    <ABN>53004085616</ABN>
    <BranchNumber>001</BranchNumber>
    <Name>Sunrise Cafe Pty Ltd</Name>
  </Payer>
  <Payee>
    <TFN>123456782</TFN>
    <Name>
      <FamilyName>Tan</FamilyName>
      <GivenName>Alex</GivenName>
    </Name>
    <DateOfBirth>1995-03-12</DateOfBirth>
    <ResidencyStatus>resident</ResidencyStatus>
    <TaxFreeThreshold>yes</TaxFreeThreshold>
    <StudyTrainingLoan>yes</StudyTrainingLoan>
    <BasisOfPayment>P</BasisOfPayment>
  </Payee>
</TFNDeclarationReport>

Normalisations shown: TFN kept as 9 digits 123456782; threshold and HELP flags to yes; residency resident; basis of payment part-time → P; DOB to YYYY-MM-DD.

Validation checklist

• Payer ABN/branch and each payee's name captured; nothing invented
• Payee TFN is 9 digits, or a valid exemption code is used (no fabricated TFN)
• Residency status set; tax-free threshold not claimed by a foreign resident
• Tax-free threshold claimed with only one employer
• STSL (HELP/SSL/TSL) and basis-of-payment flags set correctly
• Dates YYYY-MM-DD; report aligns with the STP Phase 2 tax treatment code
• Validated against the current ATO TFN declaration specification before lodging

Last updated: 2026-06-13 — verify the current ATO TFN declaration electronic specification, STP Phase 2 tax-treatment reporting, and exemption codes before use.