Skip to content

API reference

Ramp

Wallet-less settlement: USDC to and from mobile money.

post/api/v1/ramp/quote

Lock a settlement rate for 60 seconds

Off-ramp: send exactly one of usdcAmount (USDC to spend) or tzsAmount (the net TZS the recipient must receive, at least 5,000). On-ramp: send tzsAmount (TZS to collect, at least 5,000). The quote is single-use and expires after 60 seconds.

Request body

  • directionstringrequired

    offramponramp

  • usdcAmountnumber

    Off-ramp only, instead of tzsAmount: the USDC to spend.

  • tzsAmountinteger

    On-ramp: TZS the payer pays. Off-ramp (instead of usdcAmount): the net TZS the recipient receives.

  • destinationobject

    Off-ramp only: where the TZS goes. Omit (or kind: wallet) for a mobile money payout; the phone is given at execution. lipa needs payNumber; bill needs utilityCode + utilityRef. The destination is bound to the quote.

  • kindstringdefault "wallet"

    walletlipabill

  • payNumberstring

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

  • networkstring

    lipa: the till's mobile network, optional.

  • utilityCodestring

    bill: see GET /v1/spend/billers.

  • utilityRefstring

    bill: the meter, control or account number.

Responses

  • 200A quote valid for 60s.Show fields
    • quoteIdstring (uuid)
    • directionstring

      offramponramp

    • usdcAmountnumber
    • tzsAmountinteger

      Whole Tanzanian shillings. Never a decimal.

    • feeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • rateUsdTzsnumber

      TZS per 1 USDC.

    • destinationobject

      Present for lipa/bill destinations.

    • recipientNamestring | null

      Present for lipa/bill destinations: show it before executing.

    • expiresAtstring (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
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/ramp/quote" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "direction": "offramp",
  "tzsAmount": 50000
}'
Response · 200
{
  "quoteId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "direction": "offramp",
  "usdcAmount": 10000,
  "tzsAmount": 10000,
  "feeTzs": 10000,
  "rateUsdTzs": 10000,
  "expiresAt": "2026-10-27T09:00:00Z"
}
post/api/v1/ramp/offramp

USDC to mobile money

Consumes an off-ramp quote: swaps your USDC float, burns the nTZS and pays the destination. A 202 is success-in-flight, not a failure. Track it with GET /v1/ramp/{id} or the settlement webhooks.

Parameters

  • Idempotency-Keystringheader

    Optional, replaying. A unique key per logical operation. Once a request with this key has answered 2xx, a retry with the same key returns that stored response instead of settling twice. While the first request is still running, a retry answers 409. A non-2xx outcome releases the key, so a corrected retry may reuse it.

Request body

  • quoteIdstringrequired

    From POST /v1/ramp/quote with direction: offramp.

  • phoneNumberstring

    Required when the quote has a wallet (mobile money) destination; ignored for lipa/bill.

Responses

  • 201Settled: status: completed.Show fields
    • settlementIdstring (uuid)
    • statusstring

      completedpaying_outrevertedfailed

    • usdcAmountnumber
    • tzsAmountinteger

      Whole Tanzanian shillings. Never a decimal.

    • recipientPhonestring

      Wallet destinations.

    • destinationobject

      Lipa/bill destinations.

    • recipientNamestring | null

      Lipa/bill destinations.

    • errorstring

      Present on reverted and failed.

  • 202Accepted and in flight: status: paying_out. Same body as 201.object
  • 400Invalid request or a limit block, or the settlement failed (status: failed, same body as 201 with error).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
  • 409The quote was not found, already used, expired, or is not an off-ramp quote. Request a new one.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 502status: reverted: the payout failed and the funds were returned. Same body as 201, with error.object
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/ramp/offramp" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": "…",
  "phoneNumber": "255712345678"
}'
Response · 201
{
  "settlementId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "status": "completed",
  "usdcAmount": 10000,
  "tzsAmount": 10000,
  "recipientPhone": "255712345678",
  "destination": {},
  "recipientName": "…"
}
post/api/v1/ramp/onramp

Mobile money to USDC

Consumes an on-ramp quote and prompts the payer's phone. Once the payment is confirmed and minted, USDC is delivered to destinationAddress, or to your settlement float when it is omitted.

Parameters

  • Idempotency-Keystringheader

    Optional, replaying. A unique key per logical operation. Once a request with this key has answered 2xx, a retry with the same key returns that stored response instead of settling twice. While the first request is still running, a retry answers 409. A non-2xx outcome releases the key, so a corrected retry may reuse it.

