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.