Skip to content

API reference

Disbursements

Pay out to mobile money or a bank account.

post/api/v1/withdrawals/quote

Price 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 id from POST /v1/users, not your externalId). Or use fromTreasury / subWalletId.

  • fromTreasuryboolean

    Pay from your platform wallet (partner treasury), with no per-user wallet needed. Requires the treasury capability and a provisioned treasury.

  • subWalletIdstring (uuid)

    Agent float: pay from one of your own sub-wallets. Requires the wakala capability. Takes precedence over fromTreasury and userId.

  • amountTzsintegerrequired

    Net to the recipient. Minimum 5,000 TZS.

  • phoneNumberstring

    Mobile money destination. Or send bankCode + accountNumber.

  • bankCodestring

    Bank destination, e.g. CRDB. Send with accountNumber, instead of phoneNumber.

  • accountNumberstring

Responses

  • 200A quote. quoteId is null when the balance is insufficient.Show fields
    • quoteIdstring | null

      Pass to POST /v1/withdrawals. Null when the balance is insufficient.

    • expiresAtstring | null

      Null when quoteId is null.

    • expiresInSecondsinteger | null
    • recipientPhonestring

      Mobile destinations: the normalised number.

    • bankCodestring

      Bank destinations only.

    • bankNamestring

      Bank destinations only.

    • accountNumberstring

      Bank destinations only.

    • recipientNamestring | null

      Registered name. Null means unconfirmed: show the raw number, do not block.

    • receiveAmountTzsinteger

      What the recipient gets.

    • burnAmountTzsinteger

      What leaves the source wallet: the net plus every fee.

    • payoutRailstring

      The rail this quote is priced for.

    • feesobject
    • platformFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • pspFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • nedaFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • totalFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • balanceobject
    • availableTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • sufficientboolean
    • approvalobject

      Render the approval rule from these fields; never hardcode the threshold.

    • requiresApprovalboolean

      True when this payout will be queued for approval (201 requested) rather than executed.

    • secondApprovalThresholdTzsinteger

      Whole 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-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
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"
}'
Response · 200
{
  "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": "…"
}
post/api/v1/withdrawals

Execute 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-Keystringheader

    Optional, 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 id from POST /v1/users, not your externalId). Or use fromTreasury / subWalletId.

  • fromTreasuryboolean

    Pay from your platform wallet (partner treasury), with no per-user wallet needed. Requires the treasury capability and a provisioned treasury.

  • subWalletIdstring (uuid)

    Agent float: pay from one of your own sub-wallets. Requires the wakala capability. Takes precedence over fromTreasury and userId.

  • endUserEndUser

    Platform-wallet calls only: which of YOUR users this transaction is for. reference is your own id for them (opaque to us, at most 128 characters). Echoed on the webhooks for the transaction.

  • referencestringrequired
  • namestring
  • phonestring

    A valid Tanzanian number, when you have it.

  • amountTzsintegerrequired

    Net to the recipient; must equal the quoted amount. Minimum 5,000 TZS.

  • phoneNumberstring

    Mobile money destination. Or send bankCode + accountNumber.

  • bankCodestring

    Bank destination. Send with accountNumber, instead of phoneNumber.

  • accountNumberstring
  • quoteIdstring

    From POST /v1/withdrawals/quote.

  • allowDuplicatebooleandefault false

    Deliberately repeat an identical payout inside the 5-minute duplicate window.

Responses

  • 201Payout executed (burned), or queued for approval (requested).Show fields
    • idstring (uuid)
    • statusstring

      burned: executed and dispatched. requested: at or above the approval threshold (1,000,000 TZS gross), queued for approval, nothing burned yet.

      burnedrequested

    • amountTzsinteger

      Gross burned: the net plus fees.

    • receiveAmountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • bankCodestring

      Bank payouts only.

    • bankNamestring

      Bank payouts only.

    • accountNumberstring

      Bank payouts only.

    • recipientNamestring | null
    • platformFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • pspFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • nedaFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • totalFeeTzsinteger

      Present when status is burned.

    • feeRecipientstring | null
    • payoutRailstring | null
    • payoutReferencestring | null
    • payoutReceiptstring | null
    • payoutStatusstring | null

      The payout leg, separate from the burn status: e.g. pending, completed, reverted (payout failed, burn re-minted, balance restored) or reconcile_required (outcome unconfirmed: an operator resolves it; do not retry). Null before dispatch.

    • confirmationMessagestring | null
    • 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
  • 409quote_stale: pricing moved, request a new quote. duplicate_withdrawal: an identical payout is still holding funds (existing describes it). Or: The Idempotency-Key has 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-After and 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
Request
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
}'
Response · 201
{
  "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": "…"
}
get/api/v1/withdrawals/{id}

Read a payout and its current status

Parameters

  • idstring (uuid)pathrequired

Responses

  • 200The withdrawal.Show fields
    • idstring (uuid)
    • statusstring

      The burn. Whether the money reached the recipient is payoutStatus.

      requestedapprovedrequires_second_approvalrejectedburn_submittedburnedfailed

    • amountTzsinteger

      Gross burned: the net plus fees.

    • receiveAmountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • recipientPhonestring | null
    • payoutKindstring | null

      bank for bank payouts.

    • bankCodestring | null

      Bank payouts only.

    • accountNumberstring | null

      Bank payouts only.

    • txHashstring | null
    • payoutStatusstring | null

      The payout leg, separate from the burn status: e.g. pending, completed, reverted (payout failed, burn re-minted, balance restored) or reconcile_required (outcome unconfirmed: an operator resolves it; do not retry). Null before dispatch.

    • payoutErrorstring | null
    • payoutRailstring | null
    • payoutReferencestring | null
    • confirmationMessagestring | null

      Ready-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-After and back off exponentially.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl "https://www.ntzs.co.tz/api/v1/withdrawals/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "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"
}