Build tax into your product. Stay connected.
Connect calculation, verification, filing, payment handoff and proof to your product through one versioned API surface at api.mitax.io/v1. Every decision comes from the same governed MiTax Core that powers our applications and workspaces.
Access is self-service. Create a workspace at api.mitax.io, create a Test key with one click, and request Live access from the same workspace. Test is free up to 2,000 calls a month.
One versioned API surface for the full tax lifecycle.
Calculate & identify
scope: tax:calcCompute PIT, VAT, CIT, PAYE, WHT or CGT for a customer. Every figure comes straight from the MiTax tax engine, and nothing is recomputed on the edge.
File & verify
scope: filing:initiateTurn a calculation into a real filing with a computed deadline, under the server-authoritative calculation-id contract.
Pay & retrieve proof
scope: payment:initiateRaise a pending payment intent for the amount due and itemised service charges. Payment is initiated through Paystack, MiTax never holds funds, and provider and authority outcomes are tracked separately.
Authentication matched to your integration.
Every request to https://api.mitax.io/v1 carries an API key in the X-API-Key header. Test keys start with mtk_test_ and Live keys start with mtk_live_; each belongs to one application, one environment and one organisation. Tokens in the Authorization header are not accepted by these operations. Every filing and payment request requires an idempotency key. Event delivery uses signed, replay-protected webhooks. MiTax stores only a SHA-256 hash of each key, so a key is shown exactly once, when it is created.
Send your trace value in X-Correlation-Id. MiTax returns it in the response headers and response metadata so your team can follow one customer action across both systems.
Base URL
https://api.mitax.io/v1/<resource>
The machine-readable contract is published at api.mitax.io/v1/openapi.json and the developer documentation at api.mitax.io/docs. Where the two differ from this page, the live contract applies.
| Endpoint | Required scope | Purpose |
|---|---|---|
POST /v1/subjects | identity:resolve | Resolve a consented customer to its MiTax Core identity |
POST /v1/calculations | tax:calc | Calculate PIT, CIT, VAT, PAYE, WHT and CGT for a consented subject |
POST /v1/obligations | obligation:read | List a subject’s tax obligations |
POST /v1/filings | filing:initiate | Initiate a filing on a consented subject’s behalf |
POST /v1/payments | payment:initiate | Raise a pending, non-custodial government-payment intent |
POST /v1/records | record:read | List a subject’s financial and tax records |
POST /v1/subscriptions | subscription:read | Read a subject’s subscription and metered usage |
POST /v1/einvoices | einvoice:transmit | Submit an e-invoice to the MiTax e-invoicing queue |
GET /v1/webhooks, POST /v1/webhooks | webhook:manage | List and manage signed webhook endpoints |
Request & response.
Each call names a customer_ref, your identifier for a customer linked to a consented MiTax tax subject. The resource path is the contract; legacy action names remain temporary compatibility aliases.
Request
{
"customer_ref": "acme-cust-42",
"tax_type": "vat", // pit | vat | cit | paye | wht | cgt
"inputs": {
"output_vat": 750000,
"input_vat": 120000,
"period": "2025-08"
}
}
Response
{
"ok": true,
"data": {
"total_kobo": 63000000,
"breakdown": [ /* server-authoritative lines */ ],
"calculation_id": "6f1c…",
"tax_type": "vat"
},
"meta": { "correlation_id": "acme-req-42", "api_version": "v1" }
}
PIT uses inputs.gross, inputs.annual_rent, inputs.pension, inputs.nhis, and other relief fields. The vat/cit/paye/wht/cgt family returns a calculation_id, the token /v1/filings requires.
Request
{
"customer_ref": "acme-cust-42",
"tax_type": "vat",
"period_type": "monthly", // monthly | annual
"year": 2025,
"month": 8,
"calculation_id": "6f1c…" // from /v1/calculations, same customer + period
}
Response
{
"ok": true,
"filing_id": "b73a…",
"amount_due": 630000,
"deadline": "2025-09-21",
"amount_source": "server_verified",
"request_id": "c41d…"
}
For vat/cit/paye/wht/cgt, calculation_id is mandatory and must match the same customer, tax type and period. MiTax will not file a self-declared amount. pit is recomputed from the linked profile’s stored income.
Request
{
"customer_ref": "acme-cust-42",
"filing_id": "b73a…" // from /v1/filings
}
Response
{
"ok": true,
"intent": {
"id": "9d20…",
"amount": 630000, // outstanding tax, untouched
"orchestration_fee": 300, // fixed MiTax action fee (incl. VAT)
"provider_pass_through": 0, // provider charge, itemised separately
"fee": 300, // orchestration_fee + provider_pass_through
"total": 630300, // what the taxpayer transfers
"status": "pending"
},
"never_holds_funds": true,
"settlement": "customer_to_psp_to_government",
"request_id": "e88f…"
}
How payments settle.
/payments does not move money. It returns a server-authoritative payment intent: the outstanding tax recomputed from the filing, plus the charges on top of it. That intent is the checkout handoff.
The charges are never a percentage of the tax. MiTax quotes a fixed orchestration fee from the published commercial catalogue, and any payment-provider charge is itemised as its own line. Both are returned by the API and frozen on the quote before the taxpayer approves anything, so read the amounts from the response rather than deriving them from the principal. The example figures above are illustrative.
The taxpayer continues by bank transfer or card through Paystack. MiTax never holds funds; it records the handoff, the itemised charges and the outcomes the provider and the authority report independently.
- Calculations returns the tax the customer owes.
- Filings creates the obligation and a deadline.
- Payments returns the amount and fee as a PSP handoff.
- The taxpayer pays through Paystack; the provider webhook updates the intent status.
Predictable, per-key limits.
Each key has its own rolling-minute cap. Exceed it and the API returns 429 rate_limited; back off and retry. Every response carries a correlation ID for support and reconciliation.
| HTTP | error | Meaning |
|---|---|---|
| 401 | missing_api_key | No X-API-Key header. |
| 403 | forbidden | Unknown, revoked, or suspended key. |
| 403 | insufficient_scope | Key lacks the scope for this verb. |
| 428 | idempotency_key_required | A filing or payment mutation omitted Idempotency-Key. |
| 429 | rate_limited | Over the key’s per-minute cap. |
| 404 | customer_not_found | No customer for that customer_ref. |
| 404 | customer_not_linked | Customer not yet linked to a MiTax profile. |
| 400 | calculation_id_required | File a VAT/CIT/PAYE/WHT/CGT return with a calc id. |
| 400 | plan_required | The linked customer’s plan does not cover this tax. |
Build on MiTax® Core.
Explore the documentation without an account. When you are ready to integrate, create an API Rail workspace: Test keys are free up to 2,000 calls a month, and Live access is requested from the same workspace.
- Test first, free
- Scoped, hashed API keys
- Server-authoritative amounts