Skip to content

API reference

Collections

Pull funds in from mobile money, card or bank.

post/api/v1/deposits

Collect 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 then endUser is required.

  • collectToTreasuryboolean

    Collect into your platform wallet (partner treasury). Implied when userId is omitted.

  • 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

    Whole Tanzanian shillings. Never a decimal.

  • paymentMethodstringdefault "mobile_money"

    partner_debit is 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 returned reference; the signed callback reporting exactly amountTzs mints. 403 partner_debit_not_granted until enabled for your account.

    mobile_moneycardbank_transferlipa_nambapartner_debit

  • phoneNumberstring

    Required for mobile_money and lipa_namba (the number the payer pays from). Note the field is phoneNumber, not phone.

  • payerAccountNumberstring

    Required 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 fields
    • idstring (uuid)
    • statusstring

      submitted

    • amountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • paymentMethodstring

      mobile_moneycardbank_transferlipa_nambapartner_debit

    • collectToTreasuryboolean

      Present (true) on platform-wallet collections.

    • 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.

    • instructionsstring | object

      What to show the payer. A sentence for mobile_money; an object for lipa_namba (lipaNamba, accountName, amountTzs, payFromPhone, note) bank_transfer (institution, accountNumber, accountName, reference, amountTzs, note) and partner_debit (provider, reference, referenceField, amountTzs, note). Absent for card.

    • referencestring

      bank_transfer: the reference the payer must quote. partner_debit: our reference; quote it to your provider in instructions.referenceField.

    • paymentUrlstring

      card only: 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), or partner_debit without the per-partner grant (partner_debit_not_granted).CodeError
  • 404userId is not one of your users.CodeError
  • 429Rate limited. Respect Retry-After and 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 deposit id.SentenceError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
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"
}'
Response · 201
{
  "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"
}
get/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 fields
    • idstring (uuid)
    • statusstring

      minted is the success terminal state; rejected, cancelled and mint_failed are failures. Everything else is in flight.

      submittedkyc_pendingkyc_approvedkyc_rejectedawaiting_fiatfiat_confirmedbank_approvedplatform_approvedmint_pendingmint_requires_safemint_processingmintedmint_failedrejectedcancelled

    • amountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • paymentMethodstring

      mobile_moneycardbank_transferlipa_nambapartner_debit

    • referencestring

      bank_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's instructions.referenceField.

    • txHashstring | null

      The 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-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/deposits/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "status": "submitted",
  "amountTzs": 10000,
  "paymentMethod": "mobile_money",
  "reference": "…",
  "txHash": "0x5b1c…e2a9",
  "createdAt": "2026-10-27T09:00:00Z"
}
post/api/v1/deposits/{id}/claim

Confirm 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

  • receiptstringrequired

    The Selcom receipt number from the payment confirmation. Case and spaces are ignored.

Responses

  • 200claim is credited (status mint_pending, or mint_requires_safe for large amounts) or already_credited.Show fields
    • idstring (uuid)
    • claimstring

      creditedalready_credited

    • statusstring
    • messagestring
  • 202claim: not_found: the payment is not on our account yet. Retry in a minute.Show fields
    • idstring (uuid)
    • claimstring

      not_found

    • statusstring
    • 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
  • 404No such deposit under your partner account.CodeError
  • 409Refused: not_bank_transfer, deposit_not_open, receipt_used, receipt_unavailable, amount_mismatch, paid_before_deposit or ambiguous. message says what happens next.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/deposits/14e17d04-ec7f-4d99-91a3-dfbaca19fba1/claim" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "receipt": "SB1106Z92ST"
}'
Response · 200
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "claim": "credited",
  "status": "…",
  "message": "…"
}