MetaKYC SDK

A comprehensive React SDK for MetaKYC due diligence workflows with configurable API endpoints, dynamic form generation, and complete workflow step coverage.

Features

• ✅ Configurable API Endpoints - Support for both Host Controller and Application Service patterns
• ✅ Complete Workflow Coverage - All 9 workflow step types supported
• ✅ Dynamic Applicant Form - 23 configurable form fields for applicant creation
• 🎨 Backend-Driven Theming - Multi-tenant theme customization with 6 presets, custom logo, colors, and CSS (NEW v1.2.0)
• ✅ React Hooks - Clean API with hooks for each workflow step
• ✅ Pre-built Components - Ready-to-use UI components with Tailwind CSS
• ✅ Dynamic Form Validation - Automatic zod schema generation from API rules
• ✅ Identity Provider Integration - Sumsub, Onfido, and SardinAI support
• ✅ TypeScript - Full type safety with types generated from C# DTOs
• ✅ Session Token Auth - Server-side token creation with optional externalRefId scoping guard
• ✅ Dark Mode - Built-in dark mode support

Installation

npm install @metakyc/sdk
# or
yarn add @metakyc/sdk
# or
pnpm add @metakyc/sdk

Quick Start

Step 1 — Server: create a session token

Create a short-lived session token on your backend. The API key and secret never leave your server.

// ── Server-side (Next.js API route, Express, etc.) ──
import { MetaKYCSession } from '@vpdev2/metakyc';

export async function POST() {
  const { accessToken, expiresInSeconds } = await MetaKYCSession.createToken({
    baseUrl:       'https://api.example.com',
    clientId:      'your-client-id',           // or tenantId: 1
    apiKey:        process.env.METAKYC_API_KEY!,
    secretKey:     process.env.METAKYC_SECRET_KEY!,
    externalRefId: 'USER-12345',               // optional — scopes the token to this user
  });
  return Response.json({ accessToken, expiresInSeconds });
}

| Parameter | Type | Required | Description | |---|---|---|---| | baseUrl | string | Yes | MetaKYC API base URL | | apiKey | string | Yes | Your tenant API key | | secretKey | string | Yes | Your tenant secret key | | tenantId | number | One of | Numeric tenant ID (provide this or clientId) | | clientId | string | One of | String client ID (provide this or tenantId) | | externalRefId | string | No | When set, the returned token is scoped: all API calls made with it can only create or access applicants matching this externalRefId. Tokens created without it remain unrestricted (backward-compatible). |

Step 2 — Client: initialize the SDK

Pass the token to the frontend SDK via getAccessToken:

import { MetaKYCProvider } from '@vpdev2/metakyc';

function App() {
  return (
    <MetaKYCProvider
      config={{
        getAccessToken: () => fetchSessionToken(), // returns the accessToken string
        clientId: 'your-client-id',
        baseUrl: 'https://api.example.com',
        endpoints: { pattern: 'host-controller' },
        applicantForm: {
          externalRefId: 'USER-12345',
        },
        // Optional: Configure identity providers (e.g., SardinAI)
        identityProviders: {
          sardinai: process.env.SARDINAI_CLIENT_ID ? {
            clientId: process.env.SARDINAI_CLIENT_ID,
            environment: 'sandbox', // or 'production'
            region: 'us',           // 'us', 'eu', 'ca', or 'au'
            enableBiometrics: true,
            enablePortScanning: false,
          } : undefined,
        },
      }}
    >
      <YourApp />
    </MetaKYCProvider>
  );
}

Tip: You can also pass apiKey directly instead of getAccessToken for quick testing, but session tokens are recommended for production since they keep your secret key on the server.

Step 3 — Use the workflow component

import { KycWorkflow } from '@metakyc/sdk';

function KYCPage() {
  return (
    <KycWorkflow
      applicantId={applicantId}
      onComplete={(result) => console.log('Complete:', result)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Step 4 — Or build custom UI with hooks

import { useKycWorkflow, useQuestionnaire } from '@metakyc/sdk';

function CustomKYC() {
  const { progress, currentStep, moveToNext } = useKycWorkflow(applicantId);
  const questionnaire = useQuestionnaire(applicantId);

  // Build your custom UI...
}

Documentation

Core Features

• 🎨 Theming System - Multi-tenant theme customization (NEW v1.2.0)
• Dynamic Form Configuration - Configure visible fields in applicant creation form
• Workflow Key Management - Configure and handle workflow keys and transitions
• External Reference ID - Required field for system integration
• Step Visibility - Configure which workflow steps appear in the UI
• Appropriateness Test - Quiz system with timer and retry logic
• Identity Expiration Handling - Managing expired identity verification sessions
• KYC Status Display - Rich status UI for completed/rejected/pending states
• SardinAI Integration - Automatic sessionKey generation for SardinAI Risk SDK

Backend Integration

• 🔧 Backend Theme Integration - Database schema, API endpoints, DTOs (NEW v1.2.0)
• 🎨 Panel Theme UI - Complete Panel UI implementation guide (NEW v1.2.0)

Migration & Changes

• Migration Guide - Migrate from custom form to dynamic configuration (v1.0.0 → v1.1.0)
• Changelog - Version history and changes

License

MIT