Company setup
Before a company can run payroll it needs business details, pay settings, an employer bank account, a connection to the ATO and a default super fund. The company-setup component walks the administrator through those five steps; this guide explains what happens underneath, so you can build your own flow or know what the component is doing.
Session: an employer session with company:read for reads and company:write for writes, and company-setup in components.
Readiness drives everything
GET /v1/embedded/company/readiness
{
"ready": false,
"steps": [
{ "id": "business-details", "status": "complete", "blockers": [] },
{ "id": "pay-settings", "status": "complete", "blockers": [] },
{ "id": "bank-account", "status": "incomplete", "blockers": [] },
{
"id": "ato-connection",
"status": "blocked",
"blockers": [
{ "code": "software_id_pending", "message": "…", "nextAction": { "kind": "none" } }
]
},
{ "id": "super-fund", "status": "incomplete", "blockers": [] }
]
}
ready becomes true when every step is complete; the page event company.ready_for_payroll and the webhook of the same name fire once. Each blocker carries a nextAction (component with a step, external with an href, or none when only time will fix it), which is what the checklist component renders.
1. Business details and 2. Pay settings
GET and PUT /company/details (name, legal name, ABN, address, contact) and GET and PUT /company/pay-settings (frequency, default hours). Plain saves with an Idempotency-Key; 422 validation_failed names the field. A field Payroo has locked after the first lodgement answers 422 field_locked.
3. Bank account
The account number is sensitive, so it never passes through your page. The BankAccountForm component takes BSB and account name in your DOM and the account number in a secure field, a small Payroo-origin frame. On save:
- The secure field tokenises the number (
POST /secure-values, from the Payroo origin only; a host page that tries gets403 host_origin_not_allowed) into a single-use handle valid 10 minutes. Your page only ever learns{ valid: true }. - The component calls
PUT /company/bank-accountwithbsb,accountName,accountNumberHandleand, for payment files,apcaUserIdandinstitutionCode. - The server answers
403 step_up_requiredwitherror.stepUp.authorizeUrl: a bank change needs the user to confirm with Payroo, every time. The component opens the Payroo dialog, the user confirms, and the component retries withX-Step-Up-Intent. Partners who hold an assurance agreement with Payroo and mint with a freshmfaassurance skip the dialog. 200with the view:accountNumberProvided: true, never a digit. A handle that was consumed, expired or minted for another field answers422 invalid_handle: the component mints a new one and retries.
The APCA user id (six digits issued by the bank) and the institution code (the bank's three-letter abbreviation, for example CBA) are what the bank needs on a payment file; without either, the pay run's payment file answers 409 precondition_required with blocker payer_apca_id_missing (see Run payroll).
4. ATO connection
Two steps, mirroring what the business does in the ATO's own portal:
POST /company/ato-connection/review { submitterType }: who reports to the ATO, the employer itself or a registered tax or BAS agent. State becomesdetails_reviewed.POST /company/ato-connection/notify: the business confirms it has nominated Payroo's software id in ATO Access Manager.409 precondition_requireduntil step one is done, and until Payroo has a software id for this organisation. On sandbox the software id is issued by a background worker minutes after provisioning; show "pending" and let the user come back rather than retrying in a loop.
GET /company/ato-connection reads the state: not_started, details_reviewed, notified, connected, failed. Webhook company.ato_notified fires at step two.
5. Super fund
The default fund is chosen in SuperAPI's widget inside a Payroo frame: POST /super/embed-url mints a short-lived URL bound to the session, usable only inside the frame. The SuperFund component is frame-only for that reason. On an environment where Payroo has not configured SuperAPI the route answers 404 not_found and the step is unavailable; the sandbox has it.
What you should see when it is done
GET /company/readiness answers ready: true; the checklist component shows five complete steps; GET /employers/{employerId}/status from your server (partner credential) shows the same readiness without any payroll value. The company can now add employees and run payroll.
Errors you may see
| Status and code | Meaning | Next action |
|---|---|---|
403 scope_missing |
the session lacks company:write |
mint with the scope |
403 component_not_in_session |
company-setup was not in the session's components |
mint with the component |
403 step_up_required |
the bank save needs the user's confirmation | the component handles it; API clients open authorizeUrl for the user and retry with X-Step-Up-Intent |
410 step_up_expired |
the confirmation took too long | start the save again |
422 invalid_handle |
the secure value handle is spent or mismatched | mint a new handle |
422 field_locked |
the field is frozen after lodgement | tell the user; Payroo support can change it |
409 precondition_required |
ATO notify before review or before the software id exists | do step one; wait for the software id |