Payroll

The Payroll workspace is where a payroll period becomes real numbers. It is server-authoritative: the calculation, the totals, and the finalization all happen on the payIQ server, and the screen displays the results.

Payroll moves through three states, in order:

Status	Meaning
Draft	A run exists for a period but has not been calculated.
Calculated	Results and snapshots exist. The run can be recalculated.
Finalized	Results are locked and one payslip per employee result has been created.

Payroll periods and runs

A payroll period is a calendar window — for example a month — with a start date, an end date, and usually a pay date. Periods are defined ahead of time.

To create a run:

In the header, choose the period from the period selector.
Select Create payroll run.
The new run appears in the Payroll runs list with status Draft.

The run list shows each run’s period, status badge, employee count, payslip count, gross, deductions, PAYE, pension, net, and when it was calculated. Select a row to open the run.

Reviewing and calculating a run

Open a run to see its detail. While the run is not finalized you can select Calculate payroll, or Recalculate payroll once results exist.

Calculation:

Includes only employees who are employment-active, payroll-active, and payroll-eligible, and who were employed for the whole period. Mid-period joiners and leavers are not prorated and are not included.
Uses the compensation and component assignments in force at the end of the period.
Uses the reviewed statutory rules in force for the pay date (or the period end when there is no pay date).
Currently supports GHS, resident-monthly, monthly-salary employees with fixed-amount components.
Fails closed rather than guessing. Missing, ambiguous, or unsupported configuration produces a readable error and no partial result.

Recalculation is explicit. It replaces the previous not-yet-finalized snapshot in one atomic step: if anything fails, the previous calculation is kept.

After calculation the run shows metric cards — Results, Gross payroll, Employee deductions, Net payroll (and Advance deductions when relevant) — an Employee results table, and a Calculation references card naming the PAYE rule, the SSNIT rule, and the calculation version used.

Finalizing a run

When a run is Calculated, the header offers Finalize payroll.

Select Finalize payroll.
A confirmation panel appears: Finalize this payroll run? It explains that the run will be locked, that a payslip is created for every result, and that it cannot be undone.
Select Confirm finalization.

Finalization verifies the stored snapshots and totals first. If anything does not reconcile, nothing is committed — the run stays calculated with no payslips. If it succeeds, the run becomes Finalized, records who finalized it and when, and creates one immutable payslip per employee result.

After finalization the run also shows a Payslips table and status cards for the payment position and the accounting handoff.

Reading a payroll result

Select an employee in the Employee results table to open their result snapshot. It shows Gross pay, Employee deductions, Employer costs, and Net pay, with expandable sections for:

Earnings — basic salary and any fixed earnings.
Deductions — employee deductions, SSNIT, and PAYE.
Salary advance deduction — where a payroll advance repayment was planned.
Statutory calculation — the PAYE calculation, including the bands used.
Employer costs — employer pension contributions and other employer costs.
Snapshot references — the configuration and rule versions recorded.

Every line records its description, rate, basis, and amount.

Payslips

A finalized run produces one payslip per employee result. Open a payslip from the run’s Payslips table with View payslip.

The payslip view shows the employee, period, earnings, deductions, net pay, employer contributions, and reference versions. It offers:

Printable document — a self-contained print-optimized page.
Print / Save as PDF — uses your browser’s print dialog, so you can save a PDF from the browser.

The payslip is a snapshot. It does not change if the employee is renamed, if new compensation takes effect later, or if a statutory rule is superseded.

Payment and accounting positions

For a finalized run, the run detail shows:

A Payment position card: how many payment instructions exist, how much is payable, paid, and outstanding.
An Accounting handoff card: whether the run has been offered to LedgerIQ.

If your role allows it, Prepare payment creates the payroll payment instructions. See Payments.

What you can and cannot do

You can: create runs for configured periods, calculate and recalculate a non-finalized run, finalize a calculated run once, view results and payslips, print a payslip, and prepare payment obligations for a finalized run.

You cannot: unfinalize, edit a finalized run, change a finalized payslip, mark payroll as paid, prorate a mid-period joiner, or calculate daily/hourly rates or rate-based components. These are deliberate limits, not bugs.

Who can do what here

Action	Roles
View payroll runs, results, and payslips	Payroll Operator, Approver, Administrator
Create a run, calculate, and recalculate	Payroll Operator, Approver, Administrator
Finalize a run	Payroll Operator, Approver, Administrator
Prepare a payment from a finalized run	Payroll Operator, Administrator

A Read-only Reporter does not see payroll-run detail, and the reporter’s report set is deliberately non-monetary. See Roles & access.

Preparation checklist and readiness

Open a run to see its live preparation checklist. It covers the period, eligible employees, compensation coverage, statutory rules, approved attendance/leave consequences, planned advance deductions, prior comparison and calculation status. Select Refresh review after correcting setup.

BLOCKING means the existing calculator rejects an input; calculation is unavailable until corrected. Readiness reports the first domain failure, so refresh after each correction. WARNING and INFORMATIONAL explain inputs without adding new rules. No eligible employees is a warning: the existing engine allows empty calculation, but an empty calculated run cannot be finalized. Mid-period employees are excluded by existing full-period eligibility; there is no proration. Readiness writes no results, consumes no consequence and repays no advance.

Review, variance and attention

After calculation, Calculation review shows employee count, gross, deductions, net, chargeable income, PAYE, employee/employer SSNIT, other and advance deductions. These values are persisted server snapshots. Open an employee from the result table to inspect its composition and statutory references.

Comparison uses the latest strictly earlier period with results, preferring its finalized run over a calculated run. Drafts never qualify. Aggregate and employee changes show absolute and percentage values; a zero prior denominator has no percentage. New and removed employees are identified separately. With no earlier payroll, the screen explicitly says comparison is unavailable.

Attention indicators use ERROR, WARNING, and INFO. Snapshot validation errors prevent finalization. Operational warnings do not: net variance at least 20% and GHS 500, net at or below 20% of gross, and deductions at least 50% of gross are review prompts. Compensation/statutory changes, advances and approved consequences are informational. Thresholds are documented defaults, not calculation inputs.

Finalization and history

Finalize payroll opens an explicit confirmation showing the period, calculation time/version, employee count, gross/deductions/net, warning count, consequences to consume, repayments to commit, payslips and accounting handoff. Check the figures before Confirm finalization. The server rechecks live repayment and consequence state atomically; a successful review is not a guarantee that later finalization will succeed. This creates neither a transfer nor a posted journal.

Finalized payroll shows its actor/time, immutable totals, results, payslips, accounting handoff and payment progress. It cannot be edited or recalculated. History is ordered newest period first, supports status filtering and displays up to 50 runs per page. The API accepts offsets through 10,000; larger offsets are rejected so history queries stay bounded. Use Next page / Previous page for older runs. Prepare a subsequent run by selecting its separately configured period; copying old calculations or deductions is not supported.

Calculate and finalize requests require the reviewed run revision. If another operator changes the run, the action returns a stale-review conflict; refresh the review, inspect the current figures and confirm again.