API reference
Collections
Pull funds in from mobile money, card or bank.
/api/v1/depositsCollect funds from a payer
Minimum 500 TZS. Two models: credit a user's own wallet (userId), or collect into your platform wallet (omit userId, send endUser). The second needs no per-user wallets. Before KYB is approved the platform wallet has a one-off allowance (403 kyb_required past it). Per method: mobile_money sends a prompt to phoneNumber; lipa_namba returns instructions for the payer to pay from phoneNumber; bank_transfer returns account details and a reference and needs payerAccountNumber; card returns a hosted paymentUrl and needs redirectUrl + cancelUrl. This endpoint does not take an Idempotency-Key: after a 502 initiation_uncertain, read the deposit back instead of creating another.
Request body
userIdstring (uuid)Per-user wallets only. Omit it (or send
collectToTreasury: true) to collect into your platform wallet, and thenendUseris required.collectToTreasurybooleanCollect into your platform wallet (partner treasury). Implied when
userIdis omitted.endUserEndUserPlatform-wallet calls only: which of YOUR users this transaction is for.
referenceis your own id for them (opaque to us, at most 128 characters). Echoed on the webhooks for the transaction.referencestringrequirednamestringphonestringA valid Tanzanian number, when you have it.
amountTzsintegerrequiredWhole Tanzanian shillings. Never a decimal.
paymentMethodstringdefault "mobile_money"partner_debitis for partners that are themselves the payment provider (by agreement): no push prompt. You debit your own customer and pay our collection account quoting the returnedreference; the signed callback reporting exactlyamountTzsmints. 403partner_debit_not_granteduntil enabled for your account.mobile_moneycardbank_transferlipa_nambapartner_debitphoneNumberstringRequired for
mobile_moneyandlipa_namba(the number the payer pays from). Note the field isphoneNumber, notphone.payerAccountNumberstringRequired for
bank_transfer: the account the payer sends from. Bank credits arrive without the payer's narration, so this is how the credit is matched.redirectUrlstring (uri)Required for
card. HTTPS only. Where the payer lands after paying.cancelUrlstring (uri)Required for
card. HTTPS only. Where the payer lands on cancelling.
Responses
201Collection initiated.Show fieldsHide
idstring (uuid)statusstringsubmittedamountTzsintegerWhole Tanzanian shillings. Never a decimal.
paymentMethodstringmobile_moneycardbank_transferlipa_nambapartner_debitcollectToTreasurybooleanPresent (true) on platform-wallet collections.
endUserEndUserPlatform-wallet calls only: which of YOUR users this transaction is for.
referenceis your own id for them (opaque to us, at most 128 characters). Echoed on the webhooks for the transaction.referencestringrequirednamestringphonestringA valid Tanzanian number, when you have it.
instructionsstring | objectWhat to show the payer. A sentence for
mobile_money; an object forlipa_namba(lipaNamba,accountName,amountTzs,payFromPhone,note)bank_transfer(institution,accountNumber,accountName,reference,amountTzs,note) andpartner_debit(provider,reference,referenceField,amountTzs,note). Absent forcard.referencestringbank_transfer: the reference the payer must quote.partner_debit: our reference; quote it to your provider ininstructions.referenceField.paymentUrlstringcardonly: redirect the payer here.
- 400Invalid request.CodeError
- 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
- 403Forbidden: a missing capability, unapproved KYB past the platform-wallet allowance (
kyb_required), orpartner_debitwithout the per-partner grant (partner_debit_not_granted).CodeError - 404
userIdis not one of your users.CodeError - 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 502The provider refused (
initiation_failed), or delivery of the prompt could not be confirmed (initiation_uncertain: the collection may still be taken; do NOT retry, poll GET /v1/deposits/{id}). Both carry the depositid.SentenceError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
curl -X POST "https://www.ntzs.co.tz/api/v1/deposits" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"amountTzs": 10000,
"paymentMethod": "mobile_money",
"phoneNumber": "255712345678"
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "submitted",
"amountTzs": 10000,
"paymentMethod": "mobile_money",
"endUser": {
"reference": "usr_8f3a21",
"name": "…",
"phone": "255712345678"
},
"instructions": "…",
"reference": "…",
"paymentUrl": "https://yourapp.com/callback"
}/api/v1/deposits/{id}Read a deposit and its current status
Poll this for the status change, or take the webhook. It does not echo the payment instructions, so keep them from the create response. A bank_transfer deposit that is still submitted carries its reference so you can re-show it.
Parameters
idstring (uuid)pathrequired
Responses
200The deposit.Show fieldsHide
idstring (uuid)statusstringmintedis the success terminal state;rejected,cancelledandmint_failedare failures. Everything else is in flight.submittedkyc_pendingkyc_approvedkyc_rejectedawaiting_fiatfiat_confirmedbank_approvedplatform_approvedmint_pendingmint_requires_safemint_processingmintedmint_failedrejectedcancelledamountTzsintegerWhole Tanzanian shillings. Never a decimal.
paymentMethodstringmobile_moneycardbank_transferlipa_nambapartner_debitreferencestringbank_transfer, while the deposit is still
submitted: the reference the payer must quote. partner_debit: our reference for the deposit, always. Quote it to your provider as the createDeposit response'sinstructions.referenceField.txHashstring | nullThe mint transaction, once minting has started.
createdAtstring (date-time)
- 400Invalid request.CodeError
- 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
- 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
- 404No such deposit under your partner account.CodeError
- 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
curl "https://www.ntzs.co.tz/api/v1/deposits/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "submitted",
"amountTzs": 10000,
"paymentMethod": "mobile_money",
"reference": "…",
"txHash": "0x5b1c…e2a9",
"createdAt": "2026-10-27T09:00:00Z"
}/api/v1/deposits/{id}/claimConfirm a bank-transfer deposit with the Selcom receipt
Banks and Selcom wallets routinely drop the reference from the transfer narration, so a bank_transfer deposit can only be settled automatically when the sending account or name identifies it. The Selcom receipt on the payer's confirmation (e.g. SB1106Z92ST from a bank, 111610T7ZY from a Selcom wallet) removes the guesswork: once that credit is on our account for the deposit's exact amount, the deposit advances and nTZS mints within seconds. Works for end-user deposits and treasury top-ups. A 202 with claim: not_found means the payment has not reached our account yet: retry after a minute. Safe to repeat.
Parameters
idstring (uuid)pathrequired
Request body
receiptstringrequiredThe Selcom receipt number from the payment confirmation. Case and spaces are ignored.
Responses
200
claimiscredited(statusmint_pending, ormint_requires_safefor large amounts) oralready_credited.Show fieldsHideidstring (uuid)claimstringcreditedalready_creditedstatusstringmessagestring
202
claim: not_found: the payment is not on our account yet. Retry in a minute.Show fieldsHideidstring (uuid)claimstringnot_foundstatusstringmessagestring
- 400Invalid request.CodeError
- 401Missing, empty, or invalid API key. No machine-readable code is returned.BareError
- 403Forbidden: a missing capability, unapproved KYB, a source IP outside your allowlist, or a frozen wallet.CodeError
- 404No such deposit under your partner account.CodeError
- 409Refused:
not_bank_transfer,deposit_not_open,receipt_used,receipt_unavailable,amount_mismatch,paid_before_depositorambiguous.messagesays what happens next.CodeError - 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
curl -X POST "https://www.ntzs.co.tz/api/v1/deposits/14e17d04-ec7f-4d99-91a3-dfbaca19fba1/claim" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"receipt": "SB1106Z92ST"
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"claim": "credited",
"status": "…",
"message": "…"
}