Skip to content

Move money

Name confirmation: show who is being paid

Resolve the registered name behind a phone number, a Lipa Namba or a bill account, so the user can confirm the destination before any money moves. Both endpoints are fail-soft: a null name means no confirmation was available, never that the payment should be blocked.

Why this is separate from the quote. A quote already discloses the name, but a quote is a priced, single-use, expiring commitment, and a QR scan is not. A user points a camera at a code long before choosing an amount. Minting and discarding quotes just to render a confirmation screen is wasteful and a worse contract, so validation is its own step. The merchant lookup is deliberately not behind the spend or ramp payment flags either: it moves no money, so you can finish and test your confirmation UX while the rail is still pending approval.
Null is a normal outcome. Never block on it. A number can be unregistered, or the upstream enquiry can be down, and neither means the payment would fail. Blocking on null turns a cosmetic feature into an outage. A malformedrequest is different and still returns 400: invalid_phone, unknown_biller (the response lists every supported code), or invalid_utility_ref. Those are bugs in the caller.

Rate limit

Recipient 30/min, merchant 60/min per partner. Both return 429 with a Retry-After header. These resolve PII and must not be usable for bulk enumeration.

Audited

Every lookup writes an audit row. Expect enumeration patterns to be noticed.

Test mode

Both return deterministic names with no upstream call and no quota use, so you can build the whole confirmation screen against a sandbox key.

Latency

Merchant lookups go upstream to the utility and can take up to ~25s. Do not put one on a keystroke; debounce, and show a spinner.
POST /api/v1/lookup/recipient-name: who owns this mobile number
const res = await fetch('https://www.ntzs.co.tz/api/v1/lookup/recipient-name', {
  method: 'POST',
  headers: { Authorization: 'Bearer ntzs_live_xxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({ phoneNumber: '255712345678' }),
})

// 200: confirmed
{ "phone": "255712345678", "network": "tigo", "name": "JOHN DOE" }

// 200: no confirmation available. NOT an error: show the raw number and continue.
{ "phone": "255712345678", "network": "tigo", "name": null }
POST /api/v1/lookup/merchant-name: who owns this till or bill account
// A Lipa Namba (a TANQR scan resolves to one of these)
{ "kind": "lipa", "payNumber": "012345" }

// A bill account. Biller validation is amount-aware: send amountTzs when you
// know it for an exact answer; the default is the biller's own stated floor.
{ "kind": "bill", "utilityCode": "LUKU", "utilityRef": "01234567890", "amountTzs": 10000 }

// 200: confirmed
{ "kind": "lipa", "target": "lipa:012345", "payNumber": "012345",
  "name": "KARIAKOO HARDWARE LIMITED" }

// 200: unconfirmed, with the reason. Show the raw number and a warning.
{ "kind": "lipa", "target": "lipa:012345", "payNumber": "012345",
  "name": null, "reason": "lookup_unavailable" }