@finclusionaibuild/verification-package

A comprehensive React component library for KYC (Know Your Customer) and KYB (Know Your Business) verification flows. This package provides ready-to-use components for various verification types including BVN, NIN, CAC, TIN, and Liveliness checks.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Components
• Theme Configuration
• Styling Guide
• Verification Types
• API Endpoints
• Hooks
• Advanced Usage
• TypeScript Support
• Examples
• Troubleshooting
• API Reference
• License

Features

• ✅ Dynamic Tier System - Backend-driven verification tiers with serial progression
• ✅ Multiple Verification Types - BVN, NIN, CAC, TIN, and Liveliness checks
• ✅ Fully Customizable Themes - Complete control over colors, typography, spacing, and styling
• ✅ TypeScript Support - Full type definitions included
• ✅ Responsive Design - Mobile-first, works on all screen sizes
• ✅ Accessible - WCAG compliant with proper ARIA labels
• ✅ Flexible API Integration - Customizable endpoints for your backend
• ✅ Progress Tracking - Real-time progress indicators and status badges
• ✅ Error Handling - Comprehensive error handling with user-friendly messages

Installation

Prerequisites

• React 18.3.1 or higher
• React DOM 18.3.1 or higher
• Node.js 16+ and npm/yarn/pnpm

Install the Package

# Using npm
npm install @finclusionaibuild/verification-package

# Using yarn
yarn add @finclusionaibuild/verification-package

# Using pnpm
pnpm add @finclusionaibuild/verification-package

Install Peer Dependencies

npm install react@^18.3.1 react-dom@^18.3.1 lucide-react@^0.344.0

Import CSS Styles

Important: You must import the package styles in your application entry point:

// In your main App.tsx or index.tsx
import '@finclusionaibuild/verification-package/styles.css';

Or if using a CSS import:

import '@finclusionaibuild/verification-package/dist/styles.css';

Tailwind CSS Requirement

This package uses Tailwind CSS for styling. Ensure your project has Tailwind CSS configured:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add to your tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@finclusionaibuild/verification-package/**/*.{js,jsx,ts,tsx}",
  ],
  // ... rest of config
}

Quick Start

Basic Setup

1. Wrap your app with KYCProvider:

import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function App() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual', // or 'business'
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC />
    </KYCProvider>
  );
}

export default App;

2. That's it! The DynamicKYC component will automatically:
   • Fetch verification status from your backend
   • Display available tiers
   • Handle verification flows
   • Track progress

Configuration

KYCConfig Interface

The KYCConfig interface defines all configuration options:

interface KYCConfig {
  // Required
  apiBaseUrl: string;                    // Your API base URL
  getAuthToken: () => string | null;     // Function to retrieve auth token
  userType: 'individual' | 'business';  // User type

  // Optional
  appCode?: string;                     // Application code (e.g., "JP" for BVN)
  
  // Callbacks
  onVerificationComplete?: (tier: number, data?: any) => void;
  onTierChange?: (tier: number) => void;
  onError?: (error: Error) => void;
  
  // Theming
  theme?: ThemeConfig;                  // Complete theme configuration
  customStyles?: Record<string, React.CSSProperties | string>;
  
  // Behavior
  locale?: string;                      // Locale for i18n (future)
  enabledTiers?: number[];              // [1, 2, 3] or subset
  requireTierSequence?: boolean;        // Must complete tiers in order
  
  // API Endpoints
  endpoints?: {
    bvn?: string;
    nin?: string;
    liveliness?: string | {
      startSession?: string;
      submitSession?: string;
    };
    livelinessStatus?: string;
    dynamicKYCStatus?: string;
    documentsUpload?: string;
    documents?: string;
    verify?: string;
    cac?: {
      endpoint?: string;
      googleMapsAPIKey?: string;
    };
  };
  
  // Powered By Logo
  poweredBy?: {
    logoUrl?: string;
    altText?: string;
    linkUrl?: string;
    width?: string;
    height?: string;
    position?: 'left' | 'center' | 'right';
    textPrefix?: string;
    show?: boolean;
  };
}

Complete Configuration Example

import { KYCConfig } from '@finclusionaibuild/verification-package';

