bench get-app https://github.com/CoaleTech/payroll_africa

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=CoaleTech%2Fpayroll_africa)](https://frappegems.com/gems/apps/CoaleTech/payroll_africa)

Payroll Africa

Statutory payroll deduction automation for 20 African countries.
Built on Frappe + HRMS.

Countries · How It Works · Installation · Configuration · Reports · API

--- ## Overview Payroll Africa hooks into HRMS Salary Slip validation to automatically compute employee and employer statutory deductions — PAYE, social security, health insurance, housing levies, training funds — using each country's current tax bands and rates. No manual calculation. No spreadsheets. Change a rate in settings, and the next payroll run picks it up. ### Key Features - **Automatic deduction computation** on Salary Slip save/submit - **20 countries** with country-specific calculators, tax bands, and statutory rates - **51 reports** covering PAYE returns, social security remittances, and compliance filings - **Country enable/disable** — toggle which countries are active in your deployment - **Dynamic workspace** — sidebar and salary component dropdowns filter to show only enabled countries - **Rate change tracking** — update statutory rates with effective dates; audit trail included - **Template salary structures** — pre-built per country with all statutory components wired up - **API for standalone calculations** — compute deductions without creating a Salary Slip - **Bulk recalculation** — recalculate all enabled countries' draft slips in one API call - **Yearly rate-review reminder** — automated email to Payroll Managers at year-start - **Print format** — "Salary Slip Africa Standard" with country-aware layout - **What's New dialog** — styled release notes shown after app updates --- ## Supported Countries **East Africa** | Country | Currency | Statutory Deductions | Reports | |---------|----------|---------------------|---------| | Kenya | KES | PAYE, NSSF (Tier I & II), SHIF, Housing Levy, NITA | P9A, P10, NSSF, SHIF, Housing Levy | | Uganda | UGX | PAYE, NSSF (5%/10%/15% tiers), LST | URA PAYE Return, NSSF, LST | | Tanzania | TZS | PAYE, NSSF, SDL, WCF | TRA Employment Taxes, NSSF | | Rwanda | RWF | PAYE, Pension, Maternity, CBHI, Occupational Hazards | RRA Unified Declaration | | Burundi | BIF | PAYE, INSS, Work Injury, Health Insurance, Training Fund | OBR PAYE Return, INSS | | Ethiopia | ETB | PIT (5–35%), Pension (Employee + Employer) | Ethiopia PIT Return, Pension Remittance | **Southern Africa** | Country | Currency | Statutory Deductions | Reports | |---------|----------|---------------------|---------| | Malawi | MWK | PAYE, Pension | MRA P12, MRA P9 | | Zambia | ZMW | PAYE, NAPSA (capped), NHIMA | ZRA P11, NAPSA, NHIMA | | Mozambique | MZN | PAYE/IRPS, INSS | AT IRPS Return, INSS | | Angola | AOA | PAYE/IRT, INSS | AGT IRT Return, INSS | | Botswana | BWP | PAYE (0–26.5%) | Botswana PAYE Return | | South Africa | ZAR | PAYE (18–45%), UIF | PAYE Remittance, UIF Remittance | | Namibia | NAD | PAYE (0–37%), SSC | Namibia PAYE Return, SSC Remittance | | Madagascar | MGA | IRSA (0–30%), CNAPPS | IRSA Remittance, CNAPPS Remittance | **West & Central Africa** | Country | Currency | Statutory Deductions | Reports | |---------|----------|---------------------|---------| | Nigeria | NGN | PAYE, Pension (PenCom), NHF, NHIS, NSITF, ITF | PAYE Schedule, PenCom, NHF, NHIS | | Ghana | GHS | PAYE (0–35%), SSNIT | Ghana PAYE Schedule, SSNIT Remittance | | Ivory Coast | XOF | ITS (0–32%), CNPS | ITS Remittance, CNPS Remittance | | DRC | CDF | PAYE/IPR, INSS Pension, Occupational Risks, Family Benefits, INPP, ONEM | DRC Unified Declaration | **North Africa** | Country | Currency | Statutory Deductions | Reports | |---------|----------|---------------------|---------| | Egypt | EGP | Income Tax (0–27.5%), Social Insurance | Income Tax Return, Social Insurance Remittance | | Morocco | MAD | IR (0–37%), CNSS | IR Remittance, CNSS Remittance | | Tunisia | TND | IRPP (0–40%), CNSS | IRPP Remittance, CNSS Remittance | **Cross-country reports** (work across all enabled countries): | Report | Description | |--------|-------------| | Statutory Deductions Summary | All deductions by employee and period | | Employer Contributions | Employer-only statutory costs | | Cost to Company | Total compensation including employer contributions | | Multi-Country Payroll Summary | Consolidated view across countries | | Rate Change Audit Trail | History of statutory rate changes | --- ## How It Works ``` Employee + Salary Structure | v Salary Slip (save/submit) | v engine/hooks.py → on_salary_slip_validate() | v registry.py → get_calculator(country) | v calculators/{country}.py → compute(doc) | v Deduction rows auto-populated with correct amounts ``` 1. **Employee's country is resolved** from `Employee.payroll_country` (custom field), falling back to `Company.country` 2. **Country calculator is loaded** via the registry, which maps countries to their calculator classes 3. **Calculator reads current rates** from the country's Settings DocType (e.g., "Kenya Payroll Settings") 4. **Deductions are computed** using the country's tax bands, caps, and formulas 5. **Salary Slip rows are updated** — existing deduction rows get overwritten, missing components get appended --- ## Installation ### Prerequisites - Frappe v15 or v16 - ERPNext - HRMS ### Install ```bash cd /path/to/your/bench bench get-app --branch main bench install-app payroll_africa bench --site your-site migrate ``` The `after_install` hook automatically creates: - Currency records for all 20 countries (KES, UGX, TZS, RWF, BIF, ETB, ZMW, MWK, MZN, AOA, BWP, ZAR, NAD, MGA, NGN, GHS, XOF, CDF, EGP, MAD, TND) - Country-specific Payroll Settings with current statutory rates - Salary Components for each country's deductions - Income Tax Slabs with PAYE bands for all 20 countries - Template Salary Structures (e.g., "Kenya Payroll Template") - Workspace sidebar with country sections and reports - Desktop icon under Frappe HR ### Uninstall ```bash bench uninstall-app payroll_africa ``` The `before_uninstall` hook removes all salary structures, salary components, income tax slabs, custom fields, and desktop icons created by the app. --- ## Configuration ### Global Settings Navigate to **Payroll Africa Settings** from the workspace. | Setting | Description | |---------|-------------| | Enable Payroll Africa | Master toggle — disables all computation when off | | Country checkboxes | Enable/disable individual countries | When a country is disabled: - Its settings and report links are hidden from the workspace sidebar automatically (no restart required — driven by `payroll_africa_sidebar.js` on page load) - The payroll calculator silently skips employees in that country - Its salary components are hidden from Salary Structure dropdowns ### Country Settings Each country has its own Settings DocType accessible from the workspace sidebar: **East Africa** - **Kenya Payroll Settings** — PAYE relief, NSSF tiers, SHIF rate, Housing Levy rate, NITA rate - **Uganda Payroll Settings** — NSSF tier rates, LST bands - **Tanzania Payroll Settings** — NSSF rate, SDL rate, WCF rate - **Rwanda Payroll Settings** — Pension rates, Maternity rates, CBHI rate - **Burundi Payroll Settings** — INSS rates, Health Insurance rates, Training Fund rates - **Ethiopia Payroll Settings** — PIT bands, Pension rates (Employee + Employer) **Southern Africa** - **Malawi Payroll Settings** — Pension rate - **Zambia Payroll Settings** — NAPSA rate and cap, NHIMA rate - **Mozambique Payroll Settings** — INSS rates - **Angola Payroll Settings** — INSS rates - **Botswana Payroll Settings** — PAYE bands - **South Africa Payroll Settings** — PAYE rebates, UIF rate and annual cap - **Namibia Payroll Settings** — PAYE bands, SSC rates - **Madagascar Payroll Settings** — IRSA bands, CNAPPS rates **West & Central Africa** - **Nigeria Payroll Settings** — Pension rate (PenCom), NHF rate, NHIS rate, NSITF rate, ITF rate - **Ghana Payroll Settings** — PAYE bands, SSNIT rate - **Ivory Coast Payroll Settings** — ITS bands, CNPS rates - **DRC Payroll Settings** — INSS rates, INPP rate, ONEM rate **North Africa** - **Egypt Payroll Settings** — Income tax bands, Social Insurance rates - **Morocco Payroll Settings** — IR bands, CNSS rates - **Tunisia Payroll Settings** — IRPP bands, CNSS rates Each settings page includes a PAYE Bands table where you can update tax brackets when legislation changes. ### Employee Setup Set the **Payroll Country** field on each Employee record. If not set, the system falls back to the Employee's Company country. ### Salary Structure Use the pre-built template (e.g., "Kenya Payroll Template") or create your own. The calculator will append missing statutory components automatically during Salary Slip validation. --- ## Reports ### Kenya (5 reports) | Report | Purpose | |--------|---------| | P9A Tax Deduction Card | Annual employee tax certificate | | P10 Monthly Tax Return | Monthly PAYE filing to KRA | | NSSF Remittance | NSSF contribution schedule | | SHIF Remittance | Social Health Insurance Fund report | | Housing Levy Return | Affordable Housing Levy report | ### Uganda (3 reports) | Report | Purpose | |--------|---------| | URA PAYE Return | Monthly PAYE return for URA | | NSSF Uganda Remittance | NSSF contribution schedule | | LST Return | Local Service Tax report | ### Tanzania (2 reports) | Report | Purpose | |--------|---------| | TRA Employment Taxes | PAYE + SDL + WCF report for TRA | | NSSF Tanzania Remittance | NSSF contribution schedule | ### Rwanda (1 report) | Report | Purpose | |--------|---------| | RRA Unified Declaration | Combined PAYE + social security filing | ### Burundi (2 reports) | Report | Purpose | |--------|---------| | OBR PAYE Return | Monthly PAYE return for OBR | | INSS Burundi Remittance | INSS contribution schedule | ### Zambia (3 reports) | Report | Purpose | |--------|---------| | ZRA P11 PAYE Return | Monthly PAYE return for ZRA | | NAPSA Remittance | Pension contribution schedule | | NHIMA Remittance | Health insurance contribution schedule | ### Malawi (2 reports) | Report | Purpose | |--------|---------| | MRA P12 PAYE Return | Monthly PAYE return for MRA | | MRA P9 Deduction Certificate | Annual employee tax certificate | ### DRC (1 report) | Report | Purpose | |--------|---------| | DRC Unified Declaration | Combined IPR + INSS + INPP + ONEM filing | ### Nigeria (4 reports) | Report | Purpose | |--------|---------| | Nigeria PAYE Schedule | Monthly PAYE computation schedule | | PenCom Remittance | Pension contribution schedule | | NHF Remittance | National Housing Fund report | | NHIS Schedule | Health insurance contribution schedule | ### Mozambique (2 reports) | Report | Purpose | |--------|---------| | AT IRPS Return | Monthly PAYE/IRPS return | | INSS Mozambique Remittance | INSS contribution schedule | ### Angola (2 reports) | Report | Purpose | |--------|---------| | AGT IRT Return | Monthly PAYE/IRT return | | INSS Angola Remittance | INSS contribution schedule | ### Botswana (1 report) | Report | Purpose | |--------|---------| | Botswana PAYE Return | Monthly PAYE return for BURS | ### South Africa (2 reports) | Report | Purpose | |--------|---------| | South Africa PAYE Remittance | Monthly PAYE remittance to SARS | | South Africa UIF Re