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.

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.

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

Raise 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

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.

API endpoints, required scopes and purpose
EndpointRequired scopePurpose
POST /v1/subjectsidentity:resolveResolve a consented customer to its MiTax Core identity
POST /v1/calculationstax:calcCalculate PIT, CIT, VAT, PAYE, WHT and CGT for a consented subject
POST /v1/obligationsobligation:readList a subject’s tax obligations
POST /v1/filingsfiling:initiateInitiate a filing on a consented subject’s behalf
POST /v1/paymentspayment:initiateRaise a pending, non-custodial government-payment intent
POST /v1/recordsrecord:readList a subject’s financial and tax records
POST /v1/subscriptionssubscription:readRead a subject’s subscription and metered usage
POST /v1/einvoiceseinvoice:transmitSubmit an e-invoice to the MiTax e-invoicing queue
GET /v1/webhooks, POST /v1/webhookswebhook:manageList and manage signed webhook endpoints
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. You choose the scopes when you create a key, in your workspace.
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 https://api.mitax.io/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 /v1/filings requires.

POST https://api.mitax.io/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 /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.

POST https://api.mitax.io/v1/payments requires payment:initiate

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…"
}
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 Paystack. MiTax never holds funds; it records the handoff, the itemised charges and the outcomes the provider and the authority report independently.

  1. Calculations returns the tax the customer owes.
  2. Filings creates the obligation and a deadline.
  3. Payments returns the amount and fee as a PSP handoff.
  4. The taxpayer pays through Paystack; the provider webhook updates the intent status.
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
HTTPerrorMeaning
401missing_api_keyNo X-API-Key header.
403forbiddenUnknown, revoked, or suspended key.
403insufficient_scopeKey lacks the scope for this verb.
428idempotency_key_requiredA filing or payment mutation omitted Idempotency-Key.
429rate_limitedOver the key’s per-minute cap.
404customer_not_foundNo customer for that customer_ref.
404customer_not_linkedCustomer not yet linked to a MiTax profile.
400calculation_id_requiredFile a VAT/CIT/PAYE/WHT/CGT return with a calc id.
400plan_requiredThe 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: 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