const config: KYCConfig = {
  // Required fields
  apiBaseUrl: 'https://api.yourdomain.com',
  getAuthToken: () => {
    // Get token from your auth system
    return localStorage.getItem('accessToken') || sessionStorage.getItem('token');
  },
  userType: 'individual', // or 'business'
  
  // Optional: Application code
  appCode: 'JP',
  
  // Callbacks
  onVerificationComplete: (tier, data) => {
    console.log(`Tier ${tier} completed!`, data);
    // Update your app state, show notification, etc.
  },
  onTierChange: (tier) => {
    console.log(`User moved to tier ${tier}`);
  },
  onError: (error) => {
    console.error('KYC Error:', error);
    // Send to error tracking service
  },
  
  // Custom endpoints (optional - uses defaults if not provided)
  endpoints: {
    bvn: '/api/verify/bvn',
    nin: '/api/verify/nin',
    dynamicKYCStatus: '/api/kyc/status',
    verify: '/api/kyc/verify/{verificationType}',
    cac: {
      endpoint: '/api/verify/cac',
      googleMapsAPIKey: 'your-google-maps-api-key',
    },
  },
  
  // Powered By Logo (optional)
  poweredBy: {
    logoUrl: 'https://yourdomain.com/logo.png',
    altText: 'Powered by Your Company',
    linkUrl: 'https://yourdomain.com',
    position: 'center',
    textPrefix: 'Powered by',
    width: 'w-24',
    height: 'h-8',
  },
};

Components

DynamicKYC

The main component that displays the verification interface with tier cards and progress tracking.

import { DynamicKYC } from '@finclusionaibuild/verification-package';

<DynamicKYC
  onVerificationComplete={(tier, verifications) => {
    console.log(`Tier ${tier} completed with:`, verifications);
  }}
  showHeader={true} // Show/hide the header section
/>

Props:

• onVerificationComplete?: (tier: string, verifications: string[]) => void - Callback when a tier is completed
• showHeader?: boolean - Show/hide the header (default: true)

DynamicTierCard

Individual tier card component (used internally by DynamicKYC).

VerificationOrchestrator

Manages the flow of individual verification modals (used internally).

Individual Verification Modals

You can use verification modals individually if needed:

import {
  BVNVerificationModal,
  NINVerificationModal,
  CACVerificationModal,
  TINVerificationModal,
  LivelinessVerificationModal,
} from '@finclusionaibuild/verification-package';

// Example: BVN Verification
<BVNVerificationModal
  onComplete={(data) => {
    console.log('BVN verified:', data);
  }}
  onClose={() => {
    // Handle close
  }}
  initialData={{
    // Pre-fill if available
  }}
/>

Theme Configuration

The package provides a comprehensive theming system that allows you to customize every aspect of the UI.

Theme Structure

interface ThemeConfig {
  statusColors?: {
    completed?: string;
    inProgress?: string;
    pending?: string;
    locked?: string;
    error?: string;
  };
  primaryColors?: {
    main?: string;
    hover?: string;
    text?: string;
    light?: string;
  };
  neutralColors?: {
    background?: string;
    textPrimary?: string;
    textSecondary?: string;
    textTertiary?: string;
    border?: string;
    progressBg?: string;
  };
  componentStyles?: {
    cardPadding?: string;
    cardPaddingCompact?: string;
    cardBorderRadius?: string;
    cardBorderRadiusLarge?: string;
    buttonBorderRadius?: string;
    badgeBorderRadius?: string;
    progressBorderRadius?: string;
    cardShadow?: string;
    cardShadowHover?: string;
    modalShadow?: string;
  };
  typography?: {
    heading1?: string;
    heading2?: string;
    heading3?: string;
    body?: string;
    bodySmall?: string;
    button?: string;
  };
  iconSizes?: {
    tier?: string;
    status?: string;
    small?: string;
    button?: string;
  };
  progressBar?: {
    height?: string;
    heightSmall?: string;
  };
  modal?: {
    overlayOpacity?: string;
    maxWidth?: string;
  };
  spacing?: {
    sectionGap?: string;
    gridGap?: string;
  };
  opacity?: {
    locked?: string;
  };
  formElements?: {
    labelText?: string;
    helperText?: string;
    inputPadding?: string;
    inputBorderRadius?: string;
    inputBorder?: string;
    inputFocusRing?: string;
    secondaryButtonBorder?: string;
    disabledOpacity?: string;
  };
}

Color Values

All color values can be:

• Hex colors: "#2563eb", "#10b981"
• RGB/RGBA: "rgb(37, 99, 235)", "rgba(37, 99, 235, 0.1)"
• CSS color names: "blue", "green"

