Skip to content

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.

Access: Ramp requires the ramp capability + approved KYB. Enable it from your dashboard.
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" }