Skip to content

Wallets & identity

Identity verification (KYC)

Every wallet is backed by a verified identity. The standard flow: you verify the customer in your own onboarding (Tanzanian or not) and report the outcome to us here; the wallet is issued on your attestation. Instant NIDA-registry verification at create-user is a per-partner enablement.

TierWhat happensSpeed
ANIDA + phone pair verified against a bank-grade registry at create-userinstant
BThe phone's telco SIM registration (NIDA + fingerprints by law) corroborates; a contradiction outranksinstant
B′You verified the customer yourself and attest the outcome to us; the wallet is issued on that callinstant
COur compliance team reviews the collected evidence< 1 business day
One approval, not two. When create-user returns 202, the nextStep field tells you who resolves it. With a reliance agreement it is kyc_attestation: your own approval issues the wallet and returns the walletAddress in the same response, so a customer you have already verified never waits behind a second review. Without one it is compliance_review, and the kyc.updated webhook tells you when it clears.
Reliance is an agreement, not a setting: attesting a KYC outcome means you performed due diligence to our standard and can produce the underlying record on request. That is why every attestation carries reference, verifiedBy and verifiedAt. Talk to us to arrange it.
International documents: pass the document's country at create-user and the customer is created without a NIDA, then activated by your attestation. Passports, national IDs, driving licences, residence permits and voter IDs are all accepted.
Retro-KYC: users created before the KYC standard show kycStatus: "none". Attach an identity with POST /api/v1/users/:id/kyc (NIDA + phone, same outcomes as signup), or attest one you verified yourself.
Rehearse it on a test key. Test keys simulate this endpoint as if you already held the reliance grant, so you can build before the agreement is signed. Validation and error codes are the live ones. Magic values: reference: "NOT_GRANTED" returns 403 kyc_reliance_not_granted; an approval whose idNumber ends 13 returns 409 identity_mismatch, and one ending 09 returns 409 identity_already_registered. Live keys stay at 403 until compliance enables reliance.
POST /api/v1/users/:id/kyc/attestation
// You verified this customer yourself. Tell us, and the wallet
// is issued on this call; there is no second approval step.
// Requires a signed KYC reliance agreement with NEDA Labs.
const res = await fetch(
  'https://www.ntzs.co.tz/api/v1/users/14e17d04-ec7f-4d99-91a3-dfbaca19fba1/kyc/attestation',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ntzs_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      decision:   'approved',              // or 'rejected' (then notes is required)
      country:    'KE',                    // ISO-3166 alpha-2 of the document
      idType:     'PASSPORT',              // NATIONAL_ID | PASSPORT | DRIVERS_LICENSE
                                           // | RESIDENCE_PERMIT | VOTER_ID
      idNumber:   'A1234567',
      fullName:   'Jane Wanjiru Doe',      // as it appears on the document
      reference:  'YOURCO-KYC-88213',      // YOUR case id; we may ask for the file
      verifiedBy: 'compliance@yourco.com', // who made the decision
      verifiedAt: '2026-08-04T09:30:00Z',  // when (within the last 365 days)
      method:     'document_and_selfie',   // optional, free text
    }),
  }
)
200: approved, wallet issued
{
  "id": "14e17d04-ec7f-4d99-91a3-dfbaca19fba1",
  "externalId": "your-internal-user-id",
  "kycStatus": "approved",
  "caseId": "6f1e...c2a9",
  "walletAddress": "0x531B87EfdEBD19bfd05700DF6218d4786Cf2201C"
}

// Errors worth handling:
//   403 kyc_reliance_not_granted    no reliance agreement on your account
//   400 verified_at_stale           decision older than 365 days; re-verify
//   409 identity_mismatch           document number disagrees with the NIDA we hold
//   409 identity_already_registered that document already backs another of your users