Spacing and Typography

Spacing, border radius, and typography use Tailwind CSS classes:

• Spacing: "p-6", "px-4", "py-2"
• Border radius: "rounded-lg", "rounded-full"
• Typography: "text-sm", "text-2xl font-bold"

Theme Examples

Minimal Theme (Only Customize What You Need)

const config: KYCConfig = {
  // ... other config
  theme: {
    primaryColors: {
      main: "#6366f1",      // Custom indigo
      hover: "#4f46e5",
    },
    statusColors: {
      completed: "#10b981",  // Custom green
    },
  },
};

Complete Light Theme

const config: KYCConfig = {
  // ... other config
  theme: {
    statusColors: {
      completed: "#10b981",      // Green
      inProgress: "#2563eb",     // Blue
      pending: "#f59e0b",         // Amber
      locked: "#9ca3af",         // Gray
      error: "#ef4444",          // Red
    },
    primaryColors: {
      main: "#2563eb",           // Blue
      hover: "#1d4ed8",
      text: "#ffffff",
      light: "#dbeafe",
    },
    neutralColors: {
      background: "#ffffff",
      textPrimary: "#111827",
      textSecondary: "#4b5563",
      textTertiary: "#6b7280",
      border: "#e5e7eb",
      progressBg: "#e5e7eb",
    },
    componentStyles: {
      cardPadding: "p-6",
      cardBorderRadius: "rounded-lg",
      buttonBorderRadius: "rounded-lg",
      cardShadow: "shadow-sm",
    },
    typography: {
      heading1: "text-2xl font-bold",
      heading2: "text-lg font-semibold",
      body: "text-sm",
    },
  },
};

Dark Theme

const config: KYCConfig = {
  // ... other config
  theme: {
    statusColors: {
      completed: "#34d399",      // Lighter green
      inProgress: "#60a5fa",     // Lighter blue
      pending: "#fbbf24",         // Lighter yellow
      locked: "#6b7280",
      error: "#f87171",          // Lighter red
    },
    primaryColors: {
      main: "#60a5fa",
      hover: "#3b82f6",
      text: "#ffffff",
      light: "#1e3a8a",
    },
    neutralColors: {
      background: "#1f2937",     // Dark gray
      textPrimary: "#f9fafb",    // Light text
      textSecondary: "#d1d5db",
      textTertiary: "#9ca3af",
      border: "#374151",
      progressBg: "#374151",
    },
    componentStyles: {
      cardShadow: "shadow-lg",
      modalShadow: "shadow-2xl",
    },
  },
};

Custom Brand Theme

const config: KYCConfig = {
  // ... other config
  theme: {
    statusColors: {
      completed: "#22c55e",
      inProgress: "#3b82f6",
      pending: "#f59e0b",
      locked: "#94a3b8",
      error: "#ef4444",
    },
    primaryColors: {
      main: "#8b5cf6",           // Purple brand color
      hover: "#7c3aed",
      text: "#ffffff",
      light: "#ede9fe",
    },
    neutralColors: {
      background: "#ffffff",
      textPrimary: "#0f172a",
      textSecondary: "#475569",
      textTertiary: "#64748b",
      border: "#cbd5e1",
      progressBg: "#e2e8f0",
    },
    componentStyles: {
      cardBorderRadius: "rounded-xl",  // More rounded
      cardPadding: "p-8",              // More padding
    },
    typography: {
      heading1: "text-3xl font-bold",  // Larger heading
    },
  },
};

Theme Property Reference

For a complete reference of all theme properties, see the THEME_CONFIG_EXAMPLE.ts file in the package or check the TypeScript definitions.

Styling Guide

CSS Import

Always import the package styles:

import '@finclusionaibuild/verification-package/styles.css';

Tailwind CSS

The package uses Tailwind CSS. Ensure your project has Tailwind configured and includes the package in your content paths:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@finclusionaibuild/verification-package/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

CSS Variables

The package uses CSS custom properties (variables) for theming. These are automatically injected by the KYCProvider:

/* Example CSS variables */
--kyc-color-primary-main: #2563eb;
--kyc-color-status-completed: #10b981;
--kyc-color-neutral-background: #ffffff;
/* ... and more */

Custom CSS Overrides

You can override styles using CSS:

/* Override specific component styles */
.kyc-tier-card {
  border: 2px solid #custom-color;
}

