Skip to content

Products

Biashara: a merchant product inside your app

Turn your customers into merchants: they collect payments by QR or link, watch their sales, control how much auto-settles to mobile money, cash out and, where a lender is attached, draw working capital against their sales history. All under your UI, your brand. You hold no wallet, no key and no float.

Access: Biashara requires the biashara capability and approved KYB, because it issues merchant wallets and moves merchant money. Ask us to enable it. A key without it gets 403.
Tenant isolation: your key only ever sees merchants it created. Another partner's merchant id returns 404, never 403; we don't confirm that it exists.
Lender-controlled settlement: when a lender funds the merchant, the merchant's own settlement controls go read-only. Surface that in your UI rather than letting the PATCH fail.
No sandbox, deliberately. A ntzs_test_ key gets 501 here. The merchant rails run against live payment providers, so the meaningful test is a real one: activate a merchant, create a link, push a small payment (1,000 TZS) to a phone you control, and watch it land in /collections, /stats and /wallet, then withdraw it back out. Everything else on this page does have a full sandbox, so build those against a test key while your Biashara account is being set up.
1 · Activate a customer as a merchant
// Provision the user first (Step 3), then:
const res = await fetch('https://www.ntzs.co.tz/api/v1/biashara/accounts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId:          user.id,          // from POST /api/v1/users
    email:           'shop@example.co.tz',
    businessName:    'Duka la Asha',
    settlementPhone: '0744277496',
  }),
})
const merchant = await res.json()
// {
//   merchantId:    "…",           // send as x-merchant-id on every call below
//   handle:        "dukalaasha",  // PUBLIC payment identity; read it back!
//   walletAddress: "0x…",
// }

// Idempotent per userId/email WITHIN YOUR OWN BOOK: calling again returns the
// same merchant with alreadyExists: true.
//
// handle is globally unique across the platform. If yours is taken we assign
// the next free variant and return it, so activation never fails on a
// collision. Never assume the handle you asked for.
2 · Every other call carries the merchant id
const headers = {
  'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
  'x-merchant-id': merchant.merchantId,
  'Content-Type': 'application/json',
}

// Collect
POST   /api/v1/biashara/links      { amountTzs, label }   // payment link + QR
GET    /api/v1/biashara/links
DELETE /api/v1/biashara/links

// Show them their business
GET /api/v1/biashara/stats         // sales today / this month
GET /api/v1/biashara/collections   // history, ?limit= up to 50, cursor-paginated
GET /api/v1/biashara/wallet        // balance

// Settlement + cash-out
GET   /api/v1/biashara/settlement  // auto-settle % + payout phone
PATCH /api/v1/biashara/settlement
POST  /api/v1/biashara/withdraw    { amountTzs: 10000 }   // NET received, min 5,000
POST  /api/v1/biashara/transfer-to-wallet { amountTzs, idempotencyKey } // to the owner's own wallet, no fee

// Working capital
GET  /api/v1/biashara/financing/status     // facility, drawn, available
POST /api/v1/biashara/financing/withdraw   // draw against it