ngtaxkit

Nigerian tax compliance SDK for Python. Implements the Nigeria Tax Act (NTA) 2025 — VAT, PAYE, WHT, Pension, Statutory deductions, Marketplace transactions, and Payroll batch processing.

Zero dependencies. Pure functions. Deterministic output. Python 3.10+.

Install

pip install ngtaxkit

Optional extras:

pip install ngtaxkit[pdf]    # PDF generation (fpdf2)
pip install ngtaxkit[django] # Django fields + template tags
pip install ngtaxkit[flask]  # Flask blueprint + Jinja filters
pip install ngtaxkit[fastapi]  # FastAPI router + Pydantic models

Quick Start

from ngtaxkit import vat, paye, wht, pension, payroll

# ─── VAT ────────────────────────────────────────────────────────────────────

# Calculate VAT on an amount
result = vat.calculate(amount=100_000)
# → {'net': 100000, 'vat': 7500, 'gross': 107500, 'rate': 0.075, 'rate_type': 'standard', ...}

# Extract VAT from an inclusive amount
result = vat.extract(amount=107_500)
# → {'net': 100000, 'vat': 7500, 'gross': 107500, ...}

# Zero-rated categories
result = vat.calculate(amount=50_000, category='basic-food')
# → {'vat': 0, 'rate': 0, 'rate_type': 'zero-rated', 'input_vat_recoverable': True, ...}

# Exempt categories
result = vat.calculate(amount=200_000, category='residential-rent')
# → {'vat': 0, 'rate_type': 'exempt', 'input_vat_recoverable': False, ...}

# ─── PAYE ───────────────────────────────────────────────────────────────────

result = paye.calculate(
    gross_annual=5_000_000,
    pension_contributing=True,
    nhf_contributing=True,
    rent_paid_annual=600_000,
)
# → {
#     'annual_paye': ...,
#     'monthly_paye': ...,
#     'effective_rate': ...,
#     'tax_bands': [...],
#     'reliefs': {'consolidated_relief', 'pension_relief', 'nhf_relief', 'rent_relief', 'total'},
#     'net_monthly': ...,
#     'monthly_deductions': {'paye', 'pension', 'nhf', 'total'},
#     'employer_costs': {'pension', 'nsitf', 'itf', 'total'},
#     'legal_basis': '...',
#   }

# ─── WHT ────────────────────────────────────────────────────────────────────

result = wht.calculate(
    amount=500_000,
    payee_type='company',
    service_type='professional',
)
# → {
#     'wht_amount': 50000,
#     'rate': 0.1,
#     'net_payment': 450000,
#     'credit_note_required': True,
#     'remittance_deadline': '2026-05-21',
#   }

# ─── Pension ────────────────────────────────────────────────────────────────

result = pension.calculate(
    basic_salary=300_000,
    housing_allowance=100_000,
    transport_allowance=50_000,
)
# → {
#     'pensionable_earnings': 450000,
#     'employee_contribution': 36000,
#     'employer_contribution': 45000,
#     'total_contribution': 81000,
#   }

# ─── Payroll (batch) ────────────────────────────────────────────────────────

result = payroll.calculate_batch([
    {'name': 'Amina', 'gross_annual': 4_000_000, 'state_of_residence': 'LA', 'pension_contributing': True},
    {'name': 'Chidi', 'gross_annual': 8_000_000, 'state_of_residence': 'FC', 'pension_contributing': True},
    {'name': 'Bola',  'gross_annual': 2_400_000, 'state_of_residence': 'LA', 'nhf_contributing': True},
])
# → {
#     'employees': [...],
#     'by_state': {
#       'LA': {'state_name': 'Lagos', 'irs_name': 'LIRS', 'employee_count': 2, ...},
#       'FC': {'state_name': 'FCT', 'irs_name': 'FCT-IRS', 'employee_count': 1, ...},
#     },
#     'totals': {'total_gross', 'total_paye', 'total_pension', 'total_nhf', 'employee_count'},
#   }

Trust & Explainability

Every bundled rate can be explained with source metadata, and VAT/PAYE/WHT can return a calculation trace for audit logs, user-facing receipts, and integrations.

from ngtaxkit import rates, vat, paye, wht

