> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Run payroll with ReadyPay (Proliant)
> Walk through the embedded Proliant ReadyPay payroll wizard — select a calendar, preprocess, verify, reconcile, approve, and submit a run.
## Overview
The ReadyPay payroll run wizard at `/hr/payroll/runs/proliant` drives a single payroll cycle end-to-end against the Proliant ReadyPay engine. It is the HR-side cockpit for the [embedded payroll engine](/hr/proliant-payroll). You pick a pay calendar, push inputs, preview Proliant's gross-to-net, clear verification checks, reconcile totals, and approve the batch. Once you submit, Proliant funds the deposits and files taxes.
The seven steps map 1:1 to a server-side run state machine
(`draft → started → preprocessed → verified → approved → submitted → posting → posted | failed`),
so the wizard's active step is always derived from the live phase. If you reload the page mid-run, you land back on the correct step.
## Who it's for
HR and Finance admins responsible for cutting payroll. The page is gated by the `hr.proliant-payroll.run` permission. Reconciliation overrides additionally require `hr.proliant-payroll.override-reconciliation`.
## Prerequisites
* Your organization has the [Proliant HCM integration](/hr/hr-44-admin-guide) configured and active.
* A Proliant pay calendar is open for the period you want to run.
* Employee data, rates, deductions, and timesheets are synced to Proliant (or pushed via the integration's `push_timesheets` and employee push scopes).
* Earning, deduction, and accrual code mappings are reviewed in the **Code mappings** tab on the Proliant integration page.
* You hold the `hr.proliant-payroll.run` permission.
## Wizard steps
The wizard opens at **Select calendar** (step 1 of 7) and advances through the run state machine.
Pick the Proliant pay calendar for the period. Only calendars returned by `GET /Company/{companyId}/Earnings/calendars` appear here — if the calendar you expect is missing, confirm the period is open in Proliant.
Confirm the inputs that will be sent for preprocessing: employees in scope, pushed earnings, deductions, and timesheets. This is the last step before Proliant touches the data — back out here if the input set looks wrong. Selecting **Next** dispatches `start` and `preprocess` against the `proliant-payroll-run` edge function.
Review Proliant's gross-to-net preview: employee count, gross, net, taxes, and deductions. Numbers come from Proliant's preprocess response, not from Encore. Select **Next** to advance to verify.
Work through each verification check Proliant returns (missing rates, blocked employees, zero-hour exceptions, and similar gates). Each row has its own **Approve** action; you cannot continue until every check is approved or resolved at the source.
The reconciliation panel compares Encore's expected totals (gross, headcount, deductions) against Proliant's returned totals. Rows outside the tolerance are flagged.
* If everything is within tolerance, the panel passes and **Next** unlocks.
* If a row breaches tolerance, you can either fix the underlying input and re-run preprocess, or — if you hold `hr.proliant-payroll.override-reconciliation` — select **Override & continue**. Overrides are stamped with your profile ID and timestamp on the reconciliation row for audit.
Selecting **Submit** dispatches `approveBatch` followed by `submit` against the orchestration edge function. Once Proliant accepts the batch, the run cannot be cancelled from Encore — funding and tax filing are now in Proliant's hands.
The mutating submit is bound to **this** step only; the following Results step is read-only ([HR-44-EN-01](https://github.com/Encore-OS/encoreos/blob/development/specs/hr/specs/HR-44-EN-01-embedded-payroll-write-back-completeness-and-hardening.md) AC-5).
The final step is a read-only view of the submitted run: Proliant run identifiers, totals, and the status the run-poller has observed (`submitted`, `posting`, `posted`, or `failed`). Once Proliant emits the `JournalEntry`, the FA-43 consumer drafts a balanced GL entry for review in Finance & Accounting. This step exposes **no mutating action** — the run is already in Proliant's hands.
## Run state machine
The wizard never advances local state alone; each "Next" calls an orchestration action and the server-side phase moves the wizard forward on the next poll.
| Phase | Wizard step | Trigger |
| --------------------------------------------- | ------------------------------- | -------------------------------------- |
| `draft` | Select calendar / Inputs review | Page load with no run for the calendar |
| `started` | Preprocess preview | `start` action |
| `preprocessed` | Verify | `preprocess` action |
| `verified` | Reconcile | All verifications approved |
| `approved` | Approve & submit | `approveBatch` action |
| `submitted` / `posting` / `posted` / `failed` | Results | `submit` action and run-poller updates |
A run only ever rewinds from the server side — the UI does not let you step backwards once the run leaves `draft`.
## Reconciliation tolerance
Reconciliation compares expected vs. returned values for gross pay, headcount, and total deductions. The default absolute tolerance is `0` — any variance trips a breach. To loosen this for a tenant, set `reconciliation_tolerance` (a positive number) on the integration row's `custom_fields`:
```json theme={null}
{
"reconciliation_tolerance": 0.50
}
```
A tolerance of `0.50` means expected and returned values within \$0.50 of each other are treated as a match. Raise this only when you have a documented reason (for example, rounding between Encore's expected total and Proliant's per-employee math).
## Journal entry handoff
After Proliant marks a run `Posted`, the `proliant-run-poller` fetches the `JournalEntry` and emits an event the [FA-43 payroll JE consumer](/fa/overview) handles. The consumer:
1. Translates Proliant's `gl1`…`gl6` GL codes into Encore accounts via the **GL account** code mapping.
2. Builds a balanced draft `fa_journal_entries` row using Proliant's debit/credit transaction types.
3. Routes any unmapped GL code or unbalanced line set to the exception queue — nothing auto-posts.
Finance reviews and posts the draft entry in the FA workspace; there is no automatic posting.
## Permissions
| Permission | Grants |
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
| `hr.proliant-payroll.run` | Open the wizard, start a run, advance through preprocess / verify / approve / submit. |
| `hr.proliant-payroll.override-reconciliation` | Use **Override & continue** when reconciliation breaches tolerance. |
Both permissions are tenant-scoped. Assign them to HR/Finance admins responsible for cutting payroll. Platform and organization admins inherit access.
## Manual checks
For an off-cycle or correction payment outside a calendar run, use the **Manual check** button on
the payroll-run page. It targets exactly one actively mapped employee, a pay-period window, and a
single earning line — enter hours (with an optional rate, defaulting to the employee's current pay
rate) or a flat amount — and requires explicit confirmation before anything is written to payroll.
The edge function re-validates everything server-side (admin role, the vendor's `ManualCheck`
grant, idempotency); if ReadyPay has not granted the ManualCheck scope to your credentials yet, the
request comes back as an explicit skip (an info toast), never a silent success.
## Troubleshooting
* **No calendars appear.** No open calendars for the company. Confirm the pay period is open in Proliant before retrying.
* **Verify step never clears.** A verification check is unapproved or unresolvable. Resolve the source data (missing rate, blocked employee) in Proliant or Encore and re-run preprocess.
* **Reconciliation always fails.** Tolerance is `0` by default and Proliant's per-employee rounding can produce a $0.01–$0.50 variance. Either raise `reconciliation_tolerance` on the integration, or override the breach if you hold the override permission.
* **Run stuck on `submitted` or `posting`.** The run-poller pulls Proliant on a schedule (suggested every 15 minutes). If your environment's poller schedule has not been registered, contact your platform admin.
* **GL entry never appears in Finance.** The FA-43 consumer routes unmapped GL codes to the exception queue. Open the **Code mappings** tab on the Proliant integration page, ensure all `gl_account` rows have an Encore account assigned, and re-run the JE consumer.
## Related
This page documents shipped product behavior. It is not medical, legal, or
billing advice. Verify against your organization's policies and applicable
regulations before using it for clinical, compliance, or billing decisions.
Protected health information (PHI) shown in the product is governed by your
tenant's access controls and is never exposed in this documentation.