@zkyc/kyc-js

Browser SDK for integrating zKYC identity verification flows into your web application.

Installation

npm install @zkyc/kyc-js
# or
yarn add @zkyc/kyc-js
# or
bun add @zkyc/kyc-js

Quick Start

import { ZKYCProcess } from '@zkyc/kyc-js'

await ZKYCProcess({
  apiKey: 'test_your_api_key',
  userId: 'user_123',
  successUrl: 'https://yourapp.com/kyc/success',
  failureUrl: 'https://yourapp.com/kyc/failure',
})

API Reference

ZKYCProcess(config)

Generates a secure KYC token and launches the identity verification flow.

Returns Promise<{ url: string }>.

Config Options

| Field | Type | Required | Description | |---|---|---|---| | apiKey | string | Yes | Your zKYC API key (test_ or prod_ prefix) | | userId | string | Yes | The user's ID on your platform | | callbackUrl | string | Conditional | Single URL for all outcomes. Mutually exclusive with failureUrl/successUrl. | | failureUrl | string | Conditional | URL to redirect on KYC failure. Must be used together with successUrl. | | successUrl | string | Conditional | URL to redirect on KYC success. Must be used together with failureUrl. | | platform | string | No | Platform identifier. Defaults to "sdk". | | mode | "redirect" \| "popup" | No | Launch mode. Defaults to "redirect". |

You must provide either callbackUrl alone, or both failureUrl and successUrl together. Providing all three throws an error.

Usage Examples

Redirect mode (default)

The browser navigates to the KYC flow, then redirects to your success/failure URL when complete.

import { ZKYCProcess } from '@zkyc/kyc-js'

document.getElementById('kyc-btn').addEventListener('click', async () => {
  try {
    await ZKYCProcess({
      apiKey: 'test_your_api_key',
      userId: 'user_abc123',
      successUrl: 'https://yourapp.com/kyc/success',
      failureUrl: 'https://yourapp.com/kyc/failure',
    })
    // Note: browser has navigated away at this point
  } catch (err) {
    console.error('KYC failed to start:', err.message)
  }
})

Popup mode

The KYC flow opens in a popup window, keeping your application in the background.

await ZKYCProcess({
  apiKey: 'test_your_api_key',
  userId: 'user_abc123',
  successUrl: 'https://yourapp.com/kyc/success',
  failureUrl: 'https://yourapp.com/kyc/failure',
  mode: 'popup',
})

Single callback URL

Use one URL to handle all outcomes.

await ZKYCProcess({
  apiKey: 'test_your_api_key',
  userId: 'user_abc123',
  callbackUrl: 'https://yourapp.com/kyc/callback',
})

React example

import { useState } from 'react'
import { ZKYCProcess } from '@zkyc/kyc-js'

function KYCButton({ apiKey, userId }: { apiKey: string; userId: string }) {
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState<string | null>(null)

  const handleClick = async () => {
    setLoading(true)
    setError(null)
    try {
      await ZKYCProcess({
        apiKey,
        userId,
        successUrl: `${window.location.origin}/kyc/success`,
        failureUrl: `${window.location.origin}/kyc/failure`,
      })
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error')
    } finally {
      setLoading(false)
    }
  }

  return (
    <>
      <button onClick={handleClick} disabled={loading}>
        {loading ? 'Starting...' : 'Verify Identity'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </>
  )
}

Notes

Browser only — This SDK requires the window object and throws if called in a server-side environment (SSR, Node.js, Bun, etc.).

If you use SSR (Next.js, Remix, etc.), call ZKYCProcess only from client-side event handlers or inside a useEffect.

License

MIT