Skip to content

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 payment
POST /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
})