Getting started

Fifteen minutes from a sandbox credential to a company with its first employee, inside your own page. Nothing here needs a Payroo login; your users never leave your product.

Before you start

  • A sandbox partner record and credential. Create a sandbox (free, instant): enter your company, product and work e-mail, sign in from the e-mail Payroo sends, then on the portal's API page roll your sandbox credential. The value is shown once: store it as a server secret (Payroo keeps only a hash). The same page shows your partnerId and the origins of the pages that may mount a component (https://app.example.com, no wildcard, no path); change them there at any time.
  • Node 20+ (or any server language: the API is plain HTTPS and JSON) and React 18.2 or 19 for the native components. The plain HTML loader needs no framework.

Sandbox base URL: https://sandbox.payroo.com.au/api/v1/embedded. Check it is up:

curl https://sandbox.payroo.com.au/api/v1/embedded/meta
# {"apiVersions":["v1"],"contractVersion":"2026-11-10.1","runtimeMinVersion":"0.1.0","jwksUrl":"/api/v1/embedded/.well-known/jwks.json","mode":"sandbox"}

1. Create a sandbox company

Your backend creates the company and its first admin user in one call. Use your own id for the company (externalEmployerId) and your own id for the user (externalUserId); you address both by those ids from now on. Use synthetic data only (see Environments and sandbox).

curl -X POST https://sandbox.payroo.com.au/api/v1/embedded/employers \
  -H "x-api-key: $PAYROO_PARTNER_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "externalEmployerId": "acme-001",
    "business": {
      "name": "Acme Test Cafe",
      "legalName": "Acme Test Cafe Pty Ltd",
      "abn": "51824753556",
      "address": { "line1": "1 Example St", "suburb": "Sydney", "state": "NSW", "postcode": "2000" }
    },
    "primaryUser": { "externalUserId": "user-42", "email": "owner+acme001@yourdomain.test", "firstName": "Ada", "lastName": "Owner" }
  }'

What you should see: 201 with provisioning { operationId, state, steps[] }. The eight steps run in order (organisation, membership_and_mapping, delegation, defaults, identity_provider, payments_account, features, notifications); employerId and primaryUserId appear once the first two have succeeded. Poll GET /operations/{operationId} until state is succeeded. A repeated externalEmployerId answers 200 with the existing operation, so the call is safe to retry.

If a step fails, state is failed and the step names why; POST /operations/{operationId}/resume runs only the steps not yet done. 409 abn_exists_elsewhere means that ABN already belongs to another organisation: pick another synthetic ABN.

2. Add one session route to your server

Your server holds the credential and mints a session for the signed-in user. The page never sees the credential.

// Node (Express). Any language works: one HTTPS POST.
app.post('/payroll/session', requireLogin, async (req, res) => {
  const r = await fetch('https://sandbox.payroo.com.au/api/v1/embedded/sessions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.PAYROO_PARTNER_KEY,
      'content-type': 'application/json',
      'idempotency-key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      employerId: 'ext:acme-001', // your id from step 1, or Payroo's employerId
      user: { externalUserId: req.user.id, email: req.user.email },
      sessionType: 'employer',
      components: ['company-setup', 'employees', 'run-payroll'],
      scopes: [
        'company:read',
        'company:write',
        'employees:read',
        'employees:write',
        'payruns:read',
        'payruns:write',
      ],
      assurance: {
        method: req.user.mfa ? 'mfa' : 'password',
        authenticatedAt: req.user.authenticatedAt,
      },
      hostOrigin: 'https://app.example.com', // the exact origin of the page that mounts components
    }),
  });
  res.status(r.status).json(await r.json());
});

What you should see: 201 with sessionToken, expiresAt (15 minutes by default), refreshAfter, frame and principal. The runtime calls your route again when the session nears expiry.

