API Reference
PAYE Calculator
Calculate Personal Income Tax (PAYE), statutory reliefs (CRA, Pension, NHF, NHIS), and reform comparisons.
PAYE Calculator
POST /api/v1/tax/paye
Computes Personal Income Tax (PAYE) under the Nigerian Personal Income Tax Act (PITA) and 2026 Reforms. It automatically calculates Consolidated Relief Allowance (CRA), statutory employee deductions, graduated brackets, and produces both an old-law vs new-law comparison and an audio-ready spoken summary.
Required scope: tax:calculate.
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
gross_income | number | Yes | — | Total gross salary/income. Aliases: salary, income. |
period | string | No | "annual" | Frequency of input salary: "annual" or "monthly". |
pension | number | No | 0 | Employee pension contribution (Statutory 8% PRA 2014). |
nhf | number | No | 0 | National Housing Fund contribution (2.5% of basic). |
nhis | number | No | 0 | National Health Insurance Scheme deduction. |
life_insurance | number | No | 0 | Qualified life assurance premiums paid during the year. |
mortgage_interest | number | No | 0 | Interest on owner-occupier residential mortgage. |
rent_relief | number | No | 0 | Verified statutory rent allowance/relief claim. |
Code Examples
curl -X POST "https://taxnigeria.ng/api/v1/tax/paye" \
-H "Authorization: Bearer txn_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"gross_income": 8500000,
"period": "annual",
"pension": 680000,
"nhf": 212500,
"nhis": 425000,
"life_insurance": 0
}'Response Example (200 OK)
{
"ok": true,
"data": {
"tax_type": "paye",
"input_period": "annual",
"gross_income": 8500000,
"taxable_income": 5282500,
"tax_payable": 1056500,
"monthly_tax": 88042,
"annual_takehome": 6126000,
"monthly_takehome": 510500,
"effective_rate": "12.43%",
"total_reliefs": 3217500,
"law_version": "Nigeria Tax Act 2025",
"spoken_summary": "For an annual gross salary of ₦8,500,000, the calculated annual PAYE liability is ₦1,056,500, resulting in a monthly tax deduction of ₦88,042. Effective tax rate is 12.43%.",
"breakdown": [
{ "band": "First ₦300,000", "rate": "7%", "taxable": 300000, "tax": 21000 },
{ "band": "Next ₦300,000", "rate": "11%", "taxable": 300000, "tax": 33000 },
{ "band": "Next ₦500,000", "rate": "15%", "taxable": 500000, "tax": 75000 },
{ "band": "Next ₦500,000", "rate": "19%", "taxable": 500000, "tax": 95000 },
{ "band": "Next ₦1,600,000", "rate": "21%", "taxable": 1600000, "tax": 336000 },
{ "band": "Above ₦3,200,000", "rate": "24%", "taxable": 2082500, "tax": 499800 }
],
"comparison": {
"old_law": { "tax_payable": 1120000, "effective_rate": "13.18%" },
"new_law": { "tax_payable": 1056500, "effective_rate": "12.43%" },
"savings": 63500,
"percent_change": "-5.67%",
"is_better": true
}
},
"meta": {
"calculation_id": "calc_paye_819c4d2e",
"timestamp": "2026-10-28T13:31:00.000Z",
"latency_ms": 11
}
}