/* Override theme variables */
:root {
  --kyc-color-primary-main: #your-color;
}

Verification Types

BVN (Bank Verification Number)

Required for: Individual users (Nigeria)

Data Required:

• BVN number
• First name
• Last name
• Middle name (optional)
• Date of birth (DD/MM/YYYY)
• Gender

Example:

// Automatically handled by DynamicKYC
// Or use individually:
<BVNVerificationModal
  onComplete={(data) => {
    console.log('BVN verified:', data);
  }}
  onClose={() => {}}
/>

NIN (National Identification Number)

Required for: Individual users (Nigeria)

Data Required:

• NIN number

Example:

<NINVerificationModal
  onComplete={(data) => {
    console.log('NIN verified:', data);
  }}
  onClose={() => {}}
/>

CAC (Corporate Affairs Commission)

Required for: Business users (Nigeria)

Data Required:

• Company registration number
• Company name
• Company address
• Director information
• Supporting documents (upload)

Example:

<CACVerificationModal
  onComplete={(data) => {
    console.log('CAC verified:', data);
  }}
  onClose={() => {}}
/>

TIN (Tax Identification Number)

Required for: Business users

Data Required:

• TIN number

Example:

<TINVerificationModal
  onComplete={(data) => {
    console.log('TIN verified:', data);
  }}
  onClose={() => {}}
/>

Liveliness Check

Required for: Individual users (face verification)

Data Required:

• Video recording of face
• Follows on-screen instructions

Example:

<LivelinessVerificationModal
  onComplete={(data) => {
    console.log('Liveliness verified:', data);
  }}
  onClose={() => {}}
/>

API Endpoints

Default Endpoints

The package uses these default endpoints (relative to apiBaseUrl):

{
  bvn: '/nigeria/bvn',
  nin: '/nigeria/nin',
  liveliness: '/api/liveliness',
  livelinessStatus: '/api/liveliness/{sessionId}',
  dynamicKYCStatus: '/kyc-status',
  documentsUpload: '/kyc/documents/upload',
  documents: '/kyc/documents',
  verify: '/kyc/verify/{verificationType}',
}

Custom Endpoints

Override defaults in your config:

const config: KYCConfig = {
  // ... other config
  endpoints: {
    bvn: '/api/custom/bvn-verify',
    nin: '/api/custom/nin-verify',
    dynamicKYCStatus: '/api/custom/kyc/status',
    verify: '/api/custom/verify/{verificationType}',
    cac: {
      endpoint: '/api/custom/cac-verify',
      googleMapsAPIKey: 'your-key-here',
    },
    liveliness: {
      startSession: '/api/liveness/start',
      submitSession: '/api/liveness/{sessionId}/submit',
    },
  },
};

Endpoint Placeholders

Some endpoints support placeholders that are replaced at runtime:

• {sessionId} - Replaced with actual session ID
• {verificationType} - Replaced with verification type (bvn, nin, etc.)

Authentication

All API requests include the authentication token from getAuthToken():

// Example: Token in Authorization header
Authorization: Bearer <token-from-getAuthToken()>

Expected Response Formats

Dynamic KYC Status

{
  currentTier: "tier1" | "tier2" | "tier3",
  overallProgress: number, // 0-100
  isFullyCompleted: boolean,
  tierRequirements: [
    {
      tier: "tier1",
      required: ["bvn", "nin"],
      completed: ["bvn"],
      pending: ["nin"],
      progress: 50,
      isCompleted: false,
    },
    // ... more tiers
  ],
  collectedPersonalInfo: boolean,
}

Verification Response

{
  success: boolean,
  message: string,
  data?: any,
}

Hooks

useKYC

Hook to access KYC status and operations (legacy - for non-dynamic KYC).

import { useKYC } from '@finclusionaibuild/verification-package';

function MyComponent() {
  const { status, progress, loading, error, refresh, service } = useKYC();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <p>Status: {status?.overall}</p>
      <p>Progress: {progress?.percentage}%</p>
      <button onClick={refresh}>Refresh</button>
    </div>
  );
}

Returns:

• status: KYCStatus | null - Current KYC status
• progress: KYCProgress | null - Progress information
• loading: boolean - Loading state
• error: Error | null - Error state
• refresh: () => Promise<void> - Refresh function
• service: KYCService - Service instance

useKYCContext

Access the KYC context (config and service).

