Lightning Payroll API – Developer Docs

Getting Started

Welcome to the Lightning Payroll API. We use the OAuth 2.0 Authorization Code flow so your app can access customer payroll data securely and in a way developers already know.

Machine-readable schema endpoints:
/schema/openapi.json
/schema/components/index.json
/schema/operations/index.json
/schema/endpoints/create-pays-for-date.json
/schema/components/PayCreate.json
/schema/components/PayCreate.json?resolved=true

Integration guides:
OAuth Authentication Guide
API Admin Setup and Management Guide
API Branding & Co-Branding Guide
Company Redirect Guide
Partner Checkout Admin Endpoints Guide (includes free trials)
Lightning Payroll Partner Program

Environments

Environment	Base URL	Notes
Production AU	`https://api.lightningpayroll.com.au`	Live AU-hosted customer data
Production NZ	`https://api.lightningpayroll.co.nz`	Live NZ-hosted customer data
Development AU	`https://api.dev.intellitron.com.au`	AU sandbox. Matching app host: `https://app.dev.intellitron.com.au`
Development NZ	`https://nzapi.dev.intellitron.com.au`	NZ sandbox. Matching app host: `https://nzapp.dev.intellitron.com.au`

Current docs host: https://api.lightningpayroll.com.au
Default AU production host: https://api.lightningpayroll.com.au
Use the AU or NZ hostname that matches the customer-facing deployment you are integrating with.

Getting API Access

To access the Lightning Payroll API, your company must first be granted access by our development team. This step ensures only approved clients can generate credentials for secure integration.

If you don’t yet have access, please contact our team here to get started.

Once access has been granted, you'll be able to visit the API Management section of your admin dashboard to create a Client ID and Client Secret. These are required to begin the OAuth 2.0 Authorisation Code flow described above.

API Management Page

Authorization Code Flow

Redirect the customer to our authorization endpoint.
Replace {base} with the environment you’re targeting.

GET {base}/api/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth
  &state=xyz123
  &scope=openid%20payroll.write

Receive the one-time code.
We redirect back to redirect_uri with ?code=…&state=…. The code is single-use and valid for 10 minutes.

Exchange the code for tokens.

POST {base}/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=THE_CODE_FROM_STEP_2&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth

Successful response:

{
  "access_token":  "…",
  "token_type":    "Bearer",
  "expires_in":    1800,
  "refresh_token": "…",
  "refresh_expires_in": 2592000
}

Call protected endpoints.
Include Authorization: Bearer <access_token>. When it expires, swap the refresh_token for a fresh pair:

POST {base}/api/oauth/token
grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth

Authentication Endpoint Reference

Path	Description
`GET /api/oauth/authorize`	Starts the Authorization Code flow (302 redirect to sign-in / consent screen).
`POST /api/oauth/token`	Exchanges an authorization code or refresh_token for fresh tokens.
`GET /api/company` (example protected)	Lists companies the authenticated customer can access.
`GET /api/employees/{employee_id}/super-funds`	AU only. Employee super-fund endpoints are not used for NZ payroll flows.
`POST /api/single-touch/{company_id}/submit-stp-pays`	AU only. STP endpoints remain available on the public API but should not be used for NZ filing.

Scopes

openid – identity scope (required)
payroll.read – read-only payroll data
payroll.write – create / modify payroll artefacts

Partner Free Trials

If you are a reseller partner, you can start a client on a free one-month trial without placing a billed order. A trial creates no order, so it never reaches an invoice and is never renewed. When the trial ends you place the real order against the same client. Trial emails carry your own branding where you have white-label branding configured.

Start the trial.
Send the client and company details. Only the company identifier decides the country: abn for Australia, ird_number for New Zealand. A billing address is optional, because nothing is billed.

POST {base}/api/partner-checkout/trials
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: 6f1c9a2e-trial-0001

{
  "customer": {
    "first_name": "Alice",
    "last_name": "Nguyen",
    "email": "alice@example.com",
    "phone": "+61 7 3000 0000"
  },
  "company": {
    "legal_name": "Sunrise Hospitality Pty Ltd",
    "abn": "10000000000"
  }
}

Keep the returned customer_id and subscription_trial_id. The client is emailed a link to set their password and begin.

Track the trial.
Poll for the trials you created and watch days_remaining. Filter with ?status=active, expired, or cancelled.

GET {base}/api/partner-checkout/trials?status=active

Each row also reports converted and converted_order_id, so you can tell which clients you have already ordered for.

Convert to a paid subscription.
Place a normal order and add end_customer_id. No new client is created, the billing address is updated in place, and the running trial subscription is retired so the paid plan's limits take effect.

POST {base}/api/partner-checkout/orders
Idempotency-Key: 6f1c9a2e-order-0001

{
  "dry_run": false,
  "end_customer_id": 192601,
  "customer": { "email": "alice@example.com", ... },
  "company":  { "legal_name": "Sunrise Hospitality Pty Ltd",
                "abn": "10000000000" },
  "billing_address": { ... },
  "order": { "product_id": 243 }
}

customer.email must match the client named by end_customer_id, so an order can never be attached to the wrong account.

The free month is granted once per client. order.add_free_trial_month defaults to true and adds an extra month, so a monthly signup gets 2 months and an annual signup gets 13. A client who has already had a free trial does not get it a second time. The order still succeeds: free_trial_month_applied comes back false and warnings explains why. Read that field rather than assuming, so you never quote a client 13 months and deliver 12.

Cancel a trial with POST /api/partner-checkout/trials/cancel if it was provisioned against the wrong entity. Access ends immediately and the records are kept for audit. Full details, including every field and error code, are in the Partner Checkout Admin Endpoints Guide.

Using Your Access Token

Once you have received an access_token, you can begin calling protected endpoints by including it in the Authorization header of your HTTP requests, using the Bearer scheme:

    Authorization: Bearer YOUR_ACCESS_TOKEN

This is required for all endpoints that need authentication. Make sure to replace YOUR_ACCESS_TOKEN with the actual token string you received in Step 3 above.

Tip: You can test authenticated API calls directly on this documentation page. Click the “Authorize” button at the top right of the endpoint list and enter your access token in the HTTPBearer area of the popup. Once authorised, the Swagger UI will automatically include your Bearer token in requests while you explore.

Swagger Authorize Button

Swagger Authorize Token Entry

Security tip: Keep client_secret and refresh_token server-side only. Never expose them in a browser or mobile client.