Xero Payroll UK
HollyHR's Xero Payroll UK connection is a first-party product integration. It does not use a customer API key, public API scope or MCP credential. A HollyHR System Admin connects one HollyHR organisation to one selected Xero organisation through Xero OAuth.
Open Integrations, choose Xero Payroll UK, then select Connect and enable leave sync. The Xero user completing consent must have Payroll Admin access.
If fresh verification is needed, HollyHR keeps the selected connection capability and continues to Xero after verification. The connection route rechecks current permissions before starting OAuth.
What the connector does
The connector supports a deliberately narrow approved-leave workflow:
- A System Admin explicitly matches a HollyHR person to one Xero employee.
- A System Admin explicitly maps a HollyHR leave category to one active Xero leave type.
- The admin can send an approved absence manually or enable background delivery for future approvals. Existing approved history remains manual.
- HollyHR retains the exact remote leave ID and uses only that ID if the absence is cancelled. With automatic sync enabled, eligible cancellations are checked and removed in the background; manual removal remains available.
Create requests use a deterministic idempotency key and an atomic local attempt claim. Xero retains keys for six minutes. HollyHR permits at most one create retry within five minutes of the local command's creation, with a final check before dispatch. Later uncertain outcomes require reconciliation, not another create. A retained receipt is checked with an exact read instead. HollyHR does not guess which Xero record to delete from a person's name or absence dates.
Automatic delivery uses a dedicated tenant-bound opt-in and expiring worker lease, not a borrowed administrator session or public API credential. Pausing stops new automatic work; an operation already underway may finish. Enabling requires acknowledgement that HollyHR manages the leave records it creates, including removal after cancellation. Earlier approvals-only grants cannot inherit that authority. Automatic cancellation checks the saved record against HollyHR's dates, category and recorded minutes first. Missing receipts, changed matches and provider discrepancies require review rather than guessed deletion. This readback is not a conditional-delete guarantee: a later edit in Xero can still be removed, which the setup acknowledgement explains. Disconnecting or reconnecting invalidates the previous automation connection generation.
Resuming the same managed connection preserves cancellation coverage for its
earlier managed leave, but starts a new cutoff for sending approvals. Approvals
from the paused period are not silently backfilled. The existing enabledAt
records the first managed-leave window and approvalsFrom the latest approval
cutoff; a new connection or policy starts both afresh.
Permission and data boundary
The initial connection uses offline_access and payroll.settings.read.
Enabling leave sync adds Xero's payroll.employees permission.
Xero groups employee matching and employee leave under that broad permission, alongside more sensitive payroll endpoints. HollyHR discloses the breadth but keeps a closed application endpoint inventory. The connector can only:
- list active leave types;
- list employees for explicit matching, including reviewed bulk suggestions from unique exact staff-ID/payroll-reference matches;
- read only assigned leave-type identifiers for mapped employee readiness;
- read exact pay-period boundaries for the absence dates;
- create leave for one exact employee;
- read back one exact retained leave record for reconciliation; and
- delete one exact leave retained by HollyHR.
Employee responses are projected in memory to employee ID, employee number, first and last name, work email and employment status. Raw employee responses are not persisted or returned to the browser.
When a retained leave receipt needs review, Check existing in Xero reads that exact record instead of creating another. Dates, leave type and hours are compared with HollyHR's recorded absence calculation. The provider's free-text description is compared inside the client and is not exposed. A matching record can recover the sync state; an absent or divergent record remains unresolved. This receipt-only action does not require fresh sensitive-action verification. It still requires an authenticated, authorised tenant administrator and a saved receipt on the current connection. It cannot create or delete provider leave. Sending, cancelling and changing integration settings retain their verification requirements; opted-in background delivery does not borrow the admin session.
When a page-level readiness check is unavailable or beyond the bounded batch, the explicit Check and send action performs the same check on demand. Unknown readiness is not reported as ready, and a failed check cannot reach the write.
Before a leave write, HollyHR checks that Xero has assigned the mapped leave type to that employee. If it is missing, HollyHR makes no write and directs the administrator to assign the policy in Xero. HollyHR never chooses an accrual schedule, balance or entitlement for the customer.
Leave writes allocate the recorded daily requested minutes to Xero's exact pay periods, including half-days and unequal working days. No duplicate working-hours fields are required. Missing calculation evidence or incompatible periods produces an exception rather than a date-only fallback. HollyHR checks the returned units before reporting success and retains the provider receipt for review if they differ or cannot be verified.
Setup validates the recorded daily calculation before offering to send. Missing or inconsistent hours produce an actionable readiness issue and a link to the existing person time-off page using its public identifier. The calculation breakdown stays server-side. Refreshing after repair rechecks readiness without replacing saved matches. This is a check of recorded absence hours, not a claim that HollyHR has inspected or reconciled the employee's entire Xero work pattern.
An additional advisory check reads effective-dated Xero working-pattern assignments and weekday schedules for mapped pending absences. It compares scheduled minutes, not partial-day requested minutes, and exposes only a three-state result. Known differences prompt review in the person's HollyHR record and Xero Payroll > Employees. Missing, truncated, ambiguous or unproven multi-week evidence is not a confirmed mismatch. These warnings do not replace or block the explicit recorded-hours send contract. No schedule is overwritten and no new hours field is introduced.
The connector does not call employee create or update, tax, payment-method, bank, salary, wage, payroll-run or payslip endpoints. Xero data is not sent to an AI provider or used to train an AI or machine-learning model.
Connection recovery
Use Check connection when the integration needs attention. A confirmed Xero 401, 403 or rejected refresh grant moves only the inspected connection generation to reauthorisation-required and clears its unusable local grant. Temporary network errors, malformed responses and Xero 5xx failures preserve the connection rather than inventing revocation.
Disconnect requires fresh administrator verification. HollyHR attempts Xero revocation, then always scrubs the exact local credential generation even when the provider is temporarily unavailable.
See the public Xero Payroll setup guide for the customer workflow.
Public API and export fallback
The Xero connection is not part of HollyHR's public API and does not make Xero OAuth tokens available to API or MCP callers. Use the Payroll Readiness Export when a payroll provider needs a reviewed manual hand-off or is not supported by a first-party connector.
HollyHR does not yet claim Xero certification or Xero App Store availability. HollyHR will apply for certification once the real-provider proof is complete, at least ten active customer connections exist and HollyHR is on the required Plus tier. A listing remains a provider-controlled outcome until Xero approves and publishes it.