A comprehensive KYC (Know Your Customer) SDK with web and mobile support, featuring face capture, document upload, and seamless device switching.
npm install astra-sdk-protocolbash
npm install astra-sdk-astra
`
Quick Start
$3
`tsx
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(null);
const startKyc = async () => {
setError(null);
setLoading(true);
try {
await sdk.init({
reference: "user123",
email: "user@example.com",
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 (
{error && {error}}
{showModal && (
onClose={() => setShowModal(false)}
/>
)}
);
}
`
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
$3
If you prefer an out-of-the-box flow with a start button, init form, terms screen, and modal managed for you:
`tsx
import { KycFlow } from "astra-sdk-astra";
import "astra-sdk-astra/kycModal.css";
function App() {
return (
);
}
`
$3
If you want a simple "Start KYC" button that opens the init form first and, on success, opens the KYC modal:
`tsx
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 (
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
{showInit && (
onStarted={() => {
setShowInit(false);
setShowModal(true);
}}
/>
)}
{showModal && (
setShowModal(false)} />
)}
);
}
`
API Reference
$3
#### Constructor
`tsx
new VerificationSDK({ serverKey: string })
`
#### Methods
##### init(options: InitOptions): Promise
Initialize a new KYC session.
`tsx
interface InitOptions {
reference: string;
email: string;
callback_url: string;
redirect_url: string;
device_type?: "WEB" | "MOBILE";
}
`
##### uploadFace(faceBlob: Blob): Promise
Upload face capture image.
##### uploadDocument(docBlob: Blob, type: string): Promise
Upload document (CNIC or PASSPORT).
##### getStatus(): Promise
Get current session status.
$3
#### KycModal
Main KYC modal component for web usage.
`tsx
interface KycModalProps {
sdk: VerificationSDK;
onClose: () => void;
classNames?: KycModalClassNames;
styles?: KycModalStyleOverrides;
}
`
$3
- 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
$3
`tsx
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:
`tsx
import type {
InitOptions,
InitResponse,
InitResponseData
} from "astra-sdk-astra";
`
Development
$3
`bash
npm run build:lib
`
$3
`bash
npm test
``