Move money
Collections: accept deposits
Initiate a payment in Tanzanian Shillings. On success, nTZS is minted 1:1 into your platform wallet (no userId) or the user's own wallet (userId). Supports mobile money (push prompt), Lipa Namba (user-initiated, so it works even with no push rail), card and bank transfer.
Platform wallet: omit
userId and send endUser: { reference }; the money lands in your treasury, no per-user wallet needed. Every example below works that way too: swap userId for endUser.Per-user wallets: userId must be the
id returned from POST /api/v1/users, not your own externalId.Minimum
500 TZS
Mobile providers
Vodacom (M-Pesa), Airtel (Airtel Money), Tigo (Tigo Pesa), Halotel (HaloPesa), TTCL (TTCL Pesa), Yass
Settlement
Real-time on Base mainnet after payment confirmation
Bank transfer
Any Tanzanian bank via TIPS, matched by the account the payer sends from (payerAccountNumber) + exact amount, mints in ~10 min, or within seconds when the payer gives you their Selcom receipt (POST /deposits/:id/claim). Show the reference too.
POST /api/v1/deposits (mobile money)
const res = 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({
userId: '14e17d04-ec7f-4d99-91a3-dfbaca19fba1', // id from POST /api/v1/users
amountTzs: 10000, // minimum 500 TZS
paymentMethod: 'mobile_money', // default
phoneNumber: '255712345678', // required for mobile_money; use phoneNumber, not phone
}),
})
// { id, status: "submitted", amountTzs: 10000,
// paymentMethod: "mobile_money",
// instructions: "Check your phone for the mobile money payment prompt" }POST /api/v1/deposits (card)
body: JSON.stringify({
userId: user.id,
amountTzs: 10000,
paymentMethod: 'card',
redirectUrl: 'https://yourapp.com/payment/success', // required, must be HTTPS
cancelUrl: 'https://yourapp.com/payment/cancel', // required, must be HTTPS
})
// { id, status: "submitted", amountTzs: 10000,
// paymentMethod: "card",
// paymentUrl: "https://pay.snippe.sh/c/..." }
// → redirect your user to paymentUrl to complete card paymentPOST /api/v1/deposits (bank transfer)
// No phone number: the payment is matched by a generated reference the
// payer puts in the transfer narration.
body: JSON.stringify({
userId: user.id,
amountTzs: 250000,
paymentMethod: 'bank_transfer',
})
// {
// id, status: "submitted", amountTzs: 250000,
// paymentMethod: "bank_transfer",
// reference: "NTZ-7K2M9Q",
// instructions: {
// institution: "SELCOM MICROFINANCE…", // the payer selects this in
// accountNumber: "5529…", // RENDER FROM THE RESPONSE: a
// accountName: "NEDA LABS LIMITED", // hardcoded account number sends
// // every donor to the wrong place
// // the day it changes
// reference: "NTZ-7K2M9Q", // MUST go in the description
// amountTzs: 250000, // MUST match exactly
// note: "..." // ready-to-show payer guidance
// }
// }
// Show instructions in your UI. The user sends a bank transfer (TIPS, any
// Tanzanian bank) of EXACTLY amountTzs with the reference in the transfer
// description; nTZS mints automatically once the credit lands, typically
// within ~10 minutes. The reference stays valid for 72 hours and
// GET /api/v1/deposits/:id echoes it while the deposit is open, so you can
// re-show the payment details. A transfer with a missing reference or a
// different amount is held for manual review. Money is never lost.POST /api/v1/deposits/:id/claim (bank transfer: confirm with the Selcom receipt)
// Banks and Selcom wallets often DROP the reference from the narration.
// Every payer gets a Selcom receipt on their confirmation screen, e.g.
// SB1106Z92ST (bank) or 111610T7ZY (Selcom wallet). Ask for it after they
// pay ("Already paid? Enter your Selcom receipt") and send it here: once
// the credit is on our account for the exact amount, the deposit advances
// and nTZS mints within seconds. No manual review, no reference needed.
// Works for end-user deposits AND treasury top-ups (fund-treasury ids).
await fetch(`/api/v1/deposits/${deposit.id}/claim`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ receipt: 'SB1106Z92ST' }),
})
// 200 { claim: "credited", status: "mint_pending", message } → minting now
// 200 { claim: "already_credited" } → nothing to do
// 202 { claim: "not_found", message } → not on our account yet; retry in ~1 min
// 409 { claim: "refused", error: "amount_mismatch" | "receipt_used" | ... }
// → show message; our team resolves it, the payer must NOT pay again
// Safe to repeat. Test mode accepts any well-formed receipt.POST /api/v1/deposits: partner debit (payment providers, by agreement)
// For a partner that IS the payment provider (e.g. AZAM Pesa): the top-up
// happens inside your own wallet app, with no push prompt. Create the
// deposit FIRST (it fixes the user and amount), then move the money.
body: JSON.stringify({
userId: user.id,
amountTzs: 10000,
paymentMethod: 'partner_debit',
})
// {
// id, status: "submitted", amountTzs: 10000,
// paymentMethod: "partner_debit",
// reference: "NTPK7M2Q9X4AB",
// instructions: {
// provider: "azampay", // fixed by your agreement, not the request
// reference: "NTPK7M2Q9X4AB",
// referenceField: "utilityref", // quote the reference in this field
// amountTzs: 10000,
// note: "..."
// }
// }
// Then debit your customer for EXACTLY amountTzs and pay our collection
// account with you, quoting the reference. Your SIGNED callback reporting
// exactly that amount mints the nTZS (deposit.completed fires). A different
// amount is refused; an unsigned callback never mints.
// 403 partner_debit_not_granted → not enabled for your account (needs a
// signed collection agreement). Test keys accept it without one.POST /api/v1/deposits: Lipa Namba (user pays from their own phone)
// No push prompt: your user pays OUR Lipa Namba from their own
// mobile-money menu. Works on EVERY network, including when no push
// rail can reach the user's network, because the user initiates it.
body: JSON.stringify({
userId: user.id,
amountTzs: 10000,
paymentMethod: 'lipa_namba',
phoneNumber: '255744123456', // the number they will PAY FROM; this
}) // is the matching key, not a prompt target
// {
// id, status: "submitted", amountTzs: 10000,
// paymentMethod: "lipa_namba",
// instructions: {
// lipaNamba: "70031820", // the business number they pay
// accountName: "NEDA LABS LIMITED", // shown in their M-Pesa confirm screen
// amountTzs: 10000, // MUST be paid exactly
// payFromPhone: "255744123456", // MUST be paid from this number
// note: "..." // ready-to-show payer guidance
// }
// }
// Show instructions; the user does "Lipa kwa M-Pesa / Lipa Namba" in their
// own menu. The credit is matched by EXACT amount + payer phone and nTZS
// mints automatically, typically within ~5 minutes. Poll
// GET /api/v1/deposits/:id for the status change. A payment from a
// different number or a different amount is held for manual review rather
// than guessed. Money is never lost. Their network may add its own fee on
// top; say so in your UI to avoid "I paid 1,050, got 1,000" tickets.POST /api/v1/deposits (collect to treasury)
// Payment-collection mode: mint nTZS directly to your platform treasury
// instead of the user's individual wallet. Useful for marketplaces and
// escrow flows where you collect funds before distributing them.
//
// No attestation needed on the payer for this mode: create the user once
// (POST /api/v1/users; the 202 kyc_attestation_required response still
// returns the id) and use that id here as the tracking reference. No
// wallet is issued to the payer and no review is opened; attestation
// matters only if you later want THIS payer to hold a wallet.
body: JSON.stringify({
userId: user.id, // the payer, for tracking
amountTzs: 50000,
paymentMethod: 'mobile_money',
phoneNumber: '255712345678',
collectToTreasury: true, // mint to partner treasury wallet
})