MY-Payroll — Malaysian Payroll
The complete requirements capture of the Malaysian payroll as implemented in the Zerp ERP backend (zerp-be, dev-my branch): a monthly pay-run engine with the full Malaysian statutory stack — EPF/KWSP, SOCSO/PERKESO, EIS/SIP, HRDF and PCB/MTD income tax — plus GL journal posting, payslips, and the annual EA Form (CP8A) and Borang E (CP8D). 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, contribution groups, tax brackets, statutory identity, GL accounts.
Enrol
Employee tax profiles, standing item assignments, statutory numbers.
Run
Snapshot inputs → calculate → approve → post journal → pay.
Comply
Payslips, EA Forms, Borang E + CP8D; statutory amounts for remittance.
Foundation
Setup & configuration CFG
Everything configured before the first run: what pay components exist, which statutory schemes apply to whom, the year's tax parameters, the employer's agency registrations, and the ledger accounts.
Detailed requirements →Capabilities & scope
- Payroll item catalogue — allowance / deduction / overtime / tax-relief definitions carrying taxability, statutory bases, EA-form category, GL account, frequency, and the basic-salary and bonus flags.
- Contribution groups — reusable statutory policies mapping schemes to who-pays and GL payable accounts.
- Per-year tax brackets — PCB bands, personal reliefs and statutory relief caps, auto-seeded from LHDN defaults.
- Company statutory identity — one employer registration number per scheme (EPF / SOCSO / EIS / LHDN).
- Company config — payroll GL accounts and the HRDF toggle/rate; spreadsheet import for catalogue, groups and assignments.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-CFG-I01 | Maintain the payroll item catalogue with full behavioural flags; no items are seeded — the catalogue is tenant-defined. | Must |
FR-CFG-I02 | Enforce a single basic-salary item per company. | Must |
FR-CFG-G01 | Define contribution groups listing statutory types with who-pays and per-scheme GL accounts. | Must |
FR-CFG-T01/T02 | Maintain per-year tax brackets; auto-seed current + next year from LHDN defaults at boot. | Must |
FR-CFG-S01 | Hold one employer registration number per statutory scheme, upserted via a single form. | Must |
Statuses & key values
Foundation
Employee payroll profile EMP
The payroll-relevant employee data: tax profile, nationality and birth date (which parameterise every statutory rule), the standing item assignments that define pay, and per-employee statutory numbers.
Detailed requirements →Capabilities & scope
- Tax profile on the employee master — residency, tax category, children, manual relief top-up.
- Standing item assignments — catalogue item + amount + effective date window; no-overlap rule; annual ÷12 smoothing.
- Per-employee statutory registration numbers for payslips and annual forms.
- Spreadsheet import of assignments resolving employees by reference/PIN and items by name.
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 | Assignments are active for a run when the pay date falls inside their effective window. | Must |
FR-EMP-A02 | No overlapping active assignments of the same item per employee. | Must |
FR-EMP-A03 | Annual amounts smooth ÷12 — except additional remuneration, which pays in full. | Must |
Statuses & key values
Engine
Pay run lifecycle RUN
The monthly run: create → add employees (snapshotting overtime, unpaid leave, 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; DRAFT is the only editable state.
- Period-input snapshotting from approved leave, timesheets and attendance; resync + manual overrides.
- Deterministic calculation order — prorate → gross → statutory → PCB → 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, statutory base and HRDF base by calendar-day fraction for mid-month joiners/leavers. | Must |
FR-RUN-X01 | Calculate in the defined order and write all lines + roll-ups in one transaction; 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
Malaysia's mandatory wage contributions, computed from a built-in legal schedule: EPF (no ceiling, round up to the ringgit), SOCSO and EIS (RM6,000 ceiling, 5-sen rounding), and the employer-only HRDF levy.
Detailed requirements →Capabilities & scope
- EPF/KWSP: 11% + 13/12% under 60; 0% + 4% at 60+; foreign workers 2%/2% from 1 Oct 2025.
- SOCSO/PERKESO: Category 1 (1.75%/0.5%) under 60, Category 2 (1.25%/0%) at 60+; EIS 0.2%/0.2% ages 18–59.
- HRDF: configurable employer levy on prorated basic + fixed allowances, Malaysian employees only.
- Custom (non-scheduled) contributions honour percentage/fixed group configuration.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-STA-R01 | One contribution row per scheme per employee per run, with prorated and full-month twin amounts. | Must |
FR-STA-R03 | EPF/SOCSO/EIS always follow the legal schedule — configured group rates are ignored. | Must |
FR-STA-E01/E02 | EPF per the rate schedule with age/citizenship/wage rules and the foreign-worker effective date. | Must |
FR-STA-S01 / I01 | SOCSO and EIS on min(wage, RM6,000) with age categories and 5-sen rounding. | Must |
FR-STA-H01 | HRDF employer levy when enabled — never an employee deduction, never journalled. | Must |
Engine
PCB / MTD income tax TAX
The LHDN Computerised Calculation: annualised chargeable income with capped reliefs, progressive band walk, s.6A rebate, year-to-date true-up, bonus differential method, zakat offsets, and a flat 30% for non-residents.
Detailed requirements →Capabilities & scope
- Monthly MTD with months-remaining projection and true-up against tax already withheld this year.
- Reliefs: EPF (cap RM4,000), SOCSO+EIS (cap RM350), personal/spouse/child (configurable per year), item reliefs ×12.
- Bonus/commission/arrears taxed by the LHDN differential method — never smoothed or prorated.
- LHDN rounding (truncate then round up to 5 sen) and the RM10 remittance floor.
Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-TAX-D01/D02 | Non-residents at flat 30%; residents by the official MTD method in every real run. | Must |
FR-TAX-M01 | The full monthly MTD formula with YTD true-up, relief caps, RM10 floor, LHDN rounding. | Must |
FR-TAX-B01/B02 | Per-year configurable bands + s.6A rebate; brackets auto-seeded with default reliefs. | Must |
FR-TAX-A01/A02 | Additional remuneration taxed by the differential method, paid in full. | Must |
FR-TAX-Z01 | Zakat offsets PCB ringgit-for-ringgit. | Must |
Finance
GL journal posting GL
An approved run becomes one balanced journal: DR Salary Expense (Σ gross); CR item deductions, employee statutory shares, PCB, 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 |
Compliance
Payslip & statutory forms OUT
The on-screen payslip per run line; the annual EA Form (CP8A) per employee with sections A–F mapped from payroll data; and Borang E with the CP8D employee listing — all aggregating finalised runs by pay-date year.
Detailed requirements →Key requirements
| ID | Requirement | Priority |
|---|---|---|
FR-OUT-P01 | Compose the payslip (earnings, deductions, summary) from every run line. | Must |
FR-OUT-EA01 | Generate the EA form per employee per year — structured data, HTML preview, A4 PDF. | Must |
FR-OUT-BE01/BE02 | Generate Borang E + CP8D with derived-but-overridable headcounts. | Must |
FR-OUT-AG01 | Aggregate only approved/paid runs, by the pay date's calendar year. | Must |
Reference
Glossary
| Term | Meaning |
|---|---|
EPF / KWSP | Employees Provident Fund (Kumpulan Wang Simpanan Pekerja) — mandatory retirement savings. |
SOCSO / PERKESO | Social Security Organisation — employment injury + invalidity insurance. |
EIS / SIP | Employment Insurance System (Sistem Insurans Pekerjaan) — retrenchment protection. |
PCB / MTD | Potongan Cukai Bulanan / Monthly Tax Deduction — income tax withheld from salary per LHDN's Computerised Calculation. |
LHDN | Lembaga Hasil Dalam Negeri — the Inland Revenue Board of Malaysia. |
HRDF / HRD Corp | Human Resource Development Fund — employer-only training levy. |
EA Form / CP8A | Annual Statement of Remuneration furnished to each employee (due end of February). |
Borang E / CP8D | Employer's annual return to LHDN with the per-employee remuneration listing (due 31 March). |
CP38 | LHDN instruction to deduct additional tax instalments from an employee's salary. |
CP39 | Monthly PCB remittance statement to LHDN (not generated by the system — see gaps). |
Additional remuneration | Bonus / commission / arrears taxed by the LHDN differential method, never smoothed or prorated. |
Zakat | Islamic alms paid via salary deduction — offsets PCB ringgit-for-ringgit. |
s.6A rebate | RM400 tax rebate for residents with annual chargeable income ≤ RM35,000. |
Contribution group | Reusable policy mapping statutory schemes (who pays, GL account) to employees. |
True-up | The MTD term subtracting tax already withheld this year so withholding converges on the annual liability. |
Reference
Known gaps — roll-up
The significant gaps found in the implementation, consolidated from the detailed pages. Each links to its module for context.