NG-Payroll — Nigerian Payroll
The complete requirements capture of the Nigerian payroll as implemented in the Zerp ERP backend (zerp-be, development branch): a monthly pay-run engine with annualised PAYE withholding, configurable statutory contributions — Pension, NHF, NHIS, NSITF — GL journal posting, and on-screen payslips. Each module below summarises the capability and links to its detailed, testable requirements; the Processes tab walks the end-to-end operating cycle.
Configure
Item catalogue, item groups, contribution groups with scheme rates, tax brackets, GL accounts.
Enrol
Employee tax profiles, standing item assignments, statutory registration numbers.
Run
Snapshot inputs → calculate → approve → post journal → pay.
Remit
Per-run PAYE and contribution summaries feeding agency remittance.
Foundation
Setup & configuration CFG
Everything configured before the first run: the pay-component catalogue, reusable item bundles, statutory scheme rates, the year's PAYE parameters, and the ledger accounts.
Detailed requirements →Capabilities & scope
- Payroll item catalogue — allowance / deduction / overtime / tax-relief definitions with taxability, statutory bases, GL account, frequency, and the single basic-salary flag.
- Item groups — named bundles of items + default amounts, applied to many employees in one skip-and-report action.
- Contribution groups — statutory policies holding each scheme's rates, who pays, and GL payable accounts.
- Per-year tax brackets — PAYE bands auto-seeded; personal relief values operator-set.
- Company config — payroll GL accounts; spreadsheet import for catalogue, groups and assignments.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-CFG-I01/I02 | Maintain the item catalogue (no seeds); enforce a single basic-salary item. | Must |
FR-CFG-B01 | Define item groups and bulk-apply them into standing assignments with skip-and-report semantics. | Must |
FR-CFG-G01 | Define contribution groups whose configured rates the run applies. | Must |
FR-CFG-T01 | Per-year tax brackets; auto-seed bands for current + next year (reliefs ship as zero). | Must |
FR-CFG-A01 | Resolve GL accounts from config; refuse to post without a liability account. | Must |
Statuses & key values
Foundation
Employee payroll profile EMP
The payroll-relevant employee data: tax category and family reliefs, employment dates, contribution-group link, the standing item assignments that define pay, and per-scheme registration numbers.
Detailed requirements →Capabilities & scope
- Tax profile on the employee master — category, children, manual relief top-up.
- Standing item assignments — catalogue item + amount + effective window; no-overlap rule; annual ÷12 smoothing.
- Per-employee statutory numbers (TIN, pension PIN, NHF/NHIS/NSITF numbers).
- Spreadsheet import of assignments resolving employees by reference/PIN.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-EMP-P01 | Hold the tax/statutory profile on the employee master; payroll reads it without modifying it. | Must |
FR-EMP-A01/A02 | Assignments active by effective window at the pay date; no overlapping assignments of the same item. | Must |
FR-EMP-A03 | Annual amounts smooth ÷12. | Must |
FR-EMP-S01 | One registration number per scheme per employee, upserted via a single form. | Must |
Statuses & key values
Engine
Pay run lifecycle RUN
The monthly run: create → add employees (snapshotting leave, overtime, absence and contributions) → calculate → approve → post journal → mark paid, with reject/cancel paths and calendar-day proration for partial months.
Detailed requirements →Capabilities & scope
- Five-state lifecycle with status-driven editability and audited transitions.
- Period-input snapshotting from approved leave, timesheets and attendance; resync + manual overrides; items read live at calculate.
- Deterministic calculation — prorate → gross → statutory → PAYE → net → employer cost — written atomically.
- Live estimates on uncalculated lines; in-app notifications on approve / reject / paid.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-RUN-L01 | Enforce the status machine; every transition audited. | Must |
FR-RUN-E01 | Snapshot unpaid leave, overtime, absence and contributions per employee on add/resync. | Must |
FR-RUN-P01 | Prorate salary, allowances, deductions and the statutory base by calendar-day fraction for mid-month joiners/leavers. | Must |
FR-RUN-X01 | Calculate in the defined order, atomically; net pay floors at zero. | Must |
FR-RUN-W02 | Maker/checker separation (today the same user can calculate and approve). | Could |
Statuses & key values
Engine
Statutory contributions STA
Pension, NHF, NHIS and NSITF computed from contribution-group configuration — rates are tenant data, bases derive from tagged items (or basic + allowances), and every row stores prorated and full-month twin amounts.
Detailed requirements →Capabilities & scope
- Pension typically 8% employee / 10% employer of emoluments; NHF 2.5% of basic; NSITF 1% employer — configured, not coded.
- Scheme bases via item tagging (e.g. pension on basic + housing + transport).
- Employee shares feed PAYE relief ×12, uncapped; employer shares feed employer cost only.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-STA-R01 | One contribution row per scheme per employee per run, with prorated + full-month twin amounts. | Must |
FR-STA-R02 | Base = items tagged with the scheme, else basic + allowances; prorated for partial months. | Must |
FR-STA-C01 | Compute by configured value type: percentage of base or fixed amount (÷12 if annual). | Must |
FR-STA-C02 | Employer amounts never reduce employee pay and are excluded from the salary journal. | Should |
Engine
PAYE income tax TAX
Annualised monthly withholding: gross less a monthly slice of the annual reliefs, ×12, walked through the progressive PAYE bands (₦800k zero band to 25%), ÷12 — stateless month to month, no rebate.
Detailed requirements →Capabilities & scope
- Reliefs: personal / spouse / child from the year's bracket, statutory contributions (uncapped), item reliefs ×12.
- Per-year configurable bands, auto-seeded "Nigeria PAYE {year}" brackets.
- Identical math for draft estimates and final calculation.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-TAX-M01/M02 | The annualised computation, stateless across months, no rebate. | Must |
FR-TAX-R01/R02 | Personal reliefs from bracket + employee profile; statutory reliefs from full-month contributions ×12. | Must |
FR-TAX-B01 | Progressive band walk on the pay year's configured bands. | Must |
Finance
GL journal posting GL
An approved run becomes one balanced journal: DR Salary Expense (Σ gross); CR item deductions, employee statutory shares, PAYE, and per-employee net salary payable. Preview first; unmapped accounts block; journal required before payment.
Detailed requirements →Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-GL-L01 | Post one balanced entry per run with the defined legs; employer costs excluded by design. | Must |
FR-GL-P01/P02 | Dry-run preview; posting refuses on unmapped accounts or a missing liability account. | Must |
FR-GL-R01 | Re-posting replaces the prior entry — never two live entries per run. | Must |
Outputs
Payslip & outputs OUT
The on-screen payslip per run line (earnings, deductions, statutory shares, PAYE) and per-run contribution summaries for remittance. No documents or statutory files are generated today.
Detailed requirements →Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-OUT-P01 | Compose the payslip (earnings, deductions, summary) from every run line. | Must |
FR-OUT-S01 | Per-run contribution and PAYE summaries for remittance and reconciliation. | Must |
FR-OUT-P02 | Payslip PDF, e-mail and self-service access (absent today). | Could |
Reference
Glossary
| Term | Meaning |
|---|---|
PAYE | Pay-As-You-Earn — personal income tax withheld from salaries, remitted to the employee's State Internal Revenue Service. |
PITA | Personal Income Tax Act — the statute behind PAYE bands and reliefs. |
Pension (PRA 2014) | Contributory pension under the Pension Reform Act — employee 8% + employer 10% of monthly emoluments, paid to the employee's PFA. |
PFA | Pension Fund Administrator — holds each employee's retirement savings account (pension PIN). |
NHF | National Housing Fund — 2.5% of basic salary, remitted to the Federal Mortgage Bank. |
NHIS | National Health Insurance Scheme (now NHIA) — health insurance contributions where operated. |
NSITF | Nigeria Social Insurance Trust Fund — 1% employer levy under the Employee Compensation Act. |
TIN | Tax Identification Number — the employee's (and employer's) tax registration with FIRS/State IRS. |
Emoluments | The pension base — basic + housing + transport — modelled here by tagging those items to the pension scheme. |
Contribution group | Reusable policy holding each statutory scheme's rates, who pays, and its GL payable account. |
Item group | A named bundle of catalogue items + default amounts, bulk-applied into standing assignments. |
Annualisation | The PAYE method: monthly taxable ×12 → band walk → annual tax ÷12, computed independently each month. |
Reference
Known gaps — roll-up
The significant gaps in the implementation, consolidated from the detailed pages.