NZ Payslip
Checker

New Zealand shift workers — nurses, hospitality staff, factory workers, retail — are paid under rules that most employees don't fully understand. PAYE tax is calculated using annualised income brackets, not a flat rate. ACC earner levy applies to all liable earnings. KiwiSaver contributions must match the elected rate. Student loan repayments have per-period thresholds. And public holiday Mondayisation rules can change the gross amount entirely.

Most workers receive a payslip, glance at the net figure, and trust it. The tools that exist to verify pay are either general-purpose calculators requiring manual entry, or IRD's own portal — which tells you what tax should have been paid annually but not whether this specific payslip is correct.

The gap I wanted to fill: upload a payslip, get a line-by-line audit in seconds. No account. No data stored. No friction.

The core challenge with using an LLM for payroll verification isn't getting it to read a payslip — modern vision models can do that easily. The challenge is getting it to output a consistent, machine-readable structure every single time, regardless of how different payslip formats look across hundreds of NZ employers.

Tool Use for Guaranteed Structure

I used Anthropic's tool use feature with tool_choice: { type: "tool", name: "analyse_payslip" }. This forces Claude to respond exclusively by calling a predefined tool — it cannot reply in free text. The tool's input schema defines exactly what fields are required, their types, and their allowed values.

This means the frontend can trust the shape of the response completely. No parsing of natural language. No regex on output. No retries when the model decides to be conversational. If the tool call doesn't appear in the response, the function throws — it's treated as a hard failure.

The Schema

The output schema covers every component of an NZ payslip as a typed object tree:

{
  payPeriod:    { type, startDate, endDate, payDate },
  employee:     { name, employeeId, taxCode, kiwiSaverRate, hasStudentLoan },
  employer:     { name, irNumber },
  earnings:     [ { description, hours, rate, amount } ],
  totals:       { totalHours, grossPay },
  deductions: {
    paye:        { found, expected, pass, taxableIncome, annualisedIncome, marginalRates, note },
    acc:         { found, expected, pass, note },
    kiwiSaver:   { found, expected, pass, rate, applicable, note },
    studentLoan: { found, expected, pass, applicable, weeklyThreshold, note }
  },
  otherDeductions: [ { description, amount } ],
  netPay:       { found, expected, pass, note },
  overallPass:  boolean,
  confidenceLevel: "high" | "medium" | "low",
  confidenceNote: string,
  summary:      string,
  warnings:     [ string ]
}

Every deduction has found, expected, and pass fields — not just a flag but the actual numbers that were compared. The working behind each calculation appears in the note field so users understand exactly how figures were verified.

System Prompt Design

The system prompt encodes NZ-specific payroll rules directly. Rather than relying on the model's training knowledge (which may be outdated), the prompt explicitly provides:

• → The 2024–2025 PAYE tax brackets for every common tax code (M, M SL, ME, SB, S, SH, ST, SA)
• → ACC earner levy rate ($1.60 per $100, capped at ~$142,283 annual liable earnings)
• → KiwiSaver contribution rates (3%, 4%, 6%, 8%, 10%) — detected from the payslip
• → Student loan threshold (~$24,128/year, 12% of gross above the per-period equivalent)
• → Explicit instruction to convert all annual thresholds to the detected pay period before comparing

That last point matters more than it sounds. A model that compares a weekly PAYE deduction against annual tax tables gets wrong answers. The prompt requires period conversion before any comparison is made.

Why Sonnet Over Haiku

The tool was initially built with Claude Haiku 4.5 for speed and cost. Haiku worked — it could read payslips and produce valid JSON. But on complex payslips with multiple earnings lines, overlapping deductions, and unusual tax codes, it would occasionally misread figures or skip the period conversion step. These aren't acceptable failure modes for a financial verification tool.

Claude Sonnet 4.6 produces markedly more accurate extraction and calculation, particularly on image-format payslips where layout varies significantly. The tradeoff is response time — Sonnet takes 15–30 seconds on a complex payslip versus 5–8 for Haiku. That response time is exactly what drove the background function architecture.