API reference
Disbursements
Pay out to mobile money or a bank account.
/api/v1/withdrawals/quotePrice a payout before executing it
Give exactly one destination: a phone, or a bank (bankCode + accountNumber). amountTzs is what the recipient receives, net. Show the returned recipientName and fees.totalFeeTzs to the user, then pass quoteId to POST /v1/withdrawals within its validity. Never recompute the fee yourself.
Request body
userIdstring (uuid)Pay from this user's wallet (the
idfrom POST /v1/users, not your externalId). Or usefromTreasury/subWalletId.fromTreasurybooleanPay from your platform wallet (partner treasury), with no per-user wallet needed. Requires the
treasurycapability and a provisioned treasury.subWalletIdstring (uuid)Agent float: pay from one of your own sub-wallets. Requires the
wakalacapability. Takes precedence overfromTreasuryanduserId.amountTzsintegerrequiredNet to the recipient. Minimum 5,000 TZS.
phoneNumberstringMobile money destination. Or send
bankCode+accountNumber.bankCodestringBank destination, e.g.
CRDB. Send withaccountNumber, instead ofphoneNumber.accountNumberstring
Responses
200A quote.
quoteIdis null when the balance is insufficient.Show fieldsHidequoteIdstring | nullPass to POST /v1/withdrawals. Null when the balance is insufficient.
expiresAtstring | nullNull when
quoteIdis null.expiresInSecondsinteger | nullrecipientPhonestringMobile destinations: the normalised number.
bankCodestringBank destinations only.
bankNamestringBank destinations only.
accountNumberstringBank destinations only.
recipientNamestring | nullRegistered name. Null means unconfirmed: show the raw number, do not block.
receiveAmountTzsintegerWhat the recipient gets.
burnAmountTzsintegerWhat leaves the source wallet: the net plus every fee.
payoutRailstringThe rail this quote is priced for.
feesobjectplatformFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
pspFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
nedaFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
totalFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
balanceobjectavailableTzsintegerWhole Tanzanian shillings. Never a decimal.
sufficientbooleanapprovalobjectRender the approval rule from these fields; never hardcode the threshold.
requiresApprovalbooleanTrue when this payout will be queued for approval (201
requested) rather than executed.secondApprovalThresholdTzsintegerWhole Tanzanian shillings. Never a decimal.
messagestring
- 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
- 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/withdrawals/quote" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"amountTzs": 10000,
"phoneNumber": "255712345678"
}'{
"quoteId": "…",
"expiresAt": "2026-10-27T09:00:00Z",
"expiresInSeconds": 1,
"recipientPhone": "255712345678",
"bankCode": "…",
"bankName": "…",
"accountNumber": "…",
"recipientName": "…",
"receiveAmountTzs": 10000,
"burnAmountTzs": 10000,
"payoutRail": "…",
"fees": {
"platformFeeTzs": 10000,
"pspFeeTzs": 10000,
"nedaFeeTzs": 10000,
"totalFeeTzs": 10000
},
"balance": {
"availableTzs": 10000,
"sufficient": true
},
"approval": {
"requiresApproval": true,
"secondApprovalThresholdTzs": 10000
},
"message": "…"
}/api/v1/withdrawalsExecute a payout against a quote
Send the same source, amountTzs and destination you quoted, plus the quoteId; different terms answer 400 quote_mismatch, an invalid or expired quote 400 invalid_quote, and a price that moved 409 quote_stale. Request a new quote rather than retrying. A payout of 1,000,000 TZS or more (gross) is queued for approval and answers 201 with status: requested (bank payouts that size are refused with bank_amount_unsupported). An identical payout from the same source to the same destination within 5 minutes answers 409 duplicate_withdrawal unless you send allowDuplicate: true. From the platform wallet (fromTreasury: true), endUser is required, and before KYB is approved a one-off allowance applies (403 kyb_required past it).
Parameters
Idempotency-KeystringheaderOptional, single-use: this does NOT replay. The first request with a key claims it for 24 hours; any later request with the same key, including a retry after an error or a timeout, answers 409 "already been used" and does nothing. After an ambiguous outcome, read the resource back; send a new key for a new request.
Request body
userIdstring (uuid)Pay from this user's wallet (the
idfrom POST /v1/users, not your externalId). Or usefromTreasury/subWalletId.fromTreasurybooleanPay from your platform wallet (partner treasury), with no per-user wallet needed. Requires the
treasurycapability and a provisioned treasury.subWalletIdstring (uuid)Agent float: pay from one of your own sub-wallets. Requires the
wakalacapability. Takes precedence overfromTreasuryanduserId.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.
amountTzsintegerrequiredNet to the recipient; must equal the quoted amount. Minimum 5,000 TZS.
phoneNumberstringMobile money destination. Or send
bankCode+accountNumber.bankCodestringBank destination. Send with
accountNumber, instead ofphoneNumber.accountNumberstringquoteIdstringFrom POST /v1/withdrawals/quote.
allowDuplicatebooleandefault falseDeliberately repeat an identical payout inside the 5-minute duplicate window.
Responses
201Payout executed (
burned), or queued for approval (requested).Show fieldsHideidstring (uuid)statusstringburned: executed and dispatched.requested: at or above the approval threshold (1,000,000 TZS gross), queued for approval, nothing burned yet.burnedrequestedamountTzsintegerGross burned: the net plus fees.
receiveAmountTzsintegerWhole Tanzanian shillings. Never a decimal.
bankCodestringBank payouts only.
bankNamestringBank payouts only.
accountNumberstringBank payouts only.
recipientNamestring | nullplatformFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
pspFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
nedaFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
totalFeeTzsintegerPresent when
statusisburned.feeRecipientstring | nullpayoutRailstring | nullpayoutReferencestring | nullpayoutReceiptstring | nullpayoutStatusstring | nullThe payout leg, separate from the burn
status: e.g.pending,completed,reverted(payout failed, burn re-minted, balance restored) orreconcile_required(outcome unconfirmed: an operator resolves it; do not retry). Null before dispatch.confirmationMessagestring | nullmessagestring
- 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
- 409
quote_stale: pricing moved, request a new quote.duplicate_withdrawal: an identical payout is still holding funds (existingdescribes it). Or: TheIdempotency-Keyhas already been used ("This Idempotency-Key has already been used. Use a new key for a new request."), or another request for the same source wallet is still in flight. Nothing was done. Read the earlier request back rather than resending.CodeError - 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 502The burn happened but the payout did not complete.
payoutStatus: reverted: the payout failed and the balance was restored.payoutStatus: reconcile_required: the outcome is unconfirmed; do NOT retry, an operator will complete it or restore the balance.object - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
curl -X POST "https://www.ntzs.co.tz/api/v1/withdrawals" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"userId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"amountTzs": 10000,
"phoneNumber": "255712345678",
"allowDuplicate": false
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "burned",
"amountTzs": 10000,
"receiveAmountTzs": 10000,
"bankCode": "…",
"bankName": "…",
"accountNumber": "…",
"recipientName": "…",
"platformFeeTzs": 10000,
"pspFeeTzs": 10000,
"nedaFeeTzs": 10000,
"feeRecipient": "…",
"payoutRail": "…",
"payoutReference": "…",
"payoutReceipt": "…",
"payoutStatus": "…",
"confirmationMessage": "…",
"message": "…"
}/api/v1/withdrawals/{id}Read a payout and its current status
Parameters
idstring (uuid)pathrequired
Responses
200The withdrawal.Show fieldsHide
idstring (uuid)statusstringThe burn. Whether the money reached the recipient is
payoutStatus.requestedapprovedrequires_second_approvalrejectedburn_submittedburnedfailedamountTzsintegerGross burned: the net plus fees.
receiveAmountTzsintegerWhole Tanzanian shillings. Never a decimal.
recipientPhonestring | nullpayoutKindstring | nullbankfor bank payouts.bankCodestring | nullBank payouts only.
accountNumberstring | nullBank payouts only.
txHashstring | nullpayoutStatusstring | nullThe payout leg, separate from the burn
status: e.g.pending,completed,reverted(payout failed, burn re-minted, balance restored) orreconcile_required(outcome unconfirmed: an operator resolves it; do not retry). Null before dispatch.payoutErrorstring | nullpayoutRailstring | nullpayoutReferencestring | nullconfirmationMessagestring | nullReady-to-show confirmation once the payout completed.
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 withdrawal 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/withdrawals/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "requested",
"amountTzs": 10000,
"receiveAmountTzs": 10000,
"recipientPhone": "255712345678",
"payoutKind": "…",
"bankCode": "…",
"accountNumber": "…",
"txHash": "0x5b1c…e2a9",
"payoutStatus": "…",
"payoutError": "…",
"payoutRail": "…",
"payoutReference": "…",
"confirmationMessage": "…",
"createdAt": "2026-10-27T09:00:00Z"
}