import { useKYCContext } from '@finclusionaibuild/verification-package';

function MyComponent() {
  const { config, service, theme } = useKYCContext();

  return (
    <div>
      <p>User Type: {config.userType}</p>
    </div>
  );
}

Returns:

• config: KYCConfig - Current configuration
• service: KYCService - Service instance
• theme: Required<ThemeConfig> - Merged theme configuration

useKYCTheme

Access the merged theme configuration.

import { useKYCTheme } from '@finclusionaibuild/verification-package';

function MyComponent() {
  const theme = useKYCTheme();

  return (
    <div style={{ color: `var(--kyc-color-primary-main)` }}>
      <h1 className={theme.typography.heading1}>Title</h1>
    </div>
  );
}

Returns:

• theme: Required<ThemeConfig> - Complete theme configuration with defaults merged

Advanced Usage

Custom Verification Flow

import { VerificationOrchestrator } from '@finclusionaibuild/verification-package';

function CustomFlow() {
  const [verifications, setVerifications] = useState(['bvn', 'nin']);
  const [showModal, setShowModal] = useState(false);

  return (
    <>
      <button onClick={() => setShowModal(true)}>
        Start Verification
      </button>
      {showModal && (
        <VerificationOrchestrator
          requiredVerifications={verifications}
          onComplete={(completed) => {
            console.log('Completed:', completed);
            setShowModal(false);
          }}
          onClose={() => setShowModal(false)}
        />
      )}
    </>
  );
}

Error Handling

const config: KYCConfig = {
  // ... other config
  onError: (error) => {
    // Log to error tracking service
    console.error('KYC Error:', error);
    
    // Show user-friendly message
    toast.error('Verification failed. Please try again.');
    
    // Send to analytics
    analytics.track('kyc_error', {
      error: error.message,
    });
  },
};

Conditional Tier Enabling

const config: KYCConfig = {
  // ... other config
  enabledTiers: [1, 2], // Only enable tier 1 and 2
  requireTierSequence: true, // Must complete in order
};

Custom Styling Per Component

const config: KYCConfig = {
  // ... other config
  customStyles: {
    'tier-card': {
      border: '2px solid #custom-color',
    },
    'verification-modal': {
      maxWidth: '800px',
    },
  },
};

TypeScript Support

The package includes full TypeScript definitions. All types are exported:

import type {
  KYCConfig,
  ThemeConfig,
  DynamicKYCStatusResponse,
  TierRequirement,
  VerificationType,
  BVNVerificationRequest,
  BVNVerificationResponse,
  // ... and more
} from '@finclusionaibuild/verification-package';

Type Safety Example

import type { KYCConfig } from '@finclusionaibuild/verification-package';

const config: KYCConfig = {
  apiBaseUrl: 'https://api.example.com',
  getAuthToken: () => localStorage.getItem('token'),
  userType: 'individual', // TypeScript will error if invalid
};

Examples

Example 1: Individual User Setup

import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function IndividualKYC() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual' as const,
    onVerificationComplete: (tier, data) => {
      console.log(`Tier ${tier} completed!`);
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC showHeader={true} />
    </KYCProvider>
  );
}

export default IndividualKYC;

Example 2: Business User Setup

import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function BusinessKYB() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'business' as const,
    endpoints: {
      cac: {
        endpoint: '/api/verify/cac',
        googleMapsAPIKey: 'your-google-maps-key',
      },
    },
    onVerificationComplete: (tier, data) => {
      console.log(`Business tier ${tier} completed!`);
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC showHeader={true} />
    </KYCProvider>
  );
}

export default BusinessKYB;

Example 3: Custom Theme

import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function ThemedKYC() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual' as const,
    theme: {
      primaryColors: {
        main: '#8b5cf6', // Purple brand
        hover: '#7c3aed',
      },
      statusColors: {
        completed: '#22c55e',
        inProgress: '#3b82f6',
        pending: '#f59e0b',
      },
      componentStyles: {
        cardBorderRadius: 'rounded-xl',
        cardPadding: 'p-8',
      },
      typography: {
        heading1: 'text-3xl font-bold',
      },
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC />
    </KYCProvider>
  );
}

export default ThemedKYC;

Example 4: Custom Endpoints

