@ayasofyazilim/kyc

KYC (Know Your Customer) component library with document scanning, liveness detection, and full internationalization support.

Features

• 📄 Document Scanning: Support for ID cards and passports with MRZ extraction
• 👤 Liveness Detection: AWS Amplify-powered face liveness verification
• 🌍 Internationalization: Full i18n support with customizable language data
• 📱 Camera Permission Handling: Browser-specific instructions for camera access
• 🎨 Customizable UI: Tailwind CSS-based styling with theme support
• ✅ Type-Safe: Full TypeScript support with comprehensive type definitions

Installation

pnpm add @ayasofyazilim/kyc

or

npm install @ayasofyazilim/kyc

Note: This package includes AWS Amplify as a dependency, so you don't need to install aws-amplify separately.

Quick Start

import { KYC, defaultEnglishLanguageData } from "@ayasofyazilim/kyc";
import "@ayasofyazilim/kyc/dist/styles.css";

function App() {
  return (
    <KYC
      config={{
        isMRZRequired: true,
        isLivenessRequired: false,
        isNFCRequired: false,
        source: "SSR",
        languageData: defaultEnglishLanguageData,
      }}
      onComplete={(data) => console.log("KYC Complete:", data)}
      onError={(error) => console.error("KYC Error:", error)}
      onDecline={() => console.log("User declined KYC")}
    />
  );
}

Configuration

All configuration is passed through the config prop. No environment variables are required for this package.

KYC Config Type

type KYCConfig = {
  isMRZRequired: boolean; // Require MRZ data extraction
  isNFCRequired: boolean; // Require NFC chip reading (not yet implemented)
  isLivenessRequired: boolean; // Require face liveness check
  source: "SSR"; // Source identifier
  languageData: KYCLanguageData; // Language/translation data (REQUIRED)
};

Internationalization (i18n)

The KYC component supports full internationalization through the languageData prop.

Using Default English

import { KYC, defaultEnglishLanguageData } from "@ayasofyazilim/kyc";

<KYC
  config={{
    // ... other config
    languageData: defaultEnglishLanguageData,
  }}
  // ... handlers
/>;

Creating Custom Translations

import { type KYCLanguageData } from "@ayasofyazilim/kyc";

const turkishLanguageData: KYCLanguageData = {
  getStarted: {
    title: "Kimliğinizi doğrulayın",
    photoIdInfo: "Fotoğraflı Kimlik",
    // ... rest of translation
  },
  getReady: {
    title: "Kimliğinizi taramaya hazırlanın",
    // ...
  },
  // ... complete all required sections
};

<KYC
  config={{
    // ... other config
    languageData: turkishLanguageData,
  }}
  // ... handlers
/>;

For a complete language data structure and examples, see LANGUAGE_DATA_UPDATE.md and USAGE_EXAMPLES.tsx.

AWS Amplify Setup

This package uses AWS Amplify UI React Liveness for face liveness detection. AWS Amplify is included with this package for your convenience - you don't need to install aws-amplify separately.

Configure Amplify with your AWS credentials in your application's entry point (e.g., _app.tsx, main.tsx, or layout.tsx):

import { Amplify } from "@ayasofyazilim/kyc";

Amplify.configure({
  Auth: {
    // Amazon Cognito User Pool ID
    userPoolId: "us-east-1_XXXXXXXXX",
    // Amazon Cognito User Pool Client ID
    userPoolWebClientId: "XXXXXXXXXXXXXXXXXXXXXXXXXX",
    // Amazon Cognito Region
    region: "us-east-1",
  },
});

Important: Never hardcode AWS credentials in your application. Use AWS IAM roles, Cognito Identity Pools, or environment variables configured securely.

KYC Component Configuration

<KYC
  config={{
    gatewayUrl: "https://your-api.com",
    isNFCRequired: false,
    source: "SSR",
    awsRegion: "us-east-1", // Optional: defaults to us-east-1
  }}
  // ... other props
/>

Basic Example

import { KYC, Amplify } from "@ayasofyazilim/kyc";

// Configure Amplify in your app's entry point
Amplify.configure({
  Auth: {
    userPoolId: "us-east-1_XXXXXXXXX",
    userPoolWebClientId: "XXXXXXXXXXXXXXXXXXXXXXXXXX",
    region: "us-east-1",
  },
});

export default function Page() {
  return (
    <KYC
      config={{
        gatewayUrl: "https://your-api.com",
        isNFCRequired: false,
        source: "SSR",
      }}
      onSuccess={(data) => {
        console.log("KYC completed successfully", data);
        // data.images - Contains document images (front/back)
        // data.mrzData - Contains MRZ extracted data
        // data.livenessData - Contains liveness detection results
      }}
      onError={(reason) => {
        console.error("KYC error", reason);
      }}
      onDecline={() => {
        console.log("KYC declined by user");
      }}
    />
  );
}

With Custom Last Step

export default function Page() {
  return (
    <KYC
      config={{
        gatewayUrl: "https://your-api.com",
        isNFCRequired: false,
        source: "SSR",
      }}
      onSuccess={handleSuccess}
      onError={handleError}
      onDecline={handleDecline}
      lastStep={(data) => (
        <div>
          <h2>Custom Completion Screen</h2>
          <p>Your KYC process is complete!</p>
        </div>
      )}
    />
  );
}

/> );

Props

| Prop | Type | Required | Description | | ----------- | --------------------------------------------------- | -------- | ----------------------------------------------------------------- | | config | Config | Yes | Configuration object with gatewayUrl, isNFCRequired, source | | onSuccess | (data: KYCSessionData) => void | Yes | Callback function called when KYC is completed successfully | | onError | (reason: string) => void | Yes | Callback function called when an error occurs | | onDecline | () => void | Yes | Callback function called when the user declines the KYC process | | lastStep | (data: KYCSessionData \| null) => React.ReactNode | No | Optional custom component to render as the last step |

Types

KYCSessionData

interface KYCSessionData {
  images: DocumentData;
  mrzData: MRZData | null;
  livenessData: LivenessResult | null;
}

License

ISC