Integrating KYC/KYB Verification via API

Nyota ID enables FinTechs, SACCOs, banks, and online marketplaces to automate customer identity verification (KYC) and corporate business onboarding (KYB) in seconds.

This guide explains how the verification session lifecycle works under the hood, how wallet holds operate, and how to launch your first verification check using either our Hosted Web Flow or Client SDKs.

1. How Verification Sessions Work Under the Hood

To guarantee server-side key security and prevent client-side tampering, Nyota ID enforces a strict 3-Step Verification Lifecycle:

TEXT

1. SESSION INITIALIZATION (Your Backend Server -> Nyota API)
    Backend calls POST /v1/verify/sessions with x-nyota-api-key: ny_live_...
    -> Nyota places a temporary wallet hold (KES 150 for KYC / KES 500 for KYB).
    -> Emits: { sessionId: "ses_xxx", sessionUrl: "https://verify.nyotaimara.com/session/ses_xxx" }
                         │
                         ▼
 2. END-USER VERIFICATION FLOW (Browser / Mobile App)
    User opens sessionUrl (or embedded @nyota/verify-web-sdk modal):
    - Captures National ID / Passport photos.
    - Executes 3D passive facial liveness check.
                         │
                         ▼
 3. ASYNCHRONOUS WEBHOOK SETTLEMENT (Nyota -> Your Backend Server)
    Nyota emits cryptographically signed event: verification.completed
    - If Verified (Approved) -> Wallet hold committed (Permanent Debit).
    - If Declined / Abandoned -> Wallet hold released in full (Cost: KES 0.00).

2. Choosing Your Integration Path

You can embed Nyota ID into your customer onboarding flow using two flexible approaches:

Integration Path	Implementation Effort	Best Used For
Hosted Web Flow	< 15 Minutes (No frontend SDK required)	Web apps, WhatsApp onboarding bots, email verification links
Web / React Native SDKs	< 1 Hour (`@nyota/verify-web-sdk`)	In-app modal verification, seamless native mobile apps

3. Step-by-Step: Initializing a Verification Session

Read Developer Docs at https://docs.nyotaimara.com/docs/3-nyota-id/sessions

4. Common Pitfalls & How to Troubleshoot

Pitfall A: "Session creation returns 402 Payment Required."

The Cause: Your workspace Nyota Wallet has insufficient balance to place the initial reservation hold (KES 150 for KYC or KES 500 for KYB).
The Resolution: Pre-fund your Nyota Wallet at accounts.nyotaimara.com/billing via M-Pesa STK push or Card.

Pitfall B: "My API request returns 401 Unauthorized: Invalid Key."

The Cause: Missing or invalid x-nyota-api-key header, or attempting to call production endpoints using a test key (ny_test_...).
The Resolution: Ensure your key matches the environment and pass it in the x-nyota-api-key request header.

Pitfall C: "Security risk: Relying on client-side UI callbacks to approve accounts."

The Cause: Client-side JavaScript redirects can be intercepted or faked by malicious users.
The Resolution: Always verify the cryptographic HMAC signature (x-nyota-signature) on your server-side webhook before updating customer account states in your database.