Skip to content

Move money

Disbursements: cash out to mobile money

Two-step flow: quote, then execute. Pay from your platform wallet with fromTreasury: true (plus endUser on the execute call) or from a user's wallet with userId. The quote returns the recipient's registered name, the fee breakdown and the net amount (everything your confirmation screen must show), plus a signed quoteId that authorizes execution at exactly those terms. amountTzs is always the amount the recipient RECEIVES (net).

Required confirmation screen: before the user's final tap, show who they are paying (name + number/account), the fee (fees.totalFeeTzs) and what the recipient receives. This is a Bank of Tanzania consumer-disclosure requirement. On success say “TZS 10,000 is on its way to JOHN DOE (fees TZS 382)”, and never present the gross burn amount as the amount “sent”.
Minimum
5,000 TZS (recipient net)
Quote validity
5 minutes. Fetch a fresh quote if the user dawdles
Bank payouts
Pass bankCode + accountNumber instead of phoneNumber: 38 banks via canonical FI codes (CRDB, NMB, NBC, …; full list in the API reference). Same fees, caps and flow; Selcom single-rail.
Large withdrawal threshold
>= 1,000,000 TZS requires admin approval and may take up to 1 business day (mobile money only)
Enforcement
quoteId is optional during the migration window and becomes mandatory on the announced enforcement date (quote_required)
Never recompute fees
The PSP fee is tiered by amount and serving rail. Display the quote’s fees verbatim; hardcoded formulas will drift
1 · POST /api/v1/withdrawals/quote
const res = await fetch('https://www.ntzs.co.tz/api/v1/withdrawals/quote', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId:      user.id,
    amountTzs:   10000,           // recipient receives this (net), minimum 5,000 TZS
    phoneNumber: '255712345678',  // Vodacom, Airtel, Tigo/Yas, Halotel, TTCL
    // …or a BANK instead of a phone (exactly one destination):
    // bankCode: 'CRDB', accountNumber: '0152768903600'
  }),
})
const quote = await res.json()
// {
//   quoteId: "eyJ2IjoxLCJw…",           // null if balance.sufficient is false
//   expiresAt: "…",                      // valid 5 minutes
//   recipientName: "JOHN DOE",           // registered holder; null = no answer (don't block)
//   receiveAmountTzs: 10000,
//   burnAmountTzs: 10382,                // deducted from the user's balance
//   payoutRail: "selcom",                // the rail this quote is priced for
//   fees: { platformFeeTzs: 52, pspFeeTzs: 300, nedaFeeTzs: 30, totalFeeTzs: 382 },
//   balance: { availableTzs: 25000, sufficient: true },
//   approval: { requiresApproval: false, secondApprovalThresholdTzs: 1000000 }
// }
//
// The PSP fee follows the serving rail's published tariff (amount-tiered).
// NEVER hardcode fees; display the quote's figures. Bank quotes answer
// bankCode/bankName/accountNumber instead of recipientPhone.
//
// Approval warnings render from the 'approval' object, never a hardcoded number:
// requiresApproval=true means this withdrawal queues for an operator
// (status "requested") instead of paying instantly. The threshold is
// platform configuration; a number baked into your app WILL go stale.
2 · POST /api/v1/withdrawals: execute with the quoteId
const res2 = await fetch('https://www.ntzs.co.tz/api/v1/withdrawals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId:      user.id,
    amountTzs:   10000,           // must match the quote
    phoneNumber: '255712345678',  // must match the quote
    quoteId:     quote.quoteId,   // optional today, MANDATORY after the announced enforcement date
  }),
})
const withdrawal = await res2.json()
// { id, status: "burned", receiveAmountTzs: 10000, recipientName: "JOHN DOE",
//   totalFeeTzs: 382,
//   payoutRail: "selcom",                       // the rail that served
//   payoutReference: "16437765-…",              // our reference (poll GET /:id with it)
//   payoutReceipt: "SB0803…",                   // the rail's own receipt, when it returns one
//   payoutStatus: "completed" | "pending",
//   confirmationMessage: "TZS 10,000 sent to JOHN DOE (2557…) via Selcom, ref …",
//   message: "Withdrawal processed: 10000 TZS on its way…" }
//
// PUSH confirmationMessage TO YOUR USER on completion. The rail's own
// confirmation SMS goes only to the platform's corporate account, so
// without it your user never sees a receipt. GET /api/v1/withdrawals/:id
// returns the same fields for status polling.
//
// Errors to handle (fetch a fresh quote and re-confirm):
//   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 quote_required:         enforcement is on and no quoteId was sent
//   409 duplicate_withdrawal:   identical withdrawal within 5 min still holding
//                               funds; do NOT retry (allowDuplicate: true to force)
//   503 bank_rail_unavailable:  bank payouts off on this environment
//
// Large amounts (>= 1,000,000 TZS) queue instead (phones only; banks
// answer 400 bank_amount_unsupported at this size; split the withdrawal):
// { id, status: "requested", message: "…requires admin approval…" }