Environments and sandbox
| Environment | API base | What it is | Who gets it |
|---|---|---|---|
| Sandbox | https://sandbox.payroo.com.au/api/v1/embedded |
Payroo's dedicated sandbox; synthetic organisations; ATO and super gateways in their test modes | every partner at sign-up |
| Production | announced to production partners | the live Payroo platform | after Payroo's production review |
| Mock | in your browser, no network | @payroo-group/embedded-mock implements the contract in memory for your own tests and demos |
anyone |
GET /meta tells you which you are talking to: { apiVersions, contractVersion, runtimeMinVersion, jwksUrl, mode }, with mode one of mock, local, staging, sandbox, production (the sandbox answers sandbox). The showcase at https://payroo-embedded-demo.vercel.app runs the mock; a live sandbox showcase exists for partners in onboarding.
Sandbox rules
- Synthetic data only. No real person, business, bank account or tax file number. Use e-mail addresses on a mailbox you control (plus-addressing works:
owner+acme001@yourdomain.test); the primary user and invited employees receive real e-mails from Payroo's sandbox. Generate test ABNs; an ABN already held by another sandbox organisation answers409 abn_exists_elsewhere. - Sandbox partners reach sandbox companies only. Your sandbox credential cannot mint for a production company and your production credential cannot mint for a sandbox one.
- Lodgements go to the ATO's test channel. The outcome (
payrun.acceptedorpayrun.rejected) arrives through the same events and webhooks as production. - Shared platform. Staging is redeployed by Payroo; a
404onGET /metameans another build is on the host for a while. Your data persists.
Rate limits
| Limit | Default | Response when exceeded |
|---|---|---|
| per partner credential | 600 requests per minute | 429 rate_limited with Retry-After |
| per session | 120 requests per minute | 429 rate_limited with Retry-After |
Limits are fixed windows per minute. Honour Retry-After; the runtime does so for its own calls. Higher limits are set by Payroo on your record.
Hosts to allow
| Purpose | Host |
|---|---|
| API, frame document, JWKS, secure fields | https://sandbox.payroo.com.au (sandbox) |
| Frame assets (scripts and styles the frame loads) | https://payroo-embedded-frame.vercel.app |
| Webhook deliveries to you | from Payroo's egress; verify the Payroo-Signature header instead of allow-listing addresses |
Your Content-Security-Policy: frame-src and connect-src for the API host; the frame assets host is loaded by the frame itself, not by your page.
Identities in the sandbox
- Your users sign in to your product; Payroo only sees your
externalUserId(and the e-mail once, for mapping). - The primary user of each company you provision becomes a Payroo organisation admin behind the scenes and sets a Payroo password the first time a step-up asks (or from the invitation e-mail when Payroo enables it). This is the person who confirms bank changes, approvals and lodgements.
- Employees never get a Payroo login. They reach their own onboarding and payslips through your product (
sessionType: employee) or through an invitation link.
From sandbox to production
Payroo issues a production partner record and credential after a review of your integration: origins, credential custody, webhook receiver, the journeys you expose and your support e-mails. The API is identical; only the base URL, the credential and the data change. The checklist is in the Going to production guide.