The payroll layer, documented.

Getting started

Overview

Ledra Pay is provider-shaped: the API models what your platform ships — employees, pay runs, payslips, filings — not the internals of a calculation engine. Country logic lives in certified regulation packs attached per tenant; the request and response shapes are identical for every country.

All tenant-scoped routes are prefixed /v1/tenants/{tenantId}. Partner-scoped routes (tenant provisioning and lookup) are prefixed /v1/partners.

# Your first calculation — tenant-scoped, against a PE-native (DE) binding
curl https://sandbox.ledrapay.com/v1/tenants/ten_8f3c…/calculate \
  -H "Authorization: Bearer lp_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "monthly",
    "employee": { "residency": "resident" },
    "earnings": [ { "type": "ordinary", "amount": 3500.00 } ]
  }'

# calculate is capability-gated (stateless_calculate): native on PE-native
# (DE) bindings, 501 CAPABILITY_NOT_SUPPORTED otherwise. The unscoped
# POST /v1/calculate is a 501 stub — always call the tenant-scoped route.

Getting started

Authentication

Every request carries a partner-scoped bearer key. Keys are issued per environment (lp_sandbox_*, lp_live_*; legacy ps_* keys remain valid) and grant access only to tenants registered to your partner account — strict partner-to-tenant isolation is enforced at the gateway, not in your code.

Embedded UI components authenticate with short-lived embed tokens minted server-side via POST /v1/tenants/{tenantId}/embed/token. Partner keys never touch the browser, and embed tokens cannot mint further tokens — a leaked token dies at its 15-minute TTL. Tokens are pinned to one tenant; reads within that tenant are allowed, while writes are gated by the component allowlist (components in the mint body — e.g. a payslip-viewer token cannot approve a pay run). Two optional mint fields narrow scope further: employee_id pins the token to a single employee for employee-facing surfaces, and origin binds it to one browser origin (requests presenting a different Origin header are rejected).

Components can call https://api.ledrapay.com/v1 directly from your pages — CORS is enabled, bearer-only (cookies are never accepted cross-origin). Direct cross-origin calls require an origin-bound token: mint with { "origin": "https://app.yourdomain.com" } and set api-url="https://api.ledrapay.com/v1" on the components. Alternatively, mount a same-origin reverse proxy on your own domain and skip CORS entirely — both integrations are first-class. The vendor embedding guide covers both topologies, token scoping, and the launch checklist.

Access control

User tokens & role-based access

For a full app where many users of one organisation each get restricted access (the enterprise model), mint a user token — an embed token plus a role and a data scope. Mint server-side with a partner key (or a tenant admin user token) via POST /v1/tenants/{tenantId}/users/token:

{ "role": "preparer",
  "scope": { "cost_centres": ["OPS-ACS"], "sites": "*" },
  "user_id": "usr_…", "user_name": "Priya P." }

Roles enforce segregation of duties (not a linear ladder). The API gate is the boundary; the SDK mirrors it by hiding/disabling buttons (query GET /v1/tenants/{id}/me for the caller's role + scope):

Data scope restricts which rows a user sees by cost-centre/site. It fails closed: a scoped user querying a data source that can't attach the cost-centre dimension receives an empty result with scope_not_enforceable: true — never unfiltered data. (Cost-centres are a governed overlay, not engine-native; enforcement is full where the overlay is present and honest-empty where it isn't yet.) Unscoped users ("*") are unaffected.

Bureau

Portfolio API

