Skip to content

Move money

Spend: pay merchants & bills

Burn a user's nTZS and pay a merchant Lipa Namba on any network (M-Pesa, Tigo, Airtel, Selcom) or a biller (LUKU electricity, GEPG government control numbers, DSTV, airtime and more) directly from the reserve. Same quote → confirm → execute shape as Disbursements. amountTzs is always the PRINCIPAL the destination receives; fees are added on top. Quote-first by design: execution ALWAYS requires a quoteId.

Scanning a QR? There is nothing extra to enable. A TANQR code is a QR containing a merchant's Lipa Namba, the same till number a customer could read off the counter and type. Decode it with POST /api/v1/lookup/qr, then use the returned payNumber in the ordinary quote → execute flow below. Same tariff as a typed till payment; scanning costs nothing extra.
Display merchantName, not qrMerchantName. The realistic attack on printed QR is a person with a printer pasting their code over a merchant's, so the customer is in the right shop and pays a stranger. The name inside the QR is whatever the attacker wrote; merchantName comes from the acquirer's register and is not. When they disagree we return nameMatch: false. Show both names and make the user confirm. We also verify the code's own checksum and refuse an altered one outright.
Whose nTZS is burned? Pick exactly one funding source. userId burns an end-user's wallet (needs the Wallets capability). fromTreasury: true burns your own partner treasury float (no per-user wallet), which is the path when you simply pay bills from a balance you top up (needs the Treasury capability and a funded treasury; on the execute call also send endUser: { reference }). subWalletId burns an agent float (needs Agent float). All three use the same quote → execute shape below.
Required confirmation screen: before the user's final tap, show who they are paying (recipientName + number), the fee (fees.totalFeeTzs) and the total burned (burnAmountTzs). When recipientName is null, show the raw number with an “unverified destination” caution. This is a Bank of Tanzania consumer-disclosure requirement.
Minimum
500 TZS (principal)
Networks
M-Pesa, Tigo, Airtel, Selcom tills. Some tills require their network: on error till_network_required (burn auto-reverted), retry with the network field
Government bills
GEPG, DAWASA, NHC, Traffic Fine, water bills are FREE up to 20,000 TZS
Quote
Always mandatory; there is no un-quoted spend path
Settlement
Usually seconds; failures auto-revert the burn
Large spend threshold
>= 1,000,000 TZS burn total is refused (amount_too_large)
0 · POST /api/v1/lookup/qr: scan → till number
// The camera gives you a string, not a till number.
const res = await fetch('https://www.ntzs.co.tz/api/v1/lookup/qr', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ payload: scannedString }),  // starts "000201"
})

// {
//   payNumber:      "123456",                     // ← pay this
//   merchantName:   "KARIAKOO HARDWARE LIMITED",  // ← DISPLAY this
//   qrMerchantName: "KARIAKOO HARDWARE",          // printed in the QR
//   nameMatch:      true,       // false → warn: possible swapped sticker
//   amountTzs:      null,       // set on a dynamic QR; use it, don't retype
//   dynamic:        false,
//   resolution:     "resolved", // ONLY "resolved" is payable
//   warnings:       []
// }

if (data.resolution !== 'resolved') {
  // "unresolved": nothing in the code is a registered merchant
  // "ambiguous":  more than one is; make the user choose
  // Either way: do not pay. Ask for the printed till number.
}
1 · POST /api/v1/spend/quote
const res = await fetch('https://www.ntzs.co.tz/api/v1/spend/quote', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId:    user.id,
    kind:      'lipa',          // 'lipa' (merchant till) | 'bill' (biller)
    amountTzs: 1000,            // PRINCIPAL the till receives, minimum 500
    payNumber: '61115582',     // merchant Lipa Namba (lipa)
    // for kind: 'bill' send instead:
    //   utilityCode: 'LUKU',   // from GET /api/v1/spend/billers
    //   utilityRef:  '01234567890',  // meter / control / smartcard number
  }),
})
const quote = await res.json()
// {
//   quoteId: "eyJ2IjoxLCJr…",           // null if balance.sufficient is false
//   expiresAt: "…",                      // valid 5 minutes
//   target: { payNumber: "61115582", network: "…" },  // network auto-resolved
//                                        // from the till registry when you
//                                        // omit it; your explicit value wins
//   recipientName: "ENZI COFFEE COMPANY LIMITED",  // null = registry had no answer
//   principalTzs: 1000,
//   burnAmountTzs: 1035,                 // deducted from the user's balance
//   fees: { selcomFeeTzs: 30, platformFeeTzs: 5, totalFeeTzs: 35 },
//   balance: { availableTzs: 25000, sufficient: true }
// }
2 · POST /api/v1/spend: execute with the quoteId
const res2 = await fetch('https://www.ntzs.co.tz/api/v1/spend', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId:    user.id,
    kind:      'lipa',
    amountTzs: 1000,             // must match the quote
    payNumber: '61115582',      // must match the quote
    quoteId:   quote.quoteId,   // ALWAYS required
  }),
})
const spend = await res2.json()
// { id, status: "burned", payoutStatus: "completed", reference: "202607259999",
//   recipientName: "ENZI COFFEE COMPANY LIMITED", principalTzs: 1000,
//   fees: { totalFeeTzs: 35 }, message: "Payment of 1000 TZS dispatched…" }
//
// payoutStatus "pending" settles server-side within a minute; a failed
// payment AUTO-REVERTS the burn (balance restored), with no partner action.
// Subscribe to the spend.updated webhook to hear the final state.
//
// BILLS (kind: 'bill') RETURN A VOUCHER, AND IT IS THE PRODUCT.
// A LUKU or utility purchase settles with the meter token the customer
// types into their meter; a receipt is not a substitute for it:
//   utilityToken:   "5373 0001 9365 2741 2169"   // display prominently
//   utilityUnits:   "2.8kWh"
//   utilityReceipt: "…"                          // the biller's own receipt
// It is null until the biller issues it (usually seconds, occasionally
// later). Render it as soon as it appears (from the spend.updated
// webhook, or by polling GET /api/v1/spend/:id) and PERSIST it: the
// customer will come back for it, and we cannot reissue what the biller
// only sends once.
//
// Errors to handle (fetch a fresh quote and re-confirm):
//   400 quote_required:   no quoteId sent (spend has no un-quoted path)
//   400 invalid_quote:    expired (> 5 min) or malformed
//   400 quote_mismatch:   user/destination/amount differ from the quote
//   409 quote_stale:      pricing changed since the quote was issued
//   400 unknown_biller:   utilityCode not in the catalogue (see supportedCodes)
//   400 invalid_utility_ref: reference fails the biller's format
//   503 spend_disabled / spend_kind_disabled: rail not enabled yet
Biller catalogue: GET /api/v1/spend/billers
// Render your bill-payment picker from live data, never a hardcoded list.
const { categories } = await (await fetch(
  'https://www.ntzs.co.tz/api/v1/spend/billers',
  { headers: { 'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx' } }
)).json()
// categories: [{ key, label, billers: [{ code, referenceLabel, referenceKind,
//   referenceMinLength, referenceMaxLength, selcomFeeFreeUnder20k,
//   feeFreeUnder20k, feeNote }] }]
// e.g. LUKU → referenceLabel "Meter No", 11 digits
//
// ⚠ Do NOT render selcomFeeFreeUnder20k as a "no fee" badge. It means Selcom
// charges nothing on that biller under 20,000 TZS (true, and worth showing),
// but a service fee applies to EVERY payment, so the payer is never charged
// nothing. A 1,000 TZS government bill costs 35 TZS. Use feeNote for wording,
// and always show the total from /spend/quote.