Skip to content

API reference

Spend

Pay bills and merchant tills.

post/api/v1/spend/quote

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

  • kindstringrequired

    lipabill

  • amountTzsintegerrequired

    Principal to the till or biller. Minimum 500 TZS.

  • payNumberstring

    Required for kind: lipa: the merchant Lipa Namba, 4–12 digits.

  • networkstring

    For kind: lipa: the till's mobile network. Normally leave blank; it is resolved from the till registry.

  • utilityCodestring

    Required for kind: bill. See GET /v1/spend/billers.

  • utilityRefstring

    Required for kind: bill: the meter, control or account number.

Responses

  • 200A quote, including the resolved merchant or biller name and the total.Show fields
    • quoteIdstring | null

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

    • expiresAtstring | null

      Null when quoteId is null.

    • expiresInSecondsinteger | null
    • kindstring

      lipabill

    • targetobject

      { payNumber, network } for lipa, { utilityCode, utilityRef } for bill.

    • payNumberstring
    • networkstring | null
    • utilityCodestring
    • utilityRefstring
    • recipientNamestring | null

      The merchant or bill account holder. Null means unconfirmed.

    • nameUnavailableReasonstring

      Present only when recipientName is null.

    • principalTzsinteger

      What the till or biller receives.

    • burnAmountTzsinteger

      The total debited: principal plus every fee.

    • feesobject
    • selcomFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • platformFeeTzsinteger

      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
    • 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/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"
}'
Response · 200
{
  "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": "…"
}
post/api/v1/spend

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

  • quoteIdstringrequired

    From POST /v1/spend/quote.

  • kindstringrequired

    lipabill

  • amountTzsintegerrequired

    The quoted principal.

  • payNumberstring

    Required for kind: lipa: the quoted Lipa Namba.

  • utilityCodestring

    Required for kind: bill, as quoted.

  • utilityRefstring

    Required for kind: bill, as quoted.

  • networkstring

    A till's mobile network, when till_network_required asked for it.

  • allowDuplicatebooleandefault false

    Deliberately repeat an identical payment inside the duplicate window.

Responses

  • 201Payment accepted.Show fields
    • idstring (uuid)
    • statusstring

      burned

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

    • referencestring | null

      Persist this; it is what the biller recognises.

    • kindstring

      lipabill

    • targetobject
    • payNumberstring
    • networkstring | null
    • utilityCodestring
    • utilityRefstring
    • recipientNamestring | null
    • principalTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • burnAmountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • feesobject
    • selcomFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • platformFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • nedaFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • totalFeeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • utilityTokenstring

      Present when settlement was already seen. For LUKU the token is the product.

    • utilityUnitsstring
    • 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: request a new quote. duplicate_spend: an identical payment was just made (existing describes it); show it, or resend with allowDuplicate: true.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 502The payment did not complete. payoutStatus: reverted: refused and the balance restored; error: till_network_required means retry with network. payoutStatus: reconcile_required: unconfirmed; do NOT retry, an operator resolves it.object
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
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
}'
Response · 201
{
  "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": "…"
}
get/api/v1/spend/{id}

Read a spend and its current status

Parameters

  • idstring (uuid)pathrequired

Responses

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

      The burn. Whether the biller was paid is payoutStatus.

      requestedapprovedrequires_second_approvalrejectedburn_submittedburnedfailed

    • 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
    • referencestring | null

      The reference the biller recognises.

    • kindstring | null

      lipabillnull

    • targetobject
    • payNumberstring | null
    • networkstring | null
    • utilityCodestring | null
    • utilityRefstring | null
    • recipientNamestring | null
    • principalTzsinteger | null
    • burnAmountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • utilityTokenstring | null

      For token billers (e.g. LUKU) the token IS the product. Show it to the customer.

    • utilityUnitsstring | null
    • utilityReceiptstring | null
    • selcomReceiptstring | null
    • actualChargesTzsinteger | null
    • 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 spend 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/spend/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "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"
}
get/api/v1/spend/billers

The 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 fields
    • enabledboolean

      Whether spend rails are switched on for you.

    • livemodeboolean

      Present (false) for test keys.

    • categoriesobject[]
    • keystring
    • labelstring
    • billersobject[]
    • codestring

      The utilityCode to quote with.

    • referenceLabelstring
    • referenceKindstring
    • referenceMinLengthinteger | null
    • referenceMaxLengthinteger | null
    • feeFreeUnder20kboolean

      True only if the total charge is zero, which is effectively never.

    • selcomFeeFreeUnder20kboolean

      The provider leg alone is free under 20,000 TZS. A service fee still applies.

    • feeNotestring | null
    • notestring
  • 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 "https://www.ntzs.co.tz/api/v1/spend/billers" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "enabled": true,
  "categories": [
    {
      "key": "…",
      "label": "…",
      "billers": [
        {}
      ]
    }
  ],
  "note": "…"
}
post/api/v1/merchant/pay

Pay 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-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

  • payerUserIdstring (uuid)required

    Your user; you are vouching they are signed in.

  • handlestringrequired

    The merchant's checkout handle.

  • amountTzsintegerrequired

    Whole shillings, at least 100.

  • linkIdstring (uuid)

    Optional. Validated against the merchant's payment link; must equal a fixed link's amount.

  • payerNamestring

    Optional. Shown in the merchant's sales list.

  • payerPhonestring

    Tanzanian mobile number. 2557XXXXXXXX, 07XXXXXXXX and +2557XXXXXXXX are all accepted.

  • externalReferencestring

    Optional. Your own order id, opaque to nTZS. Echoed on this response, on every GET /api/v1/biashara/collections row and on the deposit.completed webhook. Not unique: a retried payment for one order is a second sale with the same reference.

Responses

  • 201Payment executed, synchronous and final.Show fields
    • idstring (uuid)
    • collectionIdstring (uuid)
    • transferIdstring (uuid)
    • statusstring

      completed

    • paymentMethodstring

      ntzs_balance

    • txHashstring
    • amountTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • merchantobject
    • handlestring
    • businessNamestring
    • payerUserIdstring (uuid)
    • externalReferencestring | null

      Echoed verbatim; null when 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-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.SentenceError
  • 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/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"
}'
Response · 201
{
  "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
}