Astra KYC SDK

A comprehensive KYC (Know Your Customer) SDK with web and mobile support, featuring face capture, document upload, and seamless device switching.

Features

• Face Capture: Live camera capture with web
• Document Upload: Support for CNIC and Passport documents
• Device Switching: QR code-based switching from web to mobile
• Session Management: Automatic session validation and expiry handling
• TypeScript Support: Full type definitions included
• React Integration: Ready-to-use React components

Installation

npm install astra-sdk-astra

Quick Start

Basic Usage (Modal flow)

import React, { useState } from "react";
import { VerificationSDK, KycModal } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";

const sdk = new VerificationSDK({ serverKey: "your-server-key" });

function App() {
  const [showModal, setShowModal] = useState(false);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const startKyc = async () => {
    setError(null);
    setLoading(true);
    try {
      await sdk.init({
        reference: "user123",
        email: "[email protected]",
        callback_url: "https://your-app.com/callback",
        redirect_url: "https://your-app.com/redirect",
        device_type: "WEB"
      });
      setShowModal(true);
    } catch (err: any) {
      setError(err?.message || "Failed to initialize KYC");
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={startKyc} disabled={loading}>
        {loading ? "Starting..." : "Start KYC"}
      </button>
      {error && <div style={{ color: "red" }}>{error}</div>}
      {showModal && (
        <KycModal
          sdk={sdk}
          onClose={() => setShowModal(false)}
        />
      )}
    </div>
  );
}

What users see in the modal:

• Face capture step (with QR to switch to mobile)
• Document step with CNIC/Passport selector; if an upload fails, an "Upload again" button appears so users can retry immediately
• Status step showing the verification outcome

Turnkey Flow (optional)

If you prefer an out-of-the-box flow with a start button, init form, terms screen, and modal managed for you:

import { KycFlow } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";

function App() {
  return (
    <KycFlow serverKey="your-server-key" startLabel="Start KYC" />
  );
}

Button → Init Form → Modal (previous structure)

If you want a simple "Start KYC" button that opens the init form first and, on success, opens the KYC modal:

import { useState } from "react";
import { VerificationSDK, KycInitForm, KycModal } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";

const sdk = new VerificationSDK({ serverKey: "your-server-key" });

function App() {
  const [showInit, setShowInit] = useState(false);
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button
        type="button"
        className="kyc-input"
        style={{
          background: "linear-gradient(90deg, #FF8A00 0%, #FF3D77 100%)",
          color: "#fff",
          border: "none",
          borderRadius: 8,
          padding: 10,
          cursor: "pointer"
        }}
        onClick={() => setShowInit(true)}
      >
        Start KYC
      </button>

      {showInit && (
        <div className="kyc-backdrop">
          <div className="kyc-container">
            <KycInitForm
              sdk={sdk}
              onStarted={() => {
                setShowInit(false);
                setShowModal(true);
              }}
            />
          </div>
        </div>
      )}

      {showModal && (
        <KycModal sdk={sdk} onClose={() => setShowModal(false)} />
      )}
    </div>
  );
}

API Reference

VerificationSDK

Constructor

new VerificationSDK({ serverKey: string })

Methods

init(options: InitOptions): Promise<InitResponse>

Initialize a new KYC session.

interface InitOptions {
  reference: string;
  email: string;
  callback_url: string;
  redirect_url: string;
  device_type?: "WEB" | "MOBILE";
}

uploadFace(faceBlob: Blob): Promise<any>

Upload face capture image.

uploadDocument(docBlob: Blob, type: string): Promise<any>

Upload document (CNIC or PASSPORT).

getStatus(): Promise<any>

Get current session status.

Components

KycModal

Main KYC modal component for web usage.

interface KycModalProps {
  sdk: VerificationSDK;
  onClose: () => void;
  classNames?: KycModalClassNames;
  styles?: KycModalStyleOverrides;
}

CSS Classes

• kyc-backdrop - Modal backdrop
• kyc-container - Modal container
• kyc-close - Close button
• kyc-title - Step titles
• kyc-input - Input elements
• kyc-status - Status display
• kyc-error - Error messages
• kyc-loading - Loading indicators

Custom Styling

<KycModal
  sdk={sdk}
  onClose={() => setShowModal(false)}
  styles={{
    backdrop: { backgroundColor: "rgba(0,0,0,0.7)" },
    container: { maxWidth: 520 },
    title: { color: "#1f2937" }
  }}
  classNames={{
    container: "my-custom-modal",
    title: "my-custom-title"
  }}
/>

Error Handling

The SDK handles various error scenarios:

• Session Expired: Automatic detection and user notification
• Face Already Registered: Graceful handling with user feedback
• Document Already Exists: Prevents duplicate uploads
• Network Errors: Proper error messages and retry options

Browser Support

• Web: Modern browsers with camera support

TypeScript

Full TypeScript support with exported types:

import type { 
  InitOptions, 
  InitResponse, 
  InitResponseData 
} from "astra-sdk-astra";

CDN Usage

If you need a drop-in script (e.g., plain HTML pages or React Native WebViews), you can load the prebundled UMD build from any npm-aware CDN.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/kycModal.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/sdk.cdn.global.js"></script>
<div id="astra-kyc"></div>
<script>
  const { VerificationSDK, KycModal } = window.AstraSDK;

  (async () => {
    const sdk = new VerificationSDK({ serverKey: "YOUR_SERVER_KEY" });
    await sdk.init({
      reference: "user123",
      email: "[email protected]",
      callback_url: "https://your-app.com/callback",
      redirect_url: "https://your-app.com/redirect",
      device_type: "WEB",
    });

    ReactDOM.render(
      React.createElement(KycModal, {
        sdk,
        onClose: () => console.log("closed"),
      }),
      document.getElementById("astra-kyc")
    );
  })();
</script>

For React Native, render a WebView that loads an HTML shell similar to the snippet above. Use window.ReactNativeWebView.postMessage(...) from the page to notify your native code when the KYC flow finishes or errors.

Development

Building the SDK

npm run build:lib

Testing

npm test

License

MIT License - see LICENSE file for details.

Support

For support and questions, please contact the development team.