Skip to content

ADR-009-F: KeyPay Integration for Award Interpretation (Phase 1)

Status: Superseded by ADR-016-F (2026-04-18) Date: 2026-04-16 Decision Makers: Gautham Chellappa Depends on: ADR-006-F (Hexagonal ports)

Superseded. The decision to use KeyPay was reversed on 2026-04-18 when it became clear ASG Central v2 only has 10–20 Modern Awards actively configured (not the 120+ this ADR assumed), collapsing the build-cost justification for a commercial SaaS. The new path — v2 port for Phase 1, native engine over FWC Modern Awards Pay Database for Phase 2 — is in ADR-016-F. This document is retained unchanged below for audit trail per ADR immutability convention.

Context

Finnest must calculate pay rates across 120+ Modern Awards + Enterprise Agreements for Australian labour hire. Building a native award engine covering this surface area is 6+ months of specialist work, ~$500K, and carries ongoing maintenance as Fair Work updates awards quarterly.

KeyPay (Employment Hero Payroll) is an Australian-hosted award interpretation SaaS used by thousands of AU businesses. It covers the full award surface, maintains itself as awards evolve, and exposes a REST API.

A phased approach trades per-employee cost (paying KeyPay) against build cost (writing a native engine).

Decision

Phase 1 (launch): Use KeyPay API for award interpretation — all 120+ Modern Awards. Integrate via the AwardInterpreter hexagonal port (ADR-006-F).

Phase 2 (6–12 months post-launch): Build native NativeAwardEngine adapter for the top 15 Awards covering ~80% of placements by volume. KeyPay remains the fallback for the long tail.

Phase 3 (12–24 months, ROI-gated): Full native award engine for all 120+ Awards. KeyPay removed when ROI justifies.

KeyPay is retained in IRAP deployment because KeyPay is Australian-hosted (same adapter both envs).

Alternatives Considered

Option Rejected because
Build native award engine from the start ~$500K upfront; 6+ months before launch; maintenance burden while platform is still finding product-market fit
RatesCalc (Australian labour-hire SaaS) Designed for consultants clicking through UI; no developer API; A$99–140 per user per month; no KeyPay integration listed (would need two award engines) — see B12 analysis
Pay.me / other AU award SaaS Less mature APIs, narrower award coverage
Skip award interpretation entirely — hand-entered rates per placement Labour-hire industry standard is award-driven rates; manual entry is error-prone and legally risky

Consequences

Positive:

  • Launch with 120+ Award coverage on day one — competitive with established players (Fasttrack360 etc.)
  • Avoid $500K + 6 months of build cost before product-market-fit validation
  • KeyPay maintains awards as Fair Work updates — no quarterly maintenance burden on Finnest team
  • Hexagonal port (AwardInterpreter) means Phase 2 native engine is an adapter swap — no business logic changes
  • KeyPay is Australian-hosted → acceptable for IRAP deployment

Negative:

  • ~$5–10 per employee per month KeyPay cost
  • External API dependency — KeyPay outage stops rate calculation
  • Per-employee cost scales linearly (accelerates Phase 2 build ROI)
  • KeyPay API rate limits + quotas apply

Mitigations:

  • Finnest.Payroll.AwardInterpreter behaviour (port) — adapter swap is a config change
  • Response caching for rate calculations (rates stable between Fair Work updates)
  • Circuit breaker on KeyPay adapter — falls to cached rates on outage with human review flagged
  • Phase 2 NativeAwardEngine + KeyPay fallback (hybrid) reduces per-employee cost on top 15 Awards

Tipping points for re-evaluation:

  • KeyPay pricing increases materially → accelerate Phase 2 native build
  • KeyPay API stability drops → add second commercial award engine as fallback
  • Regulatory change (new labour category Fair Work doesn't cover) → native build for that category in advance of KeyPay

Related decisions (B12 gap analysis):

  • C5 Award-aware billing — Finnest billing reads KeyPay's penalty-timing response + applies client rate card multiplier. Does NOT need a second award engine (downgraded from HIGH to MEDIUM effort per B12 RatesCalc analysis).
  • C6 Timesheet-to-invoice automation — approved timesheets → KeyPay calculates pay → Finnest applies client rate card → invoice line generated automatically.
  • STP Phase 2 — can submit via KeyPay (Phase 1) or direct ATO API (Phase 2+ once we have the integration).

Relationship to Guardrails

Enforces / is enforced by: AR-15 (hexagonal ports for external integrations), D17 (financial precision in all rate calculations via ex_money + DECIMAL).