Skip to content

API reference

Lookup

Resolve who is behind a number, till or bill account before paying.

post/api/v1/lookup/recipient-name

Resolve the registered name behind a mobile number

For the "Sending to: JOHN DOE" line before a user confirms. Fail-soft: name: null means no confirmation was available: show the raw number and continue, never block. Rate limited to 30/min per partner and audited per call.

Request body

  • phoneNumberstringrequired

    Tanzanian mobile number. 2557XXXXXXXX, 07XXXXXXXX and +2557XXXXXXXX are all accepted.

Responses

  • 200Resolved, or name: null when unconfirmed.Show fields
    • phonestring
    • networkstring

      vodacomairteltigohalotelttclunknown

    • namestring | null
  • 400Invalid request.CodeError
  • 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
  • 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/lookup/recipient-name" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "255712345678"
}'
Response · 200
{
  "phone": "255712345678",
  "network": "vodacom",
  "name": "…"
}
post/api/v1/lookup/merchant-name

Resolve the trading name behind a till or bill account

Fail-soft like the recipient lookup. Bill validation is amount-aware, so send amountTzs when known. Upstream can take ~25s, so debounce and never put this on a keystroke. Rate limited to 60/min per partner.

Request body

  • kindstringrequired

    lipabill

  • payNumberstring
  • utilityCodestring
  • utilityRefstring
  • amountTzsinteger

    Whole Tanzanian shillings. Never a decimal.

Responses

  • 200Resolved, or name: null with a reason.Show fields
    • kindstring

      lipabill

    • targetstring
    • namestring | null
    • reasonstring
  • 400Invalid request.CodeError
  • 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
  • 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/lookup/merchant-name" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "lipa"
}'
Response · 200
{
  "kind": "lipa",
  "target": "…",
  "name": "…",
  "reason": "…"
}
post/api/v1/lookup/qr

Resolve a scanned TANQR payload to a destination

Request body

  • payloadstringrequired

    The raw scanned QR string.

Responses

  • 200The destination the code resolves to.object
  • 400Invalid request.CodeError
  • 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
  • 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/lookup/qr" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "payload": "…"
}'