API reference
Spend
Pay bills and merchant tills.
/api/v1/spend/quotePrice a bill or till payment
For kind: lipa send payNumber; for kind: bill send utilityCode + utilityRef. amountTzs is the principal the till or biller receives. Show the returned recipientName and fees.totalFeeTzs, then pass quoteId to POST /v1/spend with the same terms.
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.kindstringrequiredlipabillamountTzsintegerrequiredPrincipal to the till or biller. Minimum 500 TZS.
payNumberstringRequired for
kind: lipa: the merchant Lipa Namba, 4–12 digits.networkstringFor
kind: lipa: the till's mobile network. Normally leave blank; it is resolved from the till registry.utilityCodestringRequired for
kind: bill. See GET /v1/spend/billers.utilityRefstringRequired for
kind: bill: the meter, control or account number.
Responses
200A quote, including the resolved merchant or biller name and the total.Show fieldsHide
quoteIdstring | nullPass to POST /v1/spend. Null when the balance is insufficient.
expiresAtstring | nullNull when
quoteIdis null.expiresInSecondsinteger | nullkindstringlipabilltargetobject{ payNumber, network }for lipa,{ utilityCode, utilityRef }for bill.payNumberstringnetworkstring | nullutilityCodestringutilityRefstringrecipientNamestring | nullThe merchant or bill account holder. Null means unconfirmed.
nameUnavailableReasonstringPresent only when
recipientNameis null.principalTzsintegerWhat the till or biller receives.
burnAmountTzsintegerThe total debited: principal plus every fee.
feesobjectselcomFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
platformFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
nedaFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
totalFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
balanceobjectavailableTzsintegerWhole Tanzanian shillings. Never a decimal.
sufficientbooleanmessagestring
- 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/spend/quote" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"kind": "lipa",
"amountTzs": 10000,
"payNumber": "123456"
}'{
"quoteId": "…",
"expiresAt": "2026-10-27T09:00:00Z",
"expiresInSeconds": 1,
"kind": "lipa",
"target": {
"payNumber": "…",
"network": "…",
"utilityCode": "…",
"utilityRef": "…"
},
"recipientName": "…",
"principalTzs": 10000,
"burnAmountTzs": 10000,
"fees": {
"selcomFeeTzs": 10000,
"platformFeeTzs": 10000,
"nedaFeeTzs": 10000,
"totalFeeTzs": 10000
},
"balance": {
"availableTzs": 10000,
"sufficient": true
},
"message": "…"
}/api/v1/spendPay a bill or merchant till against a quote
A quote is mandatory: without one you get quote_required. Send the same source, kind, amountTzs and destination you quoted; different terms answer 400 quote_mismatch. Spends of 1,000,000 TZS or more are refused (amount_too_large). This endpoint does not take an Idempotency-Key; an identical payment within the duplicate window answers 409 duplicate_spend unless you send allowDuplicate: true. Persist the returned reference; it is what the biller recognises.
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.
quoteIdstringrequiredFrom POST /v1/spend/quote.
kindstringrequiredlipabillamountTzsintegerrequiredThe quoted principal.
payNumberstringRequired for
kind: lipa: the quoted Lipa Namba.utilityCodestringRequired for
kind: bill, as quoted.utilityRefstringRequired for
kind: bill, as quoted.networkstringA till's mobile network, when
till_network_requiredasked for it.allowDuplicatebooleandefault falseDeliberately repeat an identical payment inside the duplicate window.
Responses
201Payment accepted.Show fieldsHide
idstring (uuid)statusstringburnedpayoutStatusstring | 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.referencestring | nullPersist this; it is what the biller recognises.
kindstringlipabilltargetobjectpayNumberstringnetworkstring | nullutilityCodestringutilityRefstringrecipientNamestring | nullprincipalTzsintegerWhole Tanzanian shillings. Never a decimal.
burnAmountTzsintegerWhole Tanzanian shillings. Never a decimal.
feesobjectselcomFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
platformFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
nedaFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
totalFeeTzsintegerWhole Tanzanian shillings. Never a decimal.
utilityTokenstringPresent when settlement was already seen. For LUKU the token is the product.
utilityUnitsstringmessagestring
- 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: request a new quote.duplicate_spend: an identical payment was just made (existingdescribes it); show it, or resend withallowDuplicate: true.CodeError - 429Rate limited. Respect
Retry-Afterand back off exponentially.CodeError - 502The payment did not complete.
payoutStatus: reverted: refused and the balance restored;error: till_network_requiredmeans retry withnetwork.payoutStatus: reconcile_required: unconfirmed; do NOT retry, an operator resolves it.object - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
curl -X POST "https://www.ntzs.co.tz/api/v1/spend" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"quoteId": "…",
"kind": "lipa",
"amountTzs": 10000,
"payNumber": "123456",
"allowDuplicate": false
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "burned",
"payoutStatus": "…",
"reference": "…",
"kind": "lipa",
"target": {
"payNumber": "…",
"network": "…",
"utilityCode": "…",
"utilityRef": "…"
},
"recipientName": "…",
"principalTzs": 10000,
"burnAmountTzs": 10000,
"fees": {
"selcomFeeTzs": 10000,
"platformFeeTzs": 10000,
"nedaFeeTzs": 10000,
"totalFeeTzs": 10000
},
"utilityUnits": "…",
"message": "…"
}/api/v1/spend/{id}Read a spend and its current status
Parameters
idstring (uuid)pathrequired
Responses
200The spend.Show fieldsHide
idstring (uuid)statusstringThe burn. Whether the biller was paid is
payoutStatus.requestedapprovedrequires_second_approvalrejectedburn_submittedburnedfailedpayoutStatusstring | 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 | nullreferencestring | nullThe reference the biller recognises.
kindstring | nulllipabillnulltargetobjectpayNumberstring | nullnetworkstring | nullutilityCodestring | nullutilityRefstring | nullrecipientNamestring | nullprincipalTzsinteger | nullburnAmountTzsintegerWhole Tanzanian shillings. Never a decimal.
utilityTokenstring | nullFor token billers (e.g. LUKU) the token IS the product. Show it to the customer.
utilityUnitsstring | nullutilityReceiptstring | nullselcomReceiptstring | nullactualChargesTzsinteger | nullcreatedAtstring (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 spend 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/spend/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "requested",
"payoutStatus": "…",
"payoutError": "…",
"reference": "…",
"kind": "lipa",
"target": {
"payNumber": "…",
"network": "…",
"utilityCode": "…",
"utilityRef": "…"
},
"recipientName": "…",
"principalTzs": 10000,
"burnAmountTzs": 10000,
"utilityToken": "…",
"utilityUnits": "…",
"utilityReceipt": "…",
"selcomReceipt": "…",
"actualChargesTzs": 10000,
"createdAt": "2026-10-27T09:00:00Z"
}/api/v1/spend/billersThe biller catalogue
Grouped by category; each biller carries its reference label and validation rules. A fee applies to every payment, so never render a biller as free, and price with POST /v1/spend/quote.
Responses
200Supported billers.Show fieldsHide
enabledbooleanWhether spend rails are switched on for you.
livemodebooleanPresent (false) for test keys.
categoriesobject[]keystringlabelstringbillersobject[]codestringThe
utilityCodeto quote with.referenceLabelstringreferenceKindstringreferenceMinLengthinteger | nullreferenceMaxLengthinteger | nullfeeFreeUnder20kbooleanTrue only if the total charge is zero, which is effectively never.
selcomFeeFreeUnder20kbooleanThe provider leg alone is free under 20,000 TZS. A service fee still applies.
feeNotestring | nullnotestring
- 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 "https://www.ntzs.co.tz/api/v1/spend/billers" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"enabled": true,
"categories": [
{
"key": "…",
"label": "…",
"billers": [
{}
]
}
],
"note": "…"
}/api/v1/merchant/payPay a Biashara merchant from a wallet balance
The balance tender at a Biashara checkout: your signed-in user pays the merchant from their own nTZS balance. Settlement is synchronous: the 201 is final. The merchant receives the full amount. A sale is a transfer between two holders: nothing is minted and no deposit is created.
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
payerUserIdstring (uuid)requiredYour user; you are vouching they are signed in.
handlestringrequiredThe merchant's checkout handle.
amountTzsintegerrequiredWhole shillings, at least 100.
linkIdstring (uuid)Optional. Validated against the merchant's payment link; must equal a fixed link's amount.
payerNamestringOptional. Shown in the merchant's sales list.
payerPhonestringTanzanian mobile number.
2557XXXXXXXX,07XXXXXXXXand+2557XXXXXXXXare all accepted.externalReferencestringOptional. Your own order id, opaque to nTZS. Echoed on this response, on every
GET /api/v1/biashara/collectionsrow and on thedeposit.completedwebhook. Not unique: a retried payment for one order is a second sale with the same reference.
Responses
201Payment executed, synchronous and final.Show fieldsHide
idstring (uuid)collectionIdstring (uuid)transferIdstring (uuid)statusstringcompletedpaymentMethodstringntzs_balancetxHashstringamountTzsintegerWhole Tanzanian shillings. Never a decimal.
merchantobjecthandlestringbusinessNamestringpayerUserIdstring (uuid)externalReferencestring | nullEchoed verbatim;
nullwhen none was sent.livemodeboolean
- 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
- 404The payer is not one of your users (
user_not_found), the merchant handle is unknown or inactive, or the payment link is unknown or inactive.CodeError - 409The
Idempotency-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.SentenceError - 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/merchant/pay" \
-H "Authorization: Bearer $NTZS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"payerUserId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"handle": "…",
"amountTzs": 10000,
"payerPhone": "255712345678"
}'{
"id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"collectionId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"transferId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "completed",
"paymentMethod": "ntzs_balance",
"txHash": "0x5b1c…e2a9",
"amountTzs": 10000,
"merchant": {
"handle": "…",
"businessName": "…"
},
"payerUserId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"externalReference": "…",
"livemode": true
}