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";

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.