Skip to content

API reference

nTZS Partner API

Programmable Tanzanian shilling payments: collections, disbursements, wallets and settlement. 35 endpoints, generated from the OpenAPI contract at /openapi.json, the same document you can generate a typed client from.

The nTZS partner API. Every endpoint here authenticates with a partner API key.

Before you build

Start in test mode. A test key (ntzs_test_…) simulates users, collections, transfers, payouts and spend with no money and no chain, and POST /v1/testmode/advance settles pending transactions on demand, so an integration can be written, run, advanced and corrected in a loop without waiting on a rail. Ramp, swap, retro-KYC and KYC attestation are not simulated: a test key gets 501 not_available_in_test_mode there. Your test key mirrors your live capabilities.

Capabilities gate endpoints, not products. Your account is granted a set of capabilities (collections, disbursements, transfers, treasury, wallets, swap, ramp, …) and an endpoint outside your grant answers 403 regardless of key validity.

Quotes are not optional where they exist. Withdrawals, spend and ramp price themselves through a quote endpoint. Never recompute a fee client-side: request a quote, show the user the name and total it returns, then pass the quoteId back. Quotes expire.

Errors come in three shapes. Most endpoints put the machine-readable code in error; identity and KYC paths put a sentence there and the code in code; 401s carry no code at all. Branch on code ?? error and keep the HTTP status.

Retries. Transfers, withdrawals, merchant payments, swaps and ramp accept Idempotency-Key. Send one: a 502 can mean the request was taken. On ramp a reused key replays the original response; everywhere else a key is single-use and a reuse answers 409. Either way it stops a retry paying twice: after an ambiguous outcome, read the resource back instead of resending.

Base URL and authentication
# Live and test keys use the same host
curl https://www.ntzs.co.tz/api/v1/users/{id} \
  -H "Authorization: Bearer ntzs_test_xxxxxxxxxxxx"
Errors: branch on code ?? error
{ "error": "insufficient_balance", "message": "…", "details": { … } }
{ "error": "A NIDA number is required…", "code": "kyc_required" }
{ "error": "Missing or invalid Authorization header" }

Every code, what it means and whether a retry is safe: error reference. Events your endpoint receives: webhooks.

Resources