API Reference
Unified Tax Calculator
Single polymorphic endpoint to compute PAYE, CIT, WHT, VAT, or Late Filing Penalties.
Unified Tax Calculator
POST /api/v1/tax/calculate
Computes tax liabilities across multiple tax types (PAYE, CIT, WHT, Penalties, VAT) through a single polymorphic endpoint. Required scope: tax:calculate.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
tax_type | string | Yes | One of "paye", "cit", "wht", "penalties", "vat". |
gross_income | number | Conditional | Gross earnings (for PAYE). Alias: salary. |
period | string | No | "annual" (default) or "monthly". |
turnover | number | Conditional | Gross revenue/turnover (for CIT). |
profit_before_tax | number | Conditional | Profit before tax (for CIT). Alias: pbt. |
amount | number | Conditional | Gross transaction amount (for WHT). |
transaction_type | string | Conditional | WHT transaction category (e.g. "contracts_supply", "professional_consulting", "rent", "dividends"). |
principal_amount | number | Conditional | Unremitted tax amount (for Penalties). |
due_date | string | Conditional | Statutory due date in YYYY-MM-DD format (for Penalties). |
conversation_id | string | No | Optional Tax Nigeria conversation ID to sync calculation cards into your workspace session. |
Code Examples
curl -X POST "https://taxnigeria.ng/api/v1/tax/calculate" \
-H "Authorization: Bearer txn_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"tax_type": "paye",
"gross_income": 6000000,
"period": "annual",
"pension": 480000,
"nhf": 150000
}'Response Example (200 OK)
{
"ok": true,
"data": {
"tax_type": "paye",
"input_period": "annual",
"gross_income": 6000000,
"taxable_income": 3970000,
"tax_payable": 744800,
"monthly_tax": 62067,
"annual_takehome": 5255200,
"monthly_takehome": 437933,
"effective_rate": "12.41%",
"total_reliefs": 2030000,
"law_version": "Nigeria Tax Act 2025",
"spoken_summary": "For an annual gross salary of ₦6,000,000, the calculated annual PAYE liability is ₦744,800, resulting in a monthly tax deduction of ₦62,067. Effective tax rate is 12.41%.",
"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": 770000, "tax": 184800 }
]
},
"meta": {
"calculation_id": "calc_paye_9a7b1c3d",
"timestamp": "2026-10-28T13:30:00.000Z",
"latency_ms": 14
}
}