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 active at once;
  • with a bank section, the server requires the bank_change step-up first (403 step_up_required, then retry with X-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 with status (active, invited, onboarding, terminated) and each one's onboarding steps.
  • GET /employees/{employeeId}: one employee. 404 not_found for an employee of another company, so ids cannot be probed.
  • PATCH /employees/{employeeId}: contact, employment and pay fields, and the tax, super and bank sections with handles; a bank section needs the step-up. Every handle is verified before any is consumed, so a failed save leaves them usable and the same Idempotency-Key retries 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