Payroll Africa: Automating Statutory Deductions Across 11 African Countries

Cloud payroll platforms like Workpay have made it easier for African businesses to process statutory deductions. But they come with a trade-off: your employee data, salary records, and compliance history live on someone else's servers. You pay per employee, per month, and if you outgrow the platform or want to switch, extracting your data is rarely straightforward.

Payroll Africa is our open-source alternative. It runs on your own ERPNext instance, which means you fully own your data -- every salary slip, every statutory calculation, every compliance report. No per-employee fees. No vendor lock-in. It hooks directly into ERPNext HRMS Salary Slip validation, calculates every deduction according to current rates and tax bands across 11 African countries, and generates 33 country-specific compliance reports ready for filing with tax authorities.

This article explains what the app does, how it works under the hood, and which countries and deductions it covers. Whether you are an HR manager processing payroll for a single Kenyan office or a CFO overseeing operations across five African subsidiaries, this is the deep-dive you need to evaluate whether self-hosted payroll is right for your business.

Built on ERPNext HRMS: The Full HR Platform

Payroll Africa does not replace your HR system -- it extends it. It sits on top of Frappe HRMS, the open-source HR and payroll module for ERPNext. HRMS handles the full employee lifecycle, and Payroll Africa adds the Africa-specific statutory layer that HRMS lacks out of the box.

What you get with HRMS as the foundation:

With Payroll Africa plugged in, the salary slip validation hook intercepts every payroll run and applies the correct statutory deductions for each employee's country. The HR team processes payroll exactly as they normally would -- Payroll Africa works silently in the background.

How It Works: The Calculator Architecture

Payroll Africa uses a clean calculator-based architecture. When a Salary Slip is validated in ERPNext HRMS, the app intercepts the event via a doc_events hook. It looks up the employee's country (from a custom payroll_country field on the Employee DocType, falling back to the Company's country), then dispatches to the correct country calculator.

Each calculator computes every statutory deduction for that country and returns a dictionary of component names with amounts. The hook then either updates existing deduction rows on the Salary Slip or appends new ones. Employer-only contributions (like employer NSSF or employer pension) are marked as statistical so they appear on reports but do not reduce the employee's net pay.

This design means adding a new country requires only a new calculator class and a settings DocType -- no changes to core ERPNext or HRMS code. The app ships with 26 DocTypes, 11 calculator classes, and a registry that maps countries to calculators with caching for performance.

East Africa: Kenya, Uganda, Tanzania, Rwanda, Burundi

Kenya

The most comprehensive calculator. It computes five components: NSSF (Tier I at 6% up to KES 18,000 and Tier II at 6% on the next KES 54,000, with employer matching), SHIF (2.75% of gross, minimum KES 300), Housing Levy (1.5% employee plus 1.5% employer), NITA (fixed KES 50), and PAYE using five progressive bands from 10% to 35% with KES 2,400 personal relief as a tax credit. Insurance relief of up to KES 5,000 at 15% is also supported.

Kenya has the most reports: P9A Tax Deduction Card, P10 Monthly Return, NSSF Remittance, SHIF Remittance, and Housing Levy Return -- all formatted for KRA filing.

Uganda

Three components: NSSF (5% employee, 10% employer), Local Service Tax (graduated bands where the highest bracket wins, converted from annual to monthly), and PAYE with a 0% first band of UGX 235,000 that effectively acts as personal relief. Reports include URA PAYE Return, NSSF Uganda Remittance, and LST Return.

Tanzania

Four components: NSSF (10% each for employee and employer), SDL (Skills Development Levy at 3.5%, employer-only), and WCF (Workers Compensation at 0.5%, employer-only). PAYE is handled via ERPNext HRMS Income Tax Slabs. Reports: TRA Employment Taxes and NSSF Tanzania Remittance.

Rwanda

Five components: Pension (6% each for employee and employer), Maternity (0.3% each), CBHI (Community-Based Health Insurance at 0.5%), and Occupational Hazards (variable, employer-only). Report: RRA Unified Declaration.

Burundi

Seven components including INSS (3.625% each), Work Injury, Health Insurance, and Training Fund -- each split between employee and employer. Reports: OBR PAYE Return and INSS Burundi Remittance.

Southern & West Africa: Zambia, Malawi, DRC, Nigeria, Mozambique, Angola

Zambia

NAPSA (5% each, capped at a configurable monthly gross) and NHIMA (1% each, no cap). Reports: ZRA P11 PAYE Return, NAPSA Remittance, NHIMA Remittance.

Nigeria

The most components at seven: Pension (8% employee, 10% employer), NHF (National Housing Fund at 2.5%), NHIS (5% employee, 10% employer), NSITF (1% employer), and ITF (Industrial Training Fund at 1% employer). Reports: Nigeria PAYE Schedule, PenCom Remittance, NHIS Schedule, NHF Remittance.

DRC

Six components including INSS Pension (5% each), INSS Occupational Risks (1.5% employer), INSS Family Benefits (6.5% employer), INPP (3% employer), and ONEM (variable employer). Reports: DRC Unified Declaration and INSS DRC Remittance.

Mozambique & Angola

Mozambique: INSS at 3% employee, 4% employer. Reports: AT IRPS Return, INSS Mozambique Remittance. Angola: INSS at 3% employee, 8% employer. Reports: AGT IRT Return, INSS Angola Remittance.

33 Compliance Reports Ready for Filing

Every report is designed to match the format expected by the relevant tax authority. Five cross-country reports give you a consolidated view: Statutory Deductions Summary, Employer Contributions, Cost to Company, Multi-Country Payroll Summary, and Rate Change Audit Trail.

Country-specific reports are organised by region in the Payroll Africa workspace. Kenya alone has five filing reports (P9A, P10, NSSF, SHIF, Housing Levy). Each report filters by date range, company, and employee -- so you can generate returns for a single subsidiary or a consolidated view across all your African operations.

Installation and Setup

Payroll Africa requires ERPNext and HRMS. Install it with bench get-app https://github.com/CoaleTech/payroll_africa followed by bench --site your-site install-app payroll_africa. The setup wizard runs automatically and creates all required currencies, salary components, income tax slabs, salary structure templates, and the Payroll Africa workspace.

Enable the countries you need in Payroll Africa Settings. Each country has its own settings DocType where you can adjust rates when statutory changes occur. When you update rates, the app clears its calculator cache so the next Salary Slip uses the new values. You can also use the recalculate_salary_slips API to recompute all draft slips for a given period after a rate change.

For multi-country deployments, set the payroll_country custom field on each Employee record. This overrides the Company's country, allowing you to process Kenyan and Ugandan employees from the same ERPNext instance with the correct statutory deductions applied automatically.

Country Coverage at a Glance

Get Started

Payroll Africa is open source and available on GitHub. Install it on your ERPNext instance, enable the countries you operate in, and your next payroll run will have statutory deductions calculated automatically. No more spreadsheets, no more manual tax band lookups, no more compliance anxiety.

If you need help with installation, configuration, or extending the app for additional countries, CoaleTech offers implementation support. We built this app because we saw the same payroll compliance pain across every African ERPNext deployment we worked on -- and we wanted to solve it once, properly, for everyone.