@flonkid/kyc

Official SDK for Flonk identity verification.

• Dashboard: dashboard.flonk.id
• Docs: docs.flonk.id

Install

npm install @flonkid/kyc

| Import | Use | |--------|-----| | @flonkid/kyc | Browser — widget + React component | | @flonkid/kyc/server | Node.js — sessions API + webhook verification |

Keys

You'll find two keys in Dashboard → Project Settings → API Keys:

| Key | Prefix | Where to use | Purpose | |-----|--------|--------------|---------| | Publishable key | pk_live_* / pk_sandbox_* | Frontend (browser) | Loads your project branding (logo, colors) instantly | | Secret key | sk_live_* / sk_sandbox_* | Backend only | Creates sessions, authenticates API calls |

Never expose your secret key in client-side code.

React Component (recommended)

Option A: SDK handles session creation

import { FlonkKYCWidget } from '@flonkid/kyc';

<FlonkKYCWidget
  publishableKey="pk_live_..."
  serverUrl="/api/kyc/create-session"
  clientMetadata={{ email: '[email protected]', userId: 'user_123' }}
  lang="de"
  onSuccess={(result) => console.log('Verified:', result)}
  onError={(error) => console.error(error)}
  onCancel={() => console.log('Cancelled')}
/>

// With authenticated backend
<FlonkKYCWidget
  publishableKey="pk_live_..."
  serverUrl="/api/kyc/create-session"
  requestHeaders={{ Authorization: `Bearer ${token}` }}
  ...
/>

Option B: You control session creation

import { FlonkKYCWidget } from '@flonkid/kyc';

// 1. Create session on your backend first
const { sessionId, embedToken } = await fetch('/api/kyc/create-session', {
  method: 'POST',
  body: JSON.stringify({ email: user.email }),
}).then(r => r.json());

// 2. Pass credentials to widget
<FlonkKYCWidget
  publishableKey="pk_live_..."  // optional — instant branded loader (see note)
  sessionId={sessionId}
  embedToken={embedToken}
  lang="de"
  onSuccess={(result) => console.log('Verified:', result)}
  onError={(error) => console.error(error)}
  onCancel={() => console.log('Cancelled')}
/>

publishableKey enables the instant branded loader in both flows. With it, the brand color is resolved straight from the key (in parallel with session setup) and painted on the first frame; without it, branding is resolved from the session and the loader shows the default color until that request returns.

Props

| Prop | Type | Description | |------|------|-------------| | publishableKey | string | Your pk_live_* key — enables instant branded loader | | serverUrl | string | Your backend endpoint — SDK auto-creates session | | sessionId | string | Pre-created session ID (Option B) | | embedToken | string | JWT token from your backend (Option B) | | requestHeaders | Record<string, string> | Extra headers for serverUrl (e.g. JWT auth) | | clientMetadata | Record<string, unknown> | Custom data passed to session | | lang | 'en' \| 'de' \| 'uk' | Widget language | | onSuccess | (result) => void | Verification completed | | onError | (error) => void | Error occurred | | onCancel | () => void | User closed widget | | onReady | () => void | Widget loaded | | autoOpen | boolean | Open on mount (default: true) |

Imperative API (non-React)

import { FlonkKYC } from '@flonkid/kyc';

const kyc = new FlonkKYC();

const widget = await kyc.init({
  publishableKey: 'pk_live_...',
  serverUrl: '/api/kyc/create-session',
  clientMetadata: { email: '[email protected]' },
  lang: 'de',
  onSuccess: (result) => console.log('Verified:', result),
  onError: (error) => console.error(error),
  onCancel: () => console.log('Cancelled'),
});

// Cleanup
widget.destroy();

Server — Node.js

import { FlonkKYCServer } from '@flonkid/kyc/server';

const flonk = new FlonkKYCServer({ secretKey: 'sk_live_...' });

// Create session
const session = await flonk.createSession({
  clientMetadata: { email: '[email protected]', userId: 'user_123' },
  expiryMinutes: 30,
  language: 'de',
});
// → { id, embedToken, status, expiresAt, widgetUrl, qrCodeUrl }

// Verify webhook
const event = flonk.webhooks.constructEvent(rawBody, signature, secret);

Webhook Events

| Event | Description | |-------|-------------| | verification.completed | AI verification finished | | verification.status_changed | Admin changed status (approved/rejected) | | verification.updated | Admin edited verification data |

const event = flonk.webhooks.constructEvent(rawBody, signature, secret);

switch (event.type) {
  case 'verification.completed':
    console.log('Extracted:', event.data.object.extracted_data);
    break;
  case 'verification.status_changed':
    console.log('New status:', event.data.object.status);
    break;
  case 'verification.updated':
    console.log('Updated by:', event.data.object.updated_by);
    break;
}

Links

• Full Documentation
• Integration Guide
• Webhook Guide
• Dashboard

License

Proprietary. Copyright (c) 2026 Flonk. All rights reserved. See Terms of Service for usage terms.