Get started
Choose your model
There are two ways to integrate, and the one you pick decides which calls you make. Most builders want the platform wallet: collect from, pay out to and pay bills for your users from one wallet, with no per-user wallets and no identity verification per user.
| Platform wallet (start here) | Per-user wallets (by agreement) | |
|---|---|---|
| Holds the money | Your treasury, one wallet for your whole platform | One nTZS wallet per end user |
| You need | An API key, your treasury (created at signup), KYB | The Wallets capability + verified identity for every user |
| Collect | POST /deposits with no userId + endUser | POST /deposits with userId |
| Pay out / pay bills | fromTreasury: true + endUser | userId |
| Your users | Stay in your own ledger | Hold nTZS themselves |
Name the end user on every platform-wallet call. Send
endUser: { reference }: your own id for the user the transaction is for (required; name and phone are optional). It comes back on deposit.completed, withdrawal.updated and spend.updated, so you know whom to credit or notify.KYB. The platform wallet holds your users' money, so it needs approved KYB. Until it is approved you can collect up to TZS 100,000 and, separately, pay out up to TZS 100,000, enough to prove the integration end to end. Past that, calls answer 403
kyb_required (with how much you have used) until KYB is approved in the dashboard. The platform wallet also counts as one participant under the sandbox limits: per transaction, per day and per 30 days, across all your users together.Why not per-user wallets? Every user wallet is an identity we carry, so it is issued only once that user is verified.
POST /api/v1/users answers 202 until then, and every money call for that user fails with wallet_not_provisioned. Choose them only if your users must hold nTZS themselves, and talk to us first.Collect into your platform wallet
await fetch('https://www.ntzs.co.tz/api/v1/deposits', {
method: 'POST',
headers: { 'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx', 'Content-Type': 'application/json' },
body: JSON.stringify({
amountTzs: 10000,
phoneNumber: '255712345678', // the payer; gets the mobile money prompt
endUser: { reference: 'usr_8f3a21' }, // YOUR id for this user. No userId, no POST /users.
}),
})
// → deposit.completed { depositId, amountTzs, endUser: { reference: 'usr_8f3a21', … } }
// credit usr_8f3a21 in your own ledgerPay out from your platform wallet
// 1 · quote (shows the recipient's registered name + exact fees)
const q = await post('/api/v1/withdrawals/quote', {
fromTreasury: true, amountTzs: 10000, phoneNumber: '255754000111',
})
// 2 · execute at those terms
await post('/api/v1/withdrawals', {
fromTreasury: true, amountTzs: 10000, phoneNumber: '255754000111',
quoteId: q.quoteId,
endUser: { reference: 'usr_8f3a21' },
})
// Bills and tills: the same with /api/v1/spend/quote → /api/v1/spend