trace = vat.explain_calculate(amount=100_000, category="standard")
trace["result"]["vat"]       # 7500
trace["formula"]             # reproducible calculation steps
trace["rate_keys"]           # ["vat.standard.rate"]
trace["sources"][0]          # source URL, legal basis, review date, confidence
trace["warnings"]            # non-empty if a source is needs_review/disputed

rates.explain("paye.exemptionThreshold")
rates.audit()

paye.explain_calculate(gross_annual=5_000_000, pension_contributing=True)
wht.explain_calculate(amount=500_000, payee_type="company", service_type="professional")

Source metadata is bundled offline. Treat it as developer evidence, not legal advice; re-check high-impact filings against official notices and professional advice.

For deterministic tool integrations, use the tools namespace:

from ngtaxkit import tools

tools.get_tool_schemas()     # JSON Schema-compatible tool definitions
tools.get_openapi_spec()     # OpenAPI 3.1 wrapper shape
tools.call_tool(
    "ngtaxkit.vat.explain_calculate",
    {"amount": 100_000, "category": "standard"},
)

Modules

Statutory Deductions

from ngtaxkit import statutory

# Individual deductions
nhf = statutory.nhf(basic_salary=300_000)
nsitf = statutory.nsitf(monthly_payroll=5_000_000)
itf = statutory.itf(annual_payroll=60_000_000, employee_count=25)

# All at once
all_deductions = statutory.calculate_all(
    basic_salary=300_000,
    monthly_payroll=5_000_000,
    annual_payroll=60_000_000,
    employee_count=25,
)

Marketplace Transactions

from ngtaxkit import marketplace

result = marketplace.calculate_transaction(
    sale_amount=100_000,
    platform_commission=0.10,       # 10% commission
    seller_vat_registered=True,
    buyer_type='individual',
    service_category='standard',
)
# → {
#     'sale_amount': 100000,
#     'vat': {'net': 100000, 'vat': 7500, ...},
#     'total_from_buyer': 107500,
#     'platform_commission': {'rate': 0.1, 'amount': 10000, ...},
#     'seller_payout': ...,
#     'wht': {...} or None,
#     'vat_liability': {'collected_by': 'seller', 'amount': 7500, ...},
#   }

VAT Categories

Key Design Decisions

• Banker's rounding — all monetary values use round-half-even to 2 decimal places (Python's ROUND_HALF_EVEN)
• Legal citations — every result includes a legal_basis string citing the NTA 2025 section
• Source-backed explanations — VAT, PAYE, and WHT expose formula steps, source metadata, and warnings for values that need review
• Versioned rates — bundled as JSON; override at runtime via rates.set_custom()
• Cross-language parity — produces identical results to the TypeScript version, enforced by shared test fixtures
• Type hints — full py.typed support with strict mypy compliance

Framework Integrations

Django

# settings.py
INSTALLED_APPS = [..., 'ngtaxkit.contrib.django']

# models.py
from ngtaxkit.contrib.django import TINField, NairaField, VATCategoryField

class Invoice(models.Model):
    seller_tin = TINField()
    amount = NairaField()
    category = VATCategoryField()

# templates
{% load ngtaxkit_tags %}
{{ amount|naira }}        {# NGN 1,234,567.89 #}
{{ amount|vat_amount }}   {# NGN 92,592.59 #}
{% vat_rate "standard" %} {# 7.5% #}

Flask

from ngtaxkit.contrib.flask import init_app

app = Flask(__name__)
init_app(app)  # Registers /tax/vat/calculate, /tax/paye/calculate, /tax/wht/calculate + Jinja filters

# In templates
{{ amount|naira }}
{{ amount|vat }}

FastAPI

from ngtaxkit.contrib.fastapi import create_router

app = FastAPI()
app.include_router(create_router(), prefix="/api")
# Adds /api/tax/vat/calculate, /api/tax/paye/calculate, etc. with Pydantic validation

Install extras:

pip install ngtaxkit[django]   # Django fields + template tags
pip install ngtaxkit[flask]    # Flask blueprint + Jinja filters
pip install ngtaxkit[fastapi]  # FastAPI router + Pydantic models

License

MIT — see LICENSE

Author

Abraham Tanta

• GitHub
• LinkedIn
• X

Links

• GitHub Repository
• Changelog
• TypeScript version