API Reference
Withholding Tax (WHT)
Compute statutory Withholding Tax deductions across professional fees, contracts, rent, and dividends.
Withholding Tax (WHT)
POST /api/v1/tax/wht
Calculates statutory Withholding Tax deductions for vendor payments, supplier contracts, consultancy fees, dividends, and rent. Enforces TIN compliance (automatically doubling the rate when the vendor lacks a valid Tax ID) and applies treaty rates for Double Taxation Agreement (DTA) jurisdictions.
Required scope: tax:calculate.
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
amount | number | Yes | — | Gross transaction amount in Naira. Alias: gross_amount. |
transaction_type | string | Yes | — | Category: "contracts_supply", "professional_consulting", "technical_services", "rent", "dividends", "interest", "royalties". |
beneficiary_type | string | No | "company" | "company" (corporate entity) or "individual". |
has_tax_id | boolean | No | true | Whether beneficiary has a valid Tax Identification Number (TIN). If false, statutory rate is doubled. |
is_non_resident | boolean | No | false | Whether beneficiary is an offshore non-resident entity. |
is_dta_country | boolean | No | false | Whether recipient resides in a country with a Double Taxation Agreement with Nigeria. |
Code Examples
curl -X POST "https://taxnigeria.ng/api/v1/tax/wht" \
-H "Authorization: Bearer txn_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000000,
"transaction_type": "professional_consulting",
"beneficiary_type": "company",
"has_tax_id": true
}'Response Example (200 OK)
{
"ok": true,
"data": {
"tax_type": "wht",
"gross_amount": 5000000,
"wht_rate": "10%",
"wht_amount": 500000,
"net_payable": 4500000,
"transaction_type": "Professional / Consultancy Services",
"beneficiary_type": "Corporate Entity",
"is_exempt": false,
"spoken_summary": "On a gross consultancy invoice of ₦5,000,000 to a corporate vendor with a valid TIN, the statutory Withholding Tax deduction is 10% (₦500,000), leaving a net payable balance of ₦4,500,000."
},
"meta": {
"calculation_id": "calc_wht_6a12b98e",
"timestamp": "2026-10-28T13:33:00.000Z",
"latency_ms": 9
}
}