For a payroll bureau / MSP running payroll across many client companies (the bureau model), the portfolio endpoints aggregate across every tenant on the partner key. Partner key only — tenant-scoped embed/user tokens are refused (they can't span a portfolio). First-party use behind an operator session; the partner key is never exposed to the browser.

The bureau SDK components (ledrapay-portfolio-dashboard, ledrapay-client-list, ledrapay-pipeline-board) render these. Because they carry portfolio-wide access they authenticate via a same-origin session only and must never be embedded in an untrusted page — see the SDK docs.

Getting started

Conventions

Idempotency

All POST endpoints accept an Idempotency-Key header. Retries with the same key return the original response for 24 hours. Use it on everything that creates pay runs or submits to an authority.

Pagination

List endpoints return data, has_more, and next_cursor. Pass ?cursor= and ?limit= (max 200).

Money and dates

Amounts are decimal strings with an explicit currency (ISO 4217). Dates are YYYY-MM-DD; timestamps are UTC ISO 8601. Identifiers are prefixed: ten_, emp_, pr_, ps_, ldg_, evd_.

Versioning

The API is versioned in the path (/v1) and changes additively. Regulation packs are versioned independently (AU-2026.1) — statutory updates ship as new pack releases, never as silent behaviour changes under a pinned version.

Getting started

Core concepts

Platform

Partners & tenants

Provision a tenant per employer. A tenant is created with its engine binding (pack + version) attached at provisioning time — the pack is pinned on the binding, not patched in later.

Platform

Regulation packs

Packs are how Ledra Pay stays one integration across countries. Attach a pack to a tenant and pin a version; the pay run API never changes shape. Certification status, maintainer, and changelog are queryable — compliance is an API object, not a PDF.

{
  "code": "AU",
  "current_version": "AU-2026.1",
  "status": "beta",                  // draft | beta | certified
  "maintainer": "Ledra Pay Compliance (AU)",
  "scope": ["paye_tax", "medicare_levy", "stsl", "super_guarantee", "awards", "payroll_tax_state"],
  "lodgement_rails": [{ "type": "STP2", "channel": "ATO-SBR", "status": "in_build" }],
  "versions": [{ "version": "AU-2026.1", "effective": { "from": "2026-07-01", "to": "2027-06-30" } }]
}

Capability matrix

GET /tenants/{tenantId}/packs returns the attached pack(s) with a capability matrix per binding. Capabilities are how the one API stays honest across engines that genuinely differ: a feature is either native or unsupported, never silently faked. An unsupported call returns 501 CAPABILITY_NOT_SUPPORTED with the alternatives, not a wrong answer.

{
  "data": [{
    "binding_id": "bnd_…", "engine": "…", "pinned_version": "DE-2026.1",
    "capabilities": {
      "effective_dating": "native",        // as_of reads / effective_from writes
      "stateless_calculate": "native",     // forecast /calculate with no pay run
      "statutory_lodgement": "unsupported",
      "payment_file": "unsupported",
      "payslip_pdf": "unsupported"
    }
  }]
}

Platform

Organisation

Roadmap — not yet available

People

Employees

One employee model for every country. Country-specific fields (TFN declarations, UK tax codes, NI numbers) live under tax_profile, validated by the tenant's attached pack — your integration code stays identical.

Effective dating

Employee facts are effective-dated on engines that support it (capability effective_dating: native): a write carries an optional effective_from that stamps when the change takes effect, and a read carries an optional as_of that resolves the value in force on that date (default: today). A future-dated raise is the canonical case — it does not change "now", but it is already on file.

// DE / PE-native packs only — AU (myaccountant) returns 501 for a non-today date
// future-dated raise — takes effect 2026-09-01, not today
PATCH /tenants/{t}/employees/emp_8f3c…
{ "employment": { "annual_salary": 90000 }, "effective_from": "2026-09-01" }

GET …/employees/emp_8f3c…?as_of=2026-08-01   → annual_salary 60000   // before
GET …/employees/emp_8f3c…?as_of=2026-10-01   → annual_salary 90000   // after
GET …/employees/emp_8f3c…                  → annual_salary 60000   // today (raise still future)

People

Timesheets

Roadmap — not yet available

Payroll

Pay runs

The pay run is a state machine: draft → previewed → approved → finalised. Preview never advances state — call it as often as you like; approve is a control-plane transition (an evidence envelope, no engine command); finalise commits to the engine. lodged, forecast and retro variants are roadmap.

# Preview response (abridged) — identical shape for every country
{
  "pay_run": "pr_8f2c", "status": "previewed", "pack": "AU-2026.1",
  "entries": [{
    "employee": "emp_31ad",
    "gross": { "amount": "3269.23", "currency": "AUD" },
    "lines": [
      { "type": "tax.paye",          "amount": "-612.00" },
      { "type": "tax.medicare_levy", "amount": "-65.38" },
      { "type": "employer.super_guarantee", "amount": "392.31", "employer_cost": true }
    ],
    "net": { "amount": "2591.85", "currency": "AUD" }
  }],
  "evidence": "evd_a90b"          // every calculation is receipted
}

Entries — the cross-country shape

GET …/pay-runs/{prId}/entries returns one row per employee with a jurisdiction-stable core and pack-variant extras. The core is guaranteed identical in every country; extras are additive per pack and never replace core fields.

{
  "data": [{
    // core — every pack, always (amounts are 2dp decimal strings)
    "id": "…", "employee_id": "emp_0e4c888c5987c068",
    "employee_name": "Alex Chen",
    "gross": "1140.00", "tax": "299.00", "net": "841.00",

    // pack-variant extras (additive):
    "super": "136.80",          // AU/NZ: superannuation / KiwiSaver
    "social": "1057.50",        // DE: KV+RV+AV+PV employee share
    "wage_types": [ "…" ]        // PE-native packs: full statutory line breakdown
  }],
  "evidence_id": "cev_…"
}

Rows with all-zero amounts are engine truth, not errors: employees active in the period but with no pay items yet. Currency lives on the run's totals, never per entry.

Payroll

Shadow runs

Roadmap — not yet available

Prove the numbers before anything goes live. Post the inputs from a real payrun together with your incumbent provider's results; Ledra Pay calculates independently and returns a line-level variance report. Shadow runs never lodge, never pay, and never touch production state.

{
  "shadow_run": "sh_c41e",
  "summary": { "entries": 640, "matched": 634, "divergent": 6, "max_variance": "4.85" },
  "divergences": [{
    "employee": "emp_99c2", "line": "tax.stsl",
    "incumbent": "128.00", "ledrapay": "123.15",
    "explanation": "Incumbent applied 2024-25 STSL thresholds after 1 July"
  }]
}

Payroll

Calculation engine

Stateless gross-to-net for embedding calculations in your own UX — quote a net salary in onboarding — without creating payroll objects. Tenant-scoped and capability-gated: stateless_calculate is native on PE-native (DE) bindings and unsupported elsewhere (501). The unscoped POST /v1/calculate is a 501 stub that returns the capability matrix — always call the tenant-scoped route.

Payroll

Statutory lodgement

Roadmap — not yet available

Payroll

Payslips & payments

Trust

Governance

Every state-changing call writes an immutable evidence record into a hash chain: actor, reason, inputs digest, pack version, result digest. When a regulator, auditor, or customer asks "why was this payslip this number", the answer is one API call.

Trust

Reference data

Roadmap — not yet available

Integrate

Webhooks

Roadmap — not yet available

Subscribe to events; deliveries are signed (Ledra Pay-Signature, HMAC-SHA256) and retried with backoff for 72 hours.

Integrate

MCP & agents

The REST write path is already governance-first: write operations require a governance_reason, supplied either as a body field or the x-governance-reason header — it lands in the evidence chain on every state-changing call. Omitting it returns 400 governance_reason_required.

Roadmap — MCP server not yet available

Ledra Pay will ship an MCP server so AI agents can operate payroll safely. Every tool carries a risk tier; all write tools require a governance_reason; high and critical tools support human-approval gates configured per partner. The tool catalogue below is the planned surface, not yet callable.

Integrate

Errors

Errors are JSON with a stable code, human message, and — for pack validation failures — the statutory rule that rejected the input. code values are snake_case (pack_validation_failed, state_conflict, governance_reason_required), except the load-bearing CAPABILITY_NOT_SUPPORTED.

{
  "error": {
    "code": "pack_validation_failed",
    "message": "tax_profile.tfn failed checksum validation",
    "rule": "AU-2026.1/identity/tfn_algorithm",
    "status": 422
  }
}