NG-Payroll — Process Flows

Phase A · One-time Setup

Configure payroll foundations setup

HR and Finance stand up everything a run depends on. Statutory types and PAYE bands self-seed; the item catalogue, contribution-group rates, personal reliefs and GL accounts are operator work — including every statutory rate.

Flow

1. 1
   SystemSeeds foundations at boot.Statutory type masters (paye, pension, nhf, nhis, nsitf) and a tax bracket per current + next year (Nigeria PAYE {year} with the default band scale). Personal reliefs seed as zero — they must be set by hand. Idempotent.
2. 2
   HR AdminSets the year's relief values on the tax bracket — individual, spouse, per-child.The run reads reliefs from the bracket only; leaving them at zero over-withholds PAYE for everyone.
3. 3
   HR AdminBuilds the item catalogue — Basic Salary, housing/transport and other allowances, deductions, tax reliefs (create or import).Each item carries taxability, statutory-base tags, GL account and frequency. Only one item may be basic salary. Nothing is pre-seeded.
4. 4
   HR AdminDefines the statutory contribution group with the legal rates — pension 8%/10%, NHF 2.5% (tagged to basic), NSITF 1% employer, NHIS per policy.Rates are configuration: the engine applies whatever is entered and never validates against statute. Use percentage value types; the table type computes zero.
5. 5
   HR AdminOptionally bundles standard packages as item groups (e.g. "Junior Staff Package").Groups bulk-apply into standing assignments later; editing a group never rewrites what was already applied.
6. 6
   Finance AdminSets the payroll GL accounts in company configuration.Salary expense, PAYE payable, and net-salary liability accounts; per-scheme payables on the contribution group; per-deduction payables on the items.

Rules & gotchas

• A year with no tax bracket silently computes zero PAYE — verify brackets and reliefs each new year.
• Deduction items without GL accounts will later block journal posting.
• The employer-expense config account is currently unused — employer statutory costs are not journalled.

End state

Catalogue, statutory group with rates, brackets with reliefs, and accounts in place — employees can be enrolled.

Phase B · Onboarding

Enrol an employee into payroll enrol

A hired employee becomes payable: tax profile completed, statutory numbers recorded, contribution group linked, and standing items assigned — singly, by import, or by applying an item group.

Flow

1. 1
   HR AdminCompletes the payroll profile — tax category, number of children, any manual relief top-up, join date, attendance group.These drive spouse/child reliefs, proration, and the working-day context for leave/overtime/absence.
2. 2
   HR AdminLinks the employee to the statutory contribution group.No group → no pension/NHF/NSITF contributions at all.
3. 3
   HR StaffRecords the employee's statutory numbers — TIN, pension PIN, NHF/NHIS/NSITF numbers.Identity only; blanks never block computation.
4. 4
   HR StaffAssigns standing items — Basic Salary with the monthly amount plus allowances/deductions, dated from the join date — individually, via spreadsheet import, or by applying an item group to a batch of hires.Active window = pay date within [start, end]. No overlapping assignments of the same item; a group apply skips conflicts and reports them. Annual amounts smooth ÷12.

Rules & gotchas

• The basic-salary assignment is what the run pays; the employee's basic-salary field is only a fallback.
• Salary revisions: end-date the old assignment, start a new one — history stays intact.
• No bank details exist anywhere — disbursement happens outside the system.

End state

The employee is fully payable: profile, group, numbers and standing items in place.

Phase C · Monthly Cycle

Monthly pay run — draft to paid run

The core cycle: a run for the month, employees join with attendance inputs snapshotted, the engine calculates contributions and PAYE, approval locks figures, the journal posts the accrual, and the run is marked paid.

Flow

1. 1
   HR AdminCreates the run — name, pay date, optional period window.Status DRAFT. The pay date's month anchors proration and the period default; its year selects the tax bracket.
2. 2
   HR AdminAdds employees to the run.Per employee: snapshot basic salary; unpaid leave (approved unpaid days × gross ÷ working days); overtime (approved timesheet hours × hourly rate); absence (working days − present days × daily rate); and one contribution row per scheme at the group's configured rates — prorated and full-month amounts both stored.