Common refusals at this step and what they mean: 403 host_origin_not_allowed (the origin is not on your partner record: add it on the portal's API page), 403 employer_not_delegated (the company is not yours: it was created by another partner or not yet provisioned), 403 user_not_member (the user is not an admin of that company: employer sessions need an organisation admin), 403 scope_exceeds_maximum (you asked for a scope your record does not allow), 422 validation_failed (a field is wrong; error.fields[] says which). The full list is on Errors.

3. Mount a component

React

npm install @payroo-group/embedded-react @payroo-group/embedded-core
import { createServerSessionAdapter } from '@payroo-group/embedded-core';
import { PayrooProvider, CompanySetupChecklist, Employees } from '@payroo-group/embedded-react';

const adapter = createServerSessionAdapter({
  mode: 'staging', // the adapter's label for the sandbox
  capabilities: ['v1-embedded'],
  apiBaseUrl: 'https://sandbox.payroo.com.au/api/v1/embedded',
  sessionUrl: '/payroll/session', // your route from step 2
});

export function Payroll() {
  return (
    <PayrooProvider
      adapter={adapter}
      theme={{ colorPrimary: '#00a258' }}
      onEvent={(e) => console.log(e.name, e.payload)}
    >
      <CompanySetupChecklist />
      <Employees />
    </PayrooProvider>
  );
}

Plain HTML

@payroo-group/embedded-loader ships an IIFE build (@payroo-group/embedded-loader/iife, file payroo-embed.iife.js) that you host beside your page. It renders the component in the Payroo frame shell.

<div id="payroll"></div>
<script src="/vendor/payroo-embed.iife.js"></script>
<script>
  PayrooEmbed.mount({
    container: '#payroll',
    component: 'company-setup',
    getSession: () => fetch('/payroll/session', { method: 'POST' }).then((r) => r.json()),
    onSessionExpiring: () => fetch('/payroll/session', { method: 'POST' }).then((r) => r.json()),
    onEvent: (name, payload) => console.log(name, payload),
    onError: (code, message) => console.warn(code, message),
  });
</script>

Frame shell from React

When you would rather not host the component UI, mount the frame shell: <PayrooFrame component="employees" /> inside the same PayrooProvider. It loads a Payroo-origin iframe with a 60-second bootstrap token that the runtime requests from your session.

What you should see: the Company setup checklist with the steps Payroo needs before a pay run (details, pay settings, bank account, ATO connection, super). The bank account number field is a Payroo-origin secure field: your page receives { valid } and nothing else.

4. Add the first employee

In the Employees component, Add employee collects the person, employment, pay, tax and super details. Or do it from your backend on the session:

curl -X POST https://sandbox.payroo.com.au/api/v1/embedded/employees \
  -H "authorization: EmbeddedSession $SESSION_TOKEN" \
  -H "content-type: application/json" -H "idempotency-key: $(uuidgen)" \
  -d '{ "person": { "givenName": "Sam", "familyName": "Worker", "dateOfBirth": "1990-04-02" },
        "contact": { "email": "sam+acme001@yourdomain.test", "address": { "line1": "2 Example St", "suburb": "Sydney", "state": "NSW", "postcode": "2000" } },
        "employment": { "basis": "casual", "startDate": "2026-11-01", "jobTitle": "Barista" },
        "pay": { "rateCents": 3000, "unit": "hour" } }'

What you should see: 201 with the employee; the page event employee.created fires in onEvent with the id and state only. POST /employees/{employeeId}/invitations sends the employee a link to complete their own tax and super details in the employee-self-onboarding component.

5. Watch the events, then go further

Page events carry identifiers and state, never values: company.onboarding.step_completed, company.ready_for_payroll, employee.created, payrun.approved, payrun.lodging, payrun.accepted, session.expired. For server-side reactions register a webhook destination (PUT /webhooks/config): Payroo signs every delivery with a secret shown once.

Next: Authentication and sessions for scopes, refresh and step-ups; Environments and sandbox for the synthetic-data rules and rate limits; the Partner API for every route your server calls.

Your security obligations

  • Keep the partner credential on your server. Never ship it to a browser, a repository or a log.
  • Register exact origins. Sessions are refused for pages whose origin is not registered.
  • Treat the session token as a bearer secret for its lifetime: memory only; never in a URL, storage or log.
  • Allow Payroo frames in your Content-Security-Policy: frame-src for the API origin; connect-src for the API origin when you use the native shell.
  • Do not try to read or set sensitive values. Secure fields give you validity only; approvals and lodgements need the user's step-up in a Payroo-origin dialog that your page cannot drive.