Skip to content

Move money

Transfers

Move nTZS or USDC between platform users or to any external wallet address. Settlement is on-chain and synchronous: the API responds only after the transaction is confirmed.

toUserId vs toAddress: Provide exactly one. toUserId sends to a platform user's wallet. toAddress sends to any Ethereum-compatible address on Base. Both fields cannot be set at the same time.
Platform fee: Configure your fee percentage and treasury wallet address in the dashboard. The fee is deducted from the sender and sent to your treasury in the same atomic operation.
Requirements: The sender must belong to your platform, their wallet must be provisioned, and they must have sufficient balance. For user-to-user transfers, the recipient must also belong to your platform. Gas is auto-managed: if the sender wallet is low on ETH, the relayer tops it up before sending.
POST /api/v1/transfers (user to user)
const res = await fetch('https://www.ntzs.co.tz/api/v1/transfers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fromUserId: 'uuid-of-sender',
    toUserId:   'uuid-of-recipient',   // nTZS user on your platform
    amountTzs:  5000,
    metadata: { orderId: 'ord_123', note: 'Payment for order' }, // optional
  }),
})
const transfer = await res.json()
// {
//   id: "uuid...",
//   status: "completed",
//   txHash: "0xabc...",
//   amountTzs: 5000,
//   recipientAmountTzs: 4975,  // after platform fee
//   feeAmountTzs: 25,
//   feeTxHash: "0xdef...",     // fee tx to your treasury, if fee > 0
//   toAddress: "0x531B..."     // resolved destination wallet
// }
POST /api/v1/transfers (send to external address)
// Send nTZS to ANY wallet address. No recipient user required.
// Use toAddress instead of toUserId.
const res = await fetch('https://www.ntzs.co.tz/api/v1/transfers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fromUserId: 'uuid-of-sender',
    toAddress:  '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18', // any valid EVM address
    amountTzs:  10000,
  }),
})
const transfer = await res.json()
// {
//   id: "uuid...",
//   status: "completed",
//   txHash: "0xabc...",
//   amountTzs: 10000,
//   recipientAmountTzs: 9950,
//   feeAmountTzs: 50,
//   toAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
// }
POST /api/v1/transfers (USDC transfer)
// Same endpoint: add token: 'USDC' and use the token-agnostic amount field.
// USDC uses 6 decimals, so fractional amounts are supported.
const res = await fetch('https://www.ntzs.co.tz/api/v1/transfers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fromUserId: 'uuid-of-sender',
    toAddress:  '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18',
    token:  'USDC',
    amount: 12.5,   // 12.5 USDC
  }),
})
const transfer = await res.json()
// {
//   id: "uuid...",
//   status: "completed",
//   txHash: "0xabc...",
//   token: "usdc",
//   amount: 12.5,
//   recipientAmount: 12.4375,   // after platform fee
//   feeAmount: 0.0625,
//   feeTxHash: "0xdef...",
//   toAddress: "0x742d35..."
//   // Legacy amountTzs / recipientAmountTzs / feeAmountTzs are omitted for non-nTZS tokens.
// }
POST /api/v1/merchant/pay: pay a Biashara merchant from wallet balance
// The second tender at merchant checkout: your signed-in user pays a
// Biashara merchant directly from their own nTZS balance, with no STK push,
// no waiting on mobile money. Same handle, linkId and amount rules as the
// hosted checkout; the sale lands in the merchant's sales list and stats
// exactly like a mobile-money sale, marked paymentMethod: 'ntzs_balance'.
const res = await fetch('https://www.ntzs.co.tz/api/v1/merchant/pay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),  // recommended: one key, one payment
  },
  body: JSON.stringify({
    payerUserId: user.id,        // YOUR user; you are vouching they are signed in
    handle:      'mamantilie',   // the merchant's checkout handle
    amountTzs:   25000,          // whole shillings, min 100; must match a fixed link's amount
    linkId:      'uuid-of-link', // optional, validated against the merchant's link
    payerName:   'Asha M.',      // optional, shown in the merchant's sales list
    externalReference: order.id, // optional, YOUR order id, ≤128 chars, opaque to us
  }),
})
const sale = await res.json()
// 201: settlement is synchronous; this response is final, no polling needed:
// {
//   id: "uuid...",              // the sale (collection) id
//   collectionId: "uuid...",
//   transferId: "uuid...",
//   status: "completed",
//   paymentMethod: "ntzs_balance",
//   txHash: "0xabc...",
//   amountTzs: 25000,
//   merchant: { handle: "mamantilie", businessName: "Mama Ntilie" },
//   externalReference: "order_8f3a…",  // echoed verbatim, null if you sent none
//   livemode: true
// }
// externalReference round-trips everywhere the sale shows up: this response,
// the merchant's GET /api/v1/biashara/collections rows, and (for the
// mobile-money tender, since POST /api/merchant/pay accepts the same field) the
// deposit.completed webhook. It is not unique: retrying a failed payment for
// the same order is a second sale with the same reference; order state is
// yours to own.
// The merchant receives the FULL amount. No fee is skimmed from a sale.
//
// Key errors: 400 insufficient_balance (details.available / .shortfall),
// 400 invalid_amount, 404 'Merchant not found or inactive',
// 404 'Payment link not found or inactive', 400 'Amount does not match link amount',
// 403 wallet_frozen, 409 in-flight/idempotency replay, 429 throttled.
//
// If your checkout screen polls GET /api/pay/status?id=…, pass the returned
// id; it answers { status: "success" } in the same shape as a mobile-money
// deposit id.
//
// Test mode: same endpoint, test key. The merchant and link are validated
// FOR REAL (a wrong handle fails now, not on go-live day); the payer's
// simulated balance is debited; the real merchant sees nothing.
//
// A balance sale is a transfer between two nTZS holders: nothing is minted,
// no deposit is created, supply does not change.