import React from 'react';
import { KYCProvider, DynamicKYC } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function CustomEndpointsKYC() {
  const config = {
    apiBaseUrl: 'https://api.yourdomain.com',
    getAuthToken: () => localStorage.getItem('authToken'),
    userType: 'individual' as const,
    endpoints: {
      bvn: '/api/v2/verify/bvn',
      nin: '/api/v2/verify/nin',
      dynamicKYCStatus: '/api/v2/kyc/status',
      verify: '/api/v2/kyc/verify/{verificationType}',
      liveliness: {
        startSession: '/api/v2/liveness/start',
        submitSession: '/api/v2/liveness/{sessionId}/submit',
      },
    },
  };

  return (
    <KYCProvider config={config}>
      <DynamicKYC />
    </KYCProvider>
  );
}

export default CustomEndpointsKYC;

Example 5: Complete Integration

import React, { useState } from 'react';
import { KYCProvider, DynamicKYC, useKYCContext } from '@finclusionaibuild/verification-package';
import '@finclusionaibuild/verification-package/styles.css';

function App() {
  const config = {
    apiBaseUrl: process.env.REACT_APP_API_URL || 'https://api.yourdomain.com',
    getAuthToken: () => {
      // Get from your auth system
      return localStorage.getItem('accessToken');
    },
    userType: 'individual' as const,
    appCode: 'JP',
    onVerificationComplete: (tier, data) => {
      // Update your app state
      console.log(`Tier ${tier} completed!`, data);
      
      // Show success notification
      // Update user permissions
      // Redirect if needed
    },
    onError: (error) => {
      console.error('KYC Error:', error);
      // Handle error (show toast, log to service, etc.)
    },
    theme: {
      primaryColors: {
        main: '#2563eb',
        hover: '#1d4ed8',
      },
    },
    poweredBy: {
      logoUrl: 'https://yourdomain.com/logo.png',
      altText: 'Powered by Your Company',
      position: 'center',
    },
  };

  return (
    <KYCProvider config={config}>
      <div className="app">
        <header>
          <h1>My Application</h1>
        </header>
        <main>
          <DynamicKYC showHeader={true} />
        </main>
      </div>
    </KYCProvider>
  );
}

export default App;

Troubleshooting

React Multiple Instances Error

If you see: Cannot read properties of undefined (reading 'ReactCurrentDispatcher')

Solution:

1. Rebuild the package: npm run build in the package directory
2. Clear node_modules and reinstall in your project
3. Ensure peer dependencies are installed correctly
4. Add to your Vite config (if using Vite):

// vite.config.ts
export default {
  resolve: {
    dedupe: ['react', 'react-dom'],
  },
  optimizeDeps: {
    include: ['react', 'react-dom'],
  },
}

Styles Not Applying

Solution:

1. Ensure you've imported the CSS: import '@finclusionaibuild/verification-package/styles.css'
2. Check that Tailwind CSS is configured correctly
3. Verify the package is included in Tailwind's content paths

Theme Not Working

Solution:

1. Ensure KYCProvider is wrapping your components
2. Check that theme properties use correct formats (hex for colors, Tailwind classes for spacing)
3. Verify CSS variables are being injected (check browser DevTools)

API Errors

Solution:

1. Verify apiBaseUrl is correct
2. Check that getAuthToken() returns a valid token
3. Ensure your backend endpoints match the configured endpoints
4. Check network tab for actual request/response

TypeScript Errors

Solution:

1. Ensure you're using the latest version of the package
2. Check that types are installed: npm install --save-dev @types/react @types/react-dom
3. Restart your TypeScript server in your IDE

Build Errors

Solution:

1. Ensure all peer dependencies are installed
2. Check Node.js version (16+ required)
3. Clear build cache and rebuild

API Reference

KYCService

The service class handles all API communication.

Methods:

• getDynamicKYCStatus(): Promise<DynamicKYCStatusResponse>
• submitVerification(verificationType, data): Promise<{success, message, data}>
• submitCACTierOne(formData): Promise<{success, message, data}>

Components

DynamicKYC

Main verification component.

Props:

interface DynamicKYCProps {
  onVerificationComplete?: (tier: string, verifications: string[]) => void;
  showHeader?: boolean;
}

KYCProvider

Context provider for KYC configuration.

Props:

interface KYCProviderProps {
  config: KYCConfig;
  children: ReactNode;
}

Types

All types are exported from the package. See TypeScript definitions for complete reference.

Contributing

Contributions are welcome! Please see the repository for contribution guidelines.

License

MIT

Need Help? Open an issue on GitHub or contact support.