Products
Ramp: wallet-less settlement
Convert USDC ⇄ mobile money (TZS) over the API with no per-end-user wallets, or pay a merchant Lipa Namba or bill straight from USDC. You keep a USDC float with us; off-ramps debit it, on-ramps deliver USDC to you. nTZS is an internal rail you never touch.
Track:
GET /api/v1/ramp/[id] for one settlement, GET /api/v1/ramp/settlements to list. You also receive ramp.settlement.completed / ramp.settlement.failed webhooks.GET /api/v1/ramp/balance: your USDC settlement float
curl https://www.ntzs.co.tz/api/v1/ramp/balance \
-H "Authorization: Bearer ntzs_live_xxxxxxxxxxxx"
// { settlementAddress: "0x…", chain: "base",
// token: { symbol: "USDC", decimals: 6 }, usdcBalance: "2500.0",
// ntzsBalance: "0" }
//
// A non-zero ntzsBalance is value a REVERTED off-ramp returned to you;
// it is consumed automatically by your next off-ramp before any USDC is
// debited. No value is ever lost to a failed payout.POST /api/v1/ramp/quote: lock a rate (60s)
// Off-ramp: pass tzsAmount (the EXACT net the recipient receives,
// recommended; your users think in shillings) OR usdcAmount. Exactly one.
// On-ramp: pass tzsAmount (what the payer pays).
fetch('https://www.ntzs.co.tz/api/v1/ramp/quote', {
method: 'POST',
headers: { Authorization: 'Bearer ntzs_live_…', 'Content-Type': 'application/json' },
body: JSON.stringify({ direction: 'offramp', tzsAmount: 50000 }),
})
// { quoteId, usdcAmount: 19.459614, // what your float will be debited
// tzsAmount: 50000, // the recipient receives EXACTLY this
// feeTzs: 1207, rateUsdTzs: 2631.45, expiresAt }POST /api/v1/ramp/offramp: USDC → mobile money
fetch('https://www.ntzs.co.tz/api/v1/ramp/offramp', {
method: 'POST',
headers: { Authorization: 'Bearer ntzs_live_…', 'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify({ quoteId, phoneNumber: '0744000000' }),
})
// Answers in ~10 seconds with a DEFINITIVE state:
// 201 { settlementId, status: "completed" }: settled inline
// 202 { settlementId, status: "paying_out" }: money captured, payout
// dispatched; completion arrives on the ramp.settlement.completed
// webhook and GET /api/v1/ramp/:id. A 202 is success-in-flight;
// NEVER re-execute on it.
//
// If a payout fails definitively the settlement REVERTS: full value back
// to your settlementAddress (as nTZS; see ntzsBalance above), webhook
// ramp.settlement.failed carries returnedAsNtzsTo. Re-quote + execute
// and the retry completes on the recovered value.Off-ramp straight to a merchant or bill: USDC → Lipa / bill
// Pass a destination on the QUOTE. It's priced on the Selcom tariff and
// returns the merchant/biller's registered name to show before you confirm.
const q = await fetch('.../api/v1/ramp/quote', { method: 'POST', headers,
body: JSON.stringify({ direction: 'offramp', usdcAmount: 10,
destination: { kind: 'lipa', payNumber: '61115582' } }) }).then(r => r.json())
// { quoteId, tzsAmount, feeTzs, recipientName: 'ENZI COFFEE COMPANY LIMITED', … }
// bill example: destination: { kind: 'bill', utilityCode: 'LUKU', utilityRef: '<meter>' }
await fetch('.../api/v1/ramp/offramp', { method: 'POST', headers,
body: JSON.stringify({ quoteId: q.quoteId }) }) // no phoneNumber for lipa/bill
// 201/202 { settlementId, status, destination, recipientName }POST /api/v1/ramp/onramp: mobile money → USDC
// Prompts the payer's phone; delivers USDC to destinationAddress once paid.
fetch('https://www.ntzs.co.tz/api/v1/ramp/onramp', {
method: 'POST',
headers: { Authorization: 'Bearer ntzs_live_…', 'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify({ quoteId, phoneNumber: '0744000000', destinationAddress: '0x…' }),
})
// 202 { settlementId, status: "minting" }