Employees
Two ways to get an employee onto payroll: the administrator enters everything, or the administrator enters the basics and invites the employee to finish their own tax, super and bank details on a Payroo page under your brand. Tax file numbers and account numbers travel through Payroo-origin secure fields in both cases; your page sees flags, never values.
Session: an employer session with employees:read and employees:write, component employees. Self-onboarding runs on an employee session that the invitation creates by itself.
Create
POST /employees with an Idempotency-Key. Person, contact, employment and pay fields are plain JSON; tax, super and bank are optional sections whose sensitive fields are handles from secure fields:
- without them, the employee is created and waits to be invited;
- with all three, the employee is
activeat once; - with a
banksection, the server requires thebank_changestep-up first (403 step_up_required, then retry withX-Step-Up-Intent), exactly as for the company bank account.
201 with the employee: tfnProvided, accountNumberProvided and the onboarding status. Validation errors are the payroll engine's own, returned as 422 validation_failed with error.details.fields[] (path, code, message); the EmployeeForm component shows them inline.
Read and update
GET /employees?status=&search=&cursor=: a page of the company's employees withstatus(active,invited,onboarding,terminated) and each one's onboarding steps.GET /employees/{employeeId}: one employee.404 not_foundfor an employee of another company, so ids cannot be probed.PATCH /employees/{employeeId}: contact, employment and pay fields, and thetax,superandbanksections with handles; abanksection needs the step-up. Every handle is verified before any is consumed, so a failed save leaves them usable and the sameIdempotency-Keyretries cleanly.GET /employees/{employeeId}/onboarding: the four steps and whether each is complete, never what the employee entered.
Invite
POST /employees/{employeeId}/invitations { channel } issues a single-use token valid 7 days; a new invitation supersedes the previous one and the employee becomes invited.
| Channel | What you get | When to use |
|---|---|---|
partner_link |
link: the landing page on Payroo's frame origin with the token in the URL fragment |
you deliver it in your own e-mail or in-app message |
payroo_email |
nothing in the response; Payroo sends its self-onboarding e-mail with your name, logo and colour | the quickest path; needs logoUrl and theme.colorPrimary on your partner record |
The token is a bearer: do not log it or store it beyond delivery.
Self-onboarding
The landing page exchanges the token (POST /invitations/{token}/session { hostOrigin }) for an employee session limited to self:onboarding and self:payslips, 15 minutes, no password. Every failure (unknown, expired, used, malformed) is 404 invitation_invalid, so the route reveals nothing; the exchange is rate limited per client address (429 rate_limited).
The SelfOnboarding component then walks the four engine steps in order, each saved with PUT /self/onboarding/{stepId}:
| Step | Content | Secure fields |
|---|---|---|
personal_details |
name, date of birth, address, contact | none |
bank_details |
BSB, account name, account number | accountNumberHandle |
tax_details |
the tax declaration | tfnHandle |
super_details |
fund choice or the employer default | member number when the fund asks for one |
No step-up is asked here: the invitation is the assurance. Completing the fourth step makes the employee active and fires employee.onboarding.completed once, on the page bus and as a webhook. A used link opened again answers invitation_invalid.
If you embed the landing page yourself, use SelfOnboarding under an adapter whose session came from the exchange; the showcase does this in mock mode and the Payroo landing page does it on sandbox and production.
Events and webhooks
Page: employee.created, employee.updated, employee.invited, employee.onboarding.step_completed, employee.onboarding.completed. Webhooks: employee.created, employee.updated, employee.invited, employee.onboarding.completed. Payloads carry ids and state only.
What you should see
After a create with the three sections, or after the fourth self-onboarding step, GET /employees/{id} shows status: active, tfnProvided: true, accountNumberProvided: true and onboarding.complete: true. An employee without tax details blocks lodgement (employee_tax_details_missing in the pay run's readiness).
Errors you may see
| Status and code | Meaning | Next action |
|---|---|---|
403 step_up_required |
a bank section needs the user's confirmation | the component handles it |
404 invitation_invalid |
the invitation token is unknown, expired or used | issue a new invitation |
422 invalid_handle |
a secure value handle is spent, expired or for another target | mint again |
422 validation_failed |
engine field rules; see details.fields[] |
fix the field |
429 rate_limited |
too many exchanges from one address | honour Retry-After |