Request body

  • quoteIdstringrequired

    From POST /v1/ramp/quote with direction: onramp.

  • phoneNumberstringrequired

    The payer, who receives the mobile money prompt.

  • destinationAddressstring

    Optional. A valid EVM address to receive the USDC; screened before anything is collected. Defaults to your settlement float.

Responses

  • 202Accepted and in flight.Show fields
    • settlementIdstring (uuid)
    • statusstring

      minting

    • tzsAmountinteger

      Whole Tanzanian shillings. Never a decimal.

    • usdcAmountnumber
    • destinationAddressstring | 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
  • 409The quote was not found, already used, expired, or is not an on-ramp quote. Request a new one.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 502The mobile money prompt could not be initiated.object
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl -X POST "https://www.ntzs.co.tz/api/v1/ramp/onramp" \
  -H "Authorization: Bearer $NTZS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": "…",
  "phoneNumber": "255712345678"
}'
Response · 202
{
  "settlementId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "status": "minting",
  "tzsAmount": 10000,
  "usdcAmount": 10000,
  "destinationAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
  "message": "…"
}
get/api/v1/ramp/{id}

Read one settlement

Parameters

  • idstring (uuid)pathrequired

Responses

  • 200The settlement.Show fields
    • settlementIdstring (uuid)
    • directionstring

      offramponramp

    • statusstring

      quotedprocessingswappingpaying_outmintingcompletedfailedreverted

    • usdcAmountnumber
    • tzsAmountinteger

      Whole Tanzanian shillings. Never a decimal.

    • feeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • rateUsdTzsnumber

      TZS per 1 USDC.

    • recipientPhonestring | null
    • destinationAddressstring | null
    • swapInTxHashstring | null
    • swapOutTxHashstring | null
    • pspReferencestring | null
    • errorstring | null
    • createdAtstring (date-time)
    • updatedAtstring (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 settlement under your partner account.CodeError
  • 429Rate limited. Respect Retry-After and back off exponentially.CodeError
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl "https://www.ntzs.co.tz/api/v1/ramp/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "settlementId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "direction": "offramp",
  "status": "quoted",
  "usdcAmount": 10000,
  "tzsAmount": 10000,
  "feeTzs": 10000,
  "rateUsdTzs": 10000,
  "recipientPhone": "255712345678",
  "destinationAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
  "swapInTxHash": "0x5b1c…e2a9",
  "swapOutTxHash": "0x5b1c…e2a9",
  "pspReference": "…",
  "error": "…",
  "createdAt": "2026-10-27T09:00:00Z",
  "updatedAt": "2026-10-27T09:00:00Z"
}
get/api/v1/ramp/settlements

List settlements

Newest first.

Parameters

  • limitintegerquery
  • offsetintegerquery

Responses

  • 200Settlements.Show fields
    • settlementsRampSettlement[]
    • settlementIdstring (uuid)
    • directionstring

      offramponramp

    • statusstring

      quotedprocessingswappingpaying_outmintingcompletedfailedreverted

    • usdcAmountnumber
    • tzsAmountinteger

      Whole Tanzanian shillings. Never a decimal.

    • feeTzsinteger

      Whole Tanzanian shillings. Never a decimal.

    • rateUsdTzsnumber

      TZS per 1 USDC.

    • recipientPhonestring | null
    • destinationAddressstring | null
    • swapInTxHashstring | null
    • swapOutTxHashstring | null
    • pspReferencestring | null
    • errorstring | null
    • createdAtstring (date-time)
    • updatedAtstring (date-time)
    • limitinteger
    • offsetinteger
  • 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
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl "https://www.ntzs.co.tz/api/v1/ramp/settlements" \
  -H "Authorization: Bearer $NTZS_API_KEY"
Response · 200
{
  "settlements": [
    {
      "settlementId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
      "direction": "offramp",
      "status": "quoted",
      "usdcAmount": 10000,
      "tzsAmount": 10000,
      "feeTzs": 10000,
      "rateUsdTzs": 10000,
      "recipientPhone": "255712345678",
      "destinationAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
      "swapInTxHash": "0x5b1c…e2a9",
      "swapOutTxHash": "0x5b1c…e2a9",
      "pspReference": "…",
      "error": "…",
      "createdAt": "2026-10-27T09:00:00Z",
      "updatedAt": "2026-10-27T09:00:00Z"
    }
  ],
  "limit": 20,
  "offset": 1
}
get/api/v1/ramp/balance

Your USDC settlement float

Responses

  • 200The float.object
  • 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
  • 501Test keys get not_available_in_test_mode: this endpoint is not simulated in the sandbox. Use a live key.CodeError
  • 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
Request
curl "https://www.ntzs.co.tz/api/v1/ramp/balance" \
  -H "Authorization: Bearer $NTZS_API_KEY"