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:

  1. The secure field tokenises the number (POST /secure-values, from the Payroo origin only; a host page that tries gets 403 host_origin_not_allowed) into a single-use handle valid 10 minutes. Your page only ever learns { valid: true }.
  2. The component calls PUT /company/bank-account with bsb, accountName, accountNumberHandle and, for payment files, apcaUserId and institutionCode.
  3. The server answers 403 step_up_required with error.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 with X-Step-Up-Intent. Partners who hold an assurance agreement with Payroo and mint with a fresh mfa assurance skip the dialog.
  4. 200 with the view: accountNumberProvided: true, never a digit. A handle that was consumed, expired or minted for another field answers 422 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:

  1. POST /company/ato-connection/review { submitterType }: who reports to the ATO, the employer itself or a registered tax or BAS agent. State becomes details_reviewed.
  2. POST /company/ato-connection/notify: the business confirms it has nominated Payroo's software id in ATO Access Manager. 409 precondition_required until 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