MiTax® API Rail

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.

Open API Rail Read the public docs

Production access is granted through partner onboarding. MiTax provisions your organisation, sandbox, credentials, usage controls, signed webhooks and customer-authorisation model.

How it works

One versioned API surface for the full tax lifecycle.

Calculate & identify

scope: tax:calc

Compute 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:initiate

Turn a calculation into a real filing with a computed deadline, under the server-authoritative calculation-id contract.

Pay & retrieve proof

scope: payment:initiate

Get a payment handoff for the amount due and itemised service charges. A licensed provider handles settlement through the relevant government channel while MiTax tracks provider and authority outcomes separately.

Authentication

Authentication matched to your integration.

Server integrations use tenant-scoped API keys or OAuth 2.0 credentials according to the approved partner flow. Every filing and payment request requires an idempotency key. Event delivery uses signed, replay-protected webhooks. API keys look like mtk_live_…; MiTax stores only their SHA-256 hash, so a key is shown exactly once at mint time.

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>

API endpoints, required scopes and purpose
Endpoint	Required scope	Purpose
`POST /calculations`	`tax:calc`	Calculate PIT, CIT, VAT, PAYE, WHT, CGT and levies
`POST /identities/verify`	`identity:verify`	Verify taxpayer and business identifiers
`POST /filings`	`filing:initiate`	Create and submit a filing workflow
`POST /payments`	`payment:initiate`	Initiate a licensed-provider payment handoff
`GET /receipts/{id}`	`records:read`	Retrieve verifiable payment proof
`GET /certificates/{id}`	`records:read`	Retrieve and verify certificate status

Credentials are scoped to exactly what your product needs. Use calculation alone, combine identity and verification, or connect the complete calculate-file-pay-proof lifecycle. Scopes and production limits are configured during onboarding.

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.

POST /tax-rails/v1/calculations requires tax:calc

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 /file requires.

POST /tax-rails/v1/filings requires filing:initiate

Request

{
  "customer_ref": "acme-cust-42",
  "tax_type": "vat",
  "period_type": "monthly",     // monthly | annual
  "year": 2025,
  "month": 8,
  "calculation_id": "6f1c…"    // from /calc, 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.

POST /tax-rails/v1/payments requires payment:initiate

Request

{
  "customer_ref": "acme-cust-42",
  "filing_id": "b73a…"       // from /file
}

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…"
}

Money, handled honestly

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 the payment service provider. The provider handles settlement through the relevant government channel; MiTax records the handoff, itemised charges and independently reported outcomes.

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 PSP collects and remits to Government; the webhook settles the intent.

Rate limits & errors

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 codes and their meaning
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.

Developer infrastructure

Build on MiTax® Core.

Explore the documentation without an account. When you are ready to integrate, create an API Rail workspace for governed sandbox access, scoped credentials and production review.

Open API Rail Read the docs

Sandbox-first access
Scoped, hashed API keys
Server-authoritative amounts