DEV Community

Cover image for We open-sourced a Nigeria Tax Act 2025 PAYE calculator (npm package + free API)
Orion Soft Limited
Orion Soft Limited

Posted on

We open-sourced a Nigeria Tax Act 2025 PAYE calculator (npm package + free API)

#javascript #opensource #api #nigeria

On 1 January 2026, the Nigeria Tax Act 2025 replaced the old Personal Income Tax Act rules for salaries. Every payroll system in Nigeria had to change: the Consolidated Relief Allowance is gone, the first ₦800,000 of chargeable income a year is now tax-free, there's a new rent relief, and the bands are new.

We build HR and payroll software at Orion Soft in Lagos, so we had to get this right anyway. We've now released the tax engine as open source, so nobody else has to rebuild it from the gazette.

Install 

npm install nigeria-paye
Enter fullscreen mode Exit fullscreen mode

Zero dependencies, TypeScript types included, works in Node.js and the browser.

Use 

import { payeSummary } from "nigeria-paye";

// ₦1,000,000 a month, paying ₦2.4m rent a year
const pay = payeSummary(1_000_000, { annualRent: 2_400_000 });

pay.paye.monthly;              // 140900   PAYE per month
pay.net;                       // 779100   take-home pay
pay.effectiveTaxRate;          // 14.09    % of gross
pay.comparison.monthlySaving;  // 10566.67 kept vs the old law
pay.employerTotalCost;         // 1120000  incl. employer pension, NSITF, ITF
Enter fullscreen mode Exit fullscreen mode

What it handles

The new annual bands:

Chargeable income Rate
First ₦800,000 0%
Next ₦2,200,000 15%
Next ₦9,000,000 18%
Next ₦13,000,000 21%
Next ₦25,000,000 23%
Above ₦50,000,000 25%

Plus:

  • Reliefs before tax: employee pension (8%), National Housing Fund (2.5% of basic), health insurance (NHIS), and rent relief (20% of annual rent, capped at ₦500,000)
  • Employer costs: pension (10%), NSITF (1%), ITF (1%)
  • Old-law comparison: the previous PITA calculation (consolidated relief, 7–24% bands, minimum tax, minimum-wage exemption), so you can show users whether they keep more or pay more in 2026
  • A band-by-band breakdown for payslips and explanations

Not using JavaScript? There's a free API

No key, CORS enabled:

curl "https://www.orionsoftlimited.com/api/public/paye?salary=500000&rent=1200000"
Enter fullscreen mode Exit fullscreen mode

You get PAYE, every deduction, take-home pay, the bands, employer cost and the old-law comparison as JSON. There's an OpenAPI spec, a public Postman workspace, and docs at orionsoftlimited.com/developers.

And if you just want to check your own salary: the calculator.

Accuracy, and how you can help

The figures are estimates for salaried employees based on the published rates and reliefs; they're tested against hand-worked examples. If you find a case where your state IRS computes something different, please open an issue. Pull requests welcome.

⭐ GitHub: orionsoftlimited/nigeria-paye

Orion Soft builds hospital, school, HR and payroll software for organisations across Africa, and custom software for clients worldwide. If you're building something in or for Africa, say hello.

Top comments (0)