Skip to content

Wallets & identity

Create users (per-user wallets)

Per-user wallets only: skip this on the platform wallet. Register a user and provision an on-chain wallet in a single call. Wallets are deterministically derived from your partner seed, so no blockchain transaction is required. Requires the 'wallets' capability.

Issuing end-user wallets is a granted capability. Every account gets a treasury wallet at signup, plus sub-wallets. Those need no grant. Issuing wallets to your own end users is different: each one is an identity the platform carries in its KYC and regulatory reporting perimeter, so it is enabled per partner rather than by default. Without the wallets capability this endpoint answers 403. Request it from the dashboard (Capabilities → Wallets); collections, disbursements, transfers and treasury are available meanwhile. Your test key mirrors your live grant, so the sandbox answers exactly as production will.
Store the id field. This is the nTZS user ID you will pass as userId in all subsequent requests (deposits, transfers, withdrawals). It is different from your own externalId.
Not every integration creates users. This endpoint needs the Wallets capability, which is granted per-partner (end-user wallets are a custody-bearing product). If you only pay bills or disburse from a balance you top up (no per-user wallets), you do not create users at all: fund your partner Treasury and pass fromTreasury: true to Spend and Disbursements instead of a userId.
Every wallet is backed by a verified identity (Bank of Tanzania requirement). By default, the user is created and you receive a 202 with kyc_attestation_required: you verify the customer in your own onboarding and report it via Identity (KYC), which issues the wallet. Platform-run instant NIDA verification at create-user (a 201) is a per-partner enablement; contact NEDA Labs if your integration needs it.
Idempotent: Calling with the same externalId returns the existing user. Safe to call on every login.
Gas pre-funded: New wallets are automatically topped up with a small ETH amount for gas. You do not need to fund wallets yourself.
POST /api/v1/users (request)
const res = await fetch('https://www.ntzs.co.tz/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalId: 'your-internal-user-id',  // required; your own system's user ID
    email: 'user@example.com',            // required
    name: 'Jane Doe',                     // optional
    country: 'TZ',                        // optional, default TZ; non-TZ signups omit NIDA
    nidaNumber: '19990102614010000120',   // required for TZ; user's 20-digit NIDA
    phone: '255712345678',                // required for TZ; user's OWN mobile money line
  }),
})
201: verified instantly, wallet issued
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "externalId": "your-internal-user-id",
  "email": "user@example.com",
  "name": "Jane Doe",
  "phone": "255712345678",
  "kycStatus": "approved",
  "walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C",
  "balance": 0
}
202: identity needs verification first
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "externalId": "your-internal-user-id",
  "kycStatus": "pending_review",
  "code": "kyc_pending_review",
  "nextStep": "kyc_session",
  "walletAddress": null
}
// The user exists but has NO wallet yet. Don't make them wait:
// open a document-capture session (next section) so they can
// verify in ~2 minutes, then re-call POST /api/v1/users.