API reference
Ramp
Wallet-less settlement: USDC to and from mobile money.
/api/v1/ramp/quoteLock 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
directionstringrequiredofframponrampusdcAmountnumberOff-ramp only, instead of
tzsAmount: the USDC to spend.tzsAmountintegerOn-ramp: TZS the payer pays. Off-ramp (instead of
usdcAmount): the net TZS the recipient receives.destinationobjectOff-ramp only: where the TZS goes. Omit (or
kind: wallet) for a mobile money payout; the phone is given at execution.lipaneedspayNumber;billneedsutilityCode+utilityRef. The destination is bound to the quote.kindstringdefault "wallet"walletlipabillpayNumberstringlipa: the merchant Lipa Namba, 4–12 digits.networkstringlipa: the till's mobile network, optional.utilityCodestringbill: see GET /v1/spend/billers.utilityRefstringbill: the meter, control or account number.
Responses
200A quote valid for 60s.Show fieldsHide
quoteIdstring (uuid)directionstringofframponrampusdcAmountnumbertzsAmountintegerWhole Tanzanian shillings. Never a decimal.
feeTzsintegerWhole Tanzanian shillings. Never a decimal.
rateUsdTzsnumberTZS per 1 USDC.
destinationobjectPresent for lipa/bill destinations.
recipientNamestring | nullPresent 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-Afterand 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
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
}'{
"quoteId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"direction": "offramp",
"usdcAmount": 10000,
"tzsAmount": 10000,
"feeTzs": 10000,
"rateUsdTzs": 10000,
"expiresAt": "2026-10-27T09:00:00Z"
}/api/v1/ramp/offrampUSDC 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-KeystringheaderOptional, 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
quoteIdstringrequiredFrom POST /v1/ramp/quote with
direction: offramp.phoneNumberstringRequired when the quote has a wallet (mobile money) destination; ignored for lipa/bill.
Responses
201Settled:
status: completed.Show fieldsHidesettlementIdstring (uuid)statusstringcompletedpaying_outrevertedfailedusdcAmountnumbertzsAmountintegerWhole Tanzanian shillings. Never a decimal.
recipientPhonestringWallet destinations.
destinationobjectLipa/bill destinations.
recipientNamestring | nullLipa/bill destinations.
errorstringPresent on
revertedandfailed.
- 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 witherror).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-Afterand 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 - 502
status: reverted: the payout failed and the funds were returned. Same body as 201, witherror.object - 503A rail or dependency is unavailable. Nothing moved; retry with backoff.CodeError
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"
}'{
"settlementId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "completed",
"usdcAmount": 10000,
"tzsAmount": 10000,
"recipientPhone": "255712345678",
"destination": {},
"recipientName": "…"
}/api/v1/ramp/onrampMobile 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-KeystringheaderOptional, 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
quoteIdstringrequiredFrom POST /v1/ramp/quote with
direction: onramp.phoneNumberstringrequiredThe payer, who receives the mobile money prompt.
destinationAddressstringOptional. A valid EVM address to receive the USDC; screened before anything is collected. Defaults to your settlement float.
Responses
202Accepted and in flight.Show fieldsHide
settlementIdstring (uuid)statusstringmintingtzsAmountintegerWhole Tanzanian shillings. Never a decimal.
usdcAmountnumberdestinationAddressstring | nullmessagestring
- 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-Afterand 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
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"
}'{
"settlementId": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
"status": "minting",
"tzsAmount": 10000,
"usdcAmount": 10000,
"destinationAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
"message": "…"
}/api/v1/ramp/{id}Read one settlement
Parameters
idstring (uuid)pathrequired
Responses
200The settlement.Show fieldsHide
settlementIdstring (uuid)directionstringofframponrampstatusstringquotedprocessingswappingpaying_outmintingcompletedfailedrevertedusdcAmountnumbertzsAmountintegerWhole Tanzanian shillings. Never a decimal.
feeTzsintegerWhole Tanzanian shillings. Never a decimal.
rateUsdTzsnumberTZS per 1 USDC.
recipientPhonestring | nulldestinationAddressstring | nullswapInTxHashstring | nullswapOutTxHashstring | nullpspReferencestring | nullerrorstring | nullcreatedAtstring (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-Afterand 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
curl "https://www.ntzs.co.tz/api/v1/ramp/14e17d04-ec7f-4d99-91a3-dfbaca19fba1" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"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"
}Parameters
limitintegerqueryoffsetintegerquery
Responses
200Settlements.Show fieldsHide
settlementsRampSettlement[]settlementIdstring (uuid)directionstringofframponrampstatusstringquotedprocessingswappingpaying_outmintingcompletedfailedrevertedusdcAmountnumbertzsAmountintegerWhole Tanzanian shillings. Never a decimal.
feeTzsintegerWhole Tanzanian shillings. Never a decimal.
rateUsdTzsnumberTZS per 1 USDC.
recipientPhonestring | nulldestinationAddressstring | nullswapInTxHashstring | nullswapOutTxHashstring | nullpspReferencestring | nullerrorstring | nullcreatedAtstring (date-time)updatedAtstring (date-time)limitintegeroffsetinteger
- 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 - 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
curl "https://www.ntzs.co.tz/api/v1/ramp/settlements" \
-H "Authorization: Bearer $NTZS_API_KEY"{
"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
}/api/v1/ramp/balanceYour 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-Afterand 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
curl "https://www.ntzs.co.tz/api/v1/ramp/balance" \
-H "Authorization: Bearer $NTZS_API_KEY"