New Zealand payroll is not a formatting problem, it is a per-pay-cycle filing obligation. Since payday filing became mandatory, every employer must lodge employment information within two working days of each pay day, plus employee details filings when someone starts or leaves. ERPNext core ships a competent generic Payroll module — Salary Structure, Salary Slip, Payroll Entry, Salary Component — but it knows nothing about IRD numbers, tax codes such as M, ME, SB, S, SH, ST and SA, secondary tax rates, the four-weekly and fortnightly PAYE tables, KiwiSaver employee contribution rates of 3, 4, 6, 8 or 10 percent, compulsory employer contributions, ESCT threshold bands, student loan repayments with SLCIR and SLBOR adjustments, or the file layout Inland Revenue expects. In practice teams end up running a separate payroll silo, then re-keying journals back into ERPNext, which breaks the general ledger link between labour cost and the cost centre or project that consumed it.

We build a proper Frappe app — its own repository, its own module, installed with bench get-app and bench --site <site> install-app — rather than a pile of customisations sprayed across your production site. The app introduces NZ-specific DocTypes: an NZ Payroll Settings single for IRD number, PAYE intermediary details, ESCT thresholds and filing endpoints; NZ Tax Code and NZ PAYE Rate Table so rates are data you can update, not hardcoded Python; NZ Employee Payroll Detail carrying IRD number, tax code, KiwiSaver status and rate, ESCT rate, student loan flags and any special tax code certificate; and NZ Payday Filing Batch, which holds one filing run, its line items, its generated file and its submission state. Calculation logic lives in server-side controller methods and is bound to the pay run through hooks.py document events — a validate hook on Salary Slip that recomputes PAYE, KiwiSaver, ESCT and student loan from the employee's tax code and pay period, and an on_submit hook on Payroll Entry that assembles the filing batch. Where a value must be checked before save, a client script on the Employee and Salary Slip forms validates IRD number check digits and warns on tax code and KiwiSaver combinations Inland Revenue will reject.

Filing and outputs are deliberately separated so a submission failure never blocks payroll. Generation produces the employment information payload for the batch; transmission is a whitelisted method wrapped in a background job, so a slow or unavailable gateway does not time out a user request. The response, error codes and correlation identifiers are written back onto the NZ Payday Filing Batch and visible in its timeline. A scheduler event registered under scheduler_events in hooks.py checks for batches that are generated but unsubmitted, or submitted but unacknowledged, and raises them so nobody discovers a missed two-working-day deadline at month end. Payslips render through a Frappe Print Format showing gross, PAYE, KiwiSaver employee and employer, ESCT, student loan, holiday pay and net. Bank files come from a template-driven exporter, so ANZ, ASB, BNZ, Westpac and Kiwibank direct-credit layouts are configuration rather than code. Leave maps ERPNext Leave Type and Leave Policy onto Holidays Act concepts — annual holidays accruing in weeks and paid at the greater of ordinary weekly pay or average weekly earnings, sick leave, bereavement, family violence leave and alternative holidays — with the comparison exposed on the leave record so a payroll officer can see how a figure was reached. Everything is reachable over the Frappe REST API and through whitelisted methods, and every new DocType ships with permission rules and a Payroll Officer role profile so filing data is not readable by the whole company.

Because this is a build-to-order engagement, nothing is downloaded and nothing is guessed. We start with a scoping call, confirm your ERPNext version, pay cycles, entity structure and bank, and write that into a scope document you approve. Typical delivery is two to four weeks from confirmed scope, depending on how many pay groups and bank formats are in play. We build against Frappe and ERPNext v15 and v16, deliver to a staging site first for UAT with your own employee data, and only then schedule the production cutover — with a rollback plan agreed in advance and a first live pay run we sit through with you. You receive the installable source code for your version and a git repository handover, so the app is yours to keep, read and extend. Compliance rates and thresholds change; we state plainly what the support window covers and what a future rate or format update looks like, rather than implying permanent free maintenance.