3. 3
   HR AdminReviews the draft — live estimates per line; adjusts assignments, overrides line inputs, or resyncs after changes.Items are read live at calculate, but contribution changes need a resync; resync overwrites manual overrides.
4. 4
   HR AdminRuns the calculation.Per employee: prorate → gross → statutory sums → annualised PAYE (reliefs ÷12, ×12 band walk, ÷12) → net (floored at 0) → employer cost. All lines + totals written in one transaction; status → PENDING_APPROVAL; any journal link cleared.
5. 5
   HR AdminApproves the run.Status → APPROVED; figures locked; in-app notification to creator and managers. (Reject → back to DRAFT with figures zeroed.)
6. 6
   Finance AdminPreviews the journal, picks the net-salary liability account, posts.Preview surfaces unmapped items — posting refuses until every deduction/scheme has a GL account. Entry dated on the pay date, linked to the run.
7. 7
   Finance AdminPays salaries through the bank (outside the system) and marks the run paid.Mark-as-paid requires the posted journal. Status → PAID (terminal). Settling the salary-payable liability is a separate manual finance entry.
8. 8
   HR StaffShares payslips.Payslips render on-screen per line. No PDF/e-mail/self-service distribution exists — a known gap.

The journal (one balanced entry per run)

Employer statutory shares are deliberately excluded — tracked on the run, settled and accounted for outside the salary journal.

Rules & gotchas

• Approval is procedural — the same user can calculate and approve (no maker/checker).
• A one-off payment in the month annualises ×12 for PAYE with no later catch-up — expect over-withholding in bonus months.
• Loan instalments, advances and claim reimbursements must be entered as item assignments — nothing flows in automatically.

End state

A PAID run with locked figures, a balanced GL accrual, and per-line payslip data plus contribution summaries for remittance.

Phase D · Exceptions & Variations

Reject, re-run & special cases exceptions

Reject loop

1. 1
   HR AdminRejects a pending run.Status → DRAFT; every line's calculated figures zeroed so stale numbers never display as final.
2. 2
   HR AdminFixes assignments/inputs, resyncs, recalculates, re-approves.Audit captures every transition; manual line overrides must be re-applied after resync.

Special cases

End state

Corrected figures re-approved, or the run cancelled with a full audit trail.

Phase E · Statutory Remittance

Monthly agency payments remit

Paying the withheld and employer amounts to the agencies. The system supplies the figures; submissions and payments happen on the agency portals — no schedules or files are generated.

Flow

1. 1
   Finance AdminReads the run's summaries — PAYE total and employee + employer amounts per scheme, with per-employee rows for schedules.Grouped per statutory type on the run; per-employee contribution rows support PFA schedule preparation.
2. 2
   Finance AdminRemits to each body — PAYE to the State IRS, pension (employee 8% + employer 10%) to each employee's PFA, NHF to FMBN, NSITF/NHIS as applicable.Figures are re-keyed manually — the system produces no remittance schedules, upload files or receipts tracking.
3. 3
   Finance AdminClears the payable accounts with manual journals as payments land.The salary journal accrued only employee-side liabilities; employer pension/NSITF were never journalled and need their own entries.

End state

All agency liabilities for the month settled; payable accounts cleared.

Phase F · Year-end

Annual compliance yearend

After the December run: the employer's annual PAYE returns to each State IRS (due 31 January), employee tax deduction summaries, and the new year's tax bracket verified — all prepared from run data, filed outside the system.

Flow

1. 1
   HR AdminConfirms every run of the year is finalised and reconciles total PAYE withheld per employee.Because monthly PAYE is annualised with no true-up, the year's total withholding can differ from the true annual liability — reconcile before filing and handle differences per State IRS guidance.
2. 2
   HR AdminPrepares and files the employer's annual return (Form H1 / state equivalent) with per-employee emoluments and PAYE.Compiled manually from run data — no annual return document is generated (known gap).
3. 3
   HR AdminVerifies the new year's tax bracket against the current Finance Act — bands and relief values.The seed created the bracket with default bands and zero reliefs; set the relief values before the January run.

End state

Annual returns filed, the new year's parameters confirmed — the January run can proceed.