The browser SDK (`@flonkid/kyc`) renders the verification widget in an iframe and
streams results back to your app via callbacks. It ships first-class React
bindings and a framework-agnostic class for everything else.

```bash
npm install @flonkid/kyc
```

| Import | Runtime | Use |
|--------|---------|-----|
| `@flonkid/kyc` | Browser | `FlonkKYC` class **+** `FlonkKYCWidget` React component |
| `@flonkid/kyc/core` | Browser (no React) | `FlonkKYC` class only — React-free entry for Vue / Angular / Svelte / vanilla |
| `@flonkid/kyc/server` | Node.js | Sessions API + webhook signature verification |
| `@flonkid/kyc/types` | — | TypeScript types only |

> **React is an optional peer dependency.** The default `@flonkid/kyc` entry
> includes the `FlonkKYCWidget` React component, so it imports `react`. If you're
> **not on React**, import the `FlonkKYC` class from **`@flonkid/kyc/core`** — a
> React-free entry, so your bundler never has to resolve React. *(Added in
> `1.9.3`.)*

---

## Two ways to start verification

The widget needs a verification session. You choose **who creates it**.

### Option A — SDK creates the session (`serverUrl`)

You point the SDK at a backend endpoint; it creates the session, opens the
widget, and cleans up. One component, no state to manage.

<CodeTabs
  items={[
    { label: 'React', snippetId: 'frontend/sdk-react-component' },
    { label: 'Vue', snippetId: 'frontend/sdk-vue' },
    { label: 'Angular', snippetId: 'frontend/sdk-angular' },
    { label: 'Script tag', snippetId: 'frontend/sdk-script-tag' },
    { label: 'TypeScript', snippetId: 'frontend/sdk-browser-init' },
  ]}
/>

> **React** imports from `@flonkid/kyc`; **Vue / Angular / vanilla** import the
> `FlonkKYC` class from `@flonkid/kyc/core` (React-free); **no build step** loads
> one `<script>` tag from the API. See the sections below for each.

If your endpoint needs auth, pass `requestHeaders`:

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

### Option B — you create the session (`sessionId` + `embedToken`)

Your code creates the session first (e.g. behind a paywall, an age gate, or a
confirmation screen), then hands the credentials to the widget. More control
over **when** and **whether** a session is created.

<CodeTabs
  items={[
    { label: 'React', snippetId: 'frontend/sdk-react-option-b' },
  ]}
/>

### Which one?

| | Option A (`serverUrl`) | Option B (`sessionId` + `embedToken`) |
|---|---|---|
| **Setup** | 1 component | Button + state + API call + component |
| **Session lifecycle** | SDK manages it | You manage it |
| **Best for** | Quick, simple flows | Custom UX, conditional flows |
| **Auth to your backend** | `requestHeaders` prop | Your own `fetch` |

---

## Instant branding with `publishableKey`

Pass your `publishableKey` (from **Dashboard → API Keys**) and the loading screen
paints **your brand color on the first frame** — no flash of the default green.

Under the hood the SDK resolves branding straight from the key (a Redis-cached
read on the API) **in parallel** with session setup, races it against an 800 ms
budget, and updates the color in place once the full tokens arrive. If the key
hasn't resolved within the budget, it shows a neutral fallback rather than a
blank screen.

This works in **both** flows — Option A *and* Option B. Without a
`publishableKey`, branding is resolved from the session instead, so the loader
shows the default color until that request returns.

> `publishableKey` is safe to expose in client code — it only reads public
> branding and issues short-lived widget tokens. Your **secret key** stays on
> the server.

---

## Props / config reference

The React `<FlonkKYCWidget>` props and the `kyc.init(config)` object share the
same shape.

| Field | Type | Notes |
|-------|------|-------|
| `publishableKey` | `string` | `pk_live_*` / `pk_sandbox_*`. Enables instant branding. Optional but recommended. |
| `serverUrl` | `string` | Your session-creation endpoint (Option A). Absolute URLs must be HTTPS (localhost exempt); relative paths are fine. |
| `sessionId` | `string` | Pre-created session id (Option B). |
| `embedToken` | `string` | Short-lived token for `sessionId` (Option B). |
| `qrCodeUrl` | `string` | The session's `qrCodeUrl` — needed for the desktop→mobile QR. Return it from your `serverUrl` endpoint, or pass it in Option B. |
| `clientMetadata` | `object` | Passed through to your backend / webhooks. `email` is required by most flows. |
| `requestHeaders` | `Record<string,string>` | Extra headers on the `serverUrl` POST — e.g. `Authorization`. |
| `lang` | `WidgetLanguage` | UI language, e.g. `'de'`, `'en'`, `'uk'`. |
| `overlayColor` | `string` | Backdrop color behind the widget. |
| `allowManualUpload` | `boolean` | Override the project default for manual document upload. |
| `autoOpen` | `boolean` | React only. Open on mount. Default `true`. |
| `onSuccess` | `(result) => void` | Flow finished — branch on `result.status`, it is not always approved. |
| `onError` | `(error: string) => void` | Session or verification failed. |
| `onCancel` | `() => void` | User closed the widget. |
| `onReady` | `() => void` | Widget iframe loaded and ready. |
| `onDiagnostic` | `(event) => void` | Observability hook — see [Debugging](#debugging) below. |

### Handling the outcome — `result.status`

`onSuccess` means the flow **finished**, not that the user is verified. The result carries a
`status` you must branch on:

| `result.status` | Meaning | What your UI should do |
|---|---|---|
| `completed` | Verified | Unlock the flow — but confirm server-side via the `verification.completed` webhook. |
| `manual_review` | Under human review | Show a waiting state: "Your verification is being reviewed — you'll receive the result by email (check spam). Usually takes minutes — fast during business hours — and up to 24 hours." Don't offer a new verification; wait for the webhook. |
| `action_required` | One step still missing | The user must redo one part (`result.nextAction`, e.g. `resubmit_back`). Reopening the widget resumes exactly that step. |
| `failed` / other | Not verified | Let the user try again. |

Your backend also receives an informational `verification.status_changed` webhook when a session
enters `manual_review` or `action_required` (with `next_action`), and the final decision events
after review — gate account access on webhooks, never on the browser callback alone. See
[Webhooks](/docs/webhooks).

---

## Other frameworks — the `FlonkKYC` class

Off React, drive the widget with the framework-agnostic `FlonkKYC` class.
**Import it from `@flonkid/kyc/core`** — the React-free entry — so your bundler
(Vite, Angular, Rollup) never tries to resolve `react`. It takes the same config
as `<FlonkKYCWidget>` and returns a handle with `destroy()` for cleanup. Vue,
Svelte, Angular, Solid, or plain TypeScript all use the **same pattern**:
`new FlonkKYC()` → `await kyc.init(...)` → `widget.destroy()` on teardown.

> **Why `/core`?** The default `@flonkid/kyc` entry re-exports the React
> component, so importing it makes your bundler resolve `react`. In a non-React
> project that has no `react` installed, that breaks the production build.
> `@flonkid/kyc/core` omits the component entirely — zero React, zero config.

```ts
import { FlonkKYC } from '@flonkid/kyc/core';

const kyc = new FlonkKYC();

const widget = await kyc.init({
  publishableKey: 'pk_live_...',
  serverUrl: '/api/kyc/create-session',
  clientMetadata: { email: 'user@example.com' },
  lang: 'de',
  onSuccess: (result) => console.log('Verified:', result),
  onError:   (error)  => console.error('Failed:', error),
});

// Later, when navigating away:
widget.destroy();
```

### Vue 3

Call `init` from a method/handler and tear down in `onUnmounted`:

```vue
<script setup lang="ts">
import { onUnmounted } from 'vue';
import { FlonkKYC } from '@flonkid/kyc/core';

let widget: { destroy(): void } | null = null;

async function verify() {
  const kyc = new FlonkKYC();
  widget = await kyc.init({
    publishableKey: 'pk_live_...',
    serverUrl: '/api/kyc/create-session',
    requestHeaders: { Authorization: `Bearer ${token}` }, // if your endpoint is authed
    onSuccess: (result) => console.log('Verified:', result),
    onError:   (error)  => console.error('Failed:', error),
  });
}

onUnmounted(() => widget?.destroy());
</script>

<template>
  <button @click="verify">Verify identity</button>
</template>
```

Svelte (`on:click={verify}` + `onDestroy`) and Angular (call from a component
method, `destroy()` in `ngOnDestroy`) follow the identical shape.

---

## No build step — `<script>` tag

No bundler, no ES modules? Load the SDK as a single self-contained script from
the API and drive it through the `window.KYCWidget` global. This is the path for
**WordPress, Shopify, Rails/Django server-rendered pages, a CMS, or plain HTML**
— anywhere you can't `import` the SDK.

```html

<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-api="https://api.flonk.id/v1"></script>

<button id="verify">Verify identity</button>

<script>
  document.getElementById('verify').onclick = async () => {
    // Your authed backend creates the session and returns { sessionId, embedToken }.
    const res = await fetch('/api/kyc/create-session', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + token },
    });
    const { sessionId, embedToken } = await res.json();

    window.KYCWidget.init({
      sessionId,
      embedToken,
      // Required by init(): the email of the person being verified. Put it on
      // the tag as data-email instead when it is known at page render.
      clientMetadata: { email: user.email },
      onSuccess: (result) => console.log('Verified:', result),
      onError:   (error)  => console.error('Failed:', error),
      onCancel:  ()       => console.log('Cancelled'),
    });
  };
</script>
```

The script exposes:

| `KYCWidget.…` | What |
|---------------|------|
| `init(config)` | Open the widget in a modal. `{ serverUrl }`, `{ sessionId, embedToken }`, or `{ publishableKey }` (it fetches a short-lived widget token itself). Returns `{ iframe, destroy() }`. |
| `redirect(config)` | Navigate the whole page to the widget instead of framing it. One-way. |
| `preview(config)` | Render with mock data and no camera, for layout/branding checks. No session. |
| `embed(config)` | The same preview, mounted into a container of yours. **Preview only** — it verifies nobody. |
| `version` | The script's version string. |
| `noConflict()` | Restore the previous `window.KYCWidget` and return the Flonk object. |

> **Keep the secret server-side here too.** The script-tag path still creates the
> session on your authenticated backend — the browser only ever receives
> `sessionId` + `embedToken` (or uses the public `pk_*`). It self-prewarms on
> load; add `data-prewarm="eager"` to warm the full bundle early.

Attribute reference, CSP requirements, the `embed()` limitation and migration
from the legacy `widget.flonk.id/v1/widget.js` loader:
[Script Tag (No Build Step)](/docs/script-tag).

---

## Performance — prewarming

The widget appears faster if you warm it **before** the user clicks. These are
static methods — call them on page mount or route enter. They never create a
session and are SSR-safe (no-op on the server).

### `FlonkKYC.prewarm(opts)`

Preconnects to the widget origin and prefetches the loader/branding assets at
idle. With `level: 'eager'` it also mounts a hidden background iframe so the
full bundle is loaded before the click. Returns a cleanup function.

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

// Warm assets at idle as soon as the page loads:
FlonkKYC.prewarm({ publishableKey: 'pk_live_…' });

// High-intent page — also load the full widget bundle in the background:
FlonkKYC.prewarm({ publishableKey: 'pk_live_…', level: 'eager' });

// Or warm only when the user shows intent (hover/focus/in-view of a button):
const stop = FlonkKYC.prewarm({ publishableKey: 'pk_live_…', level: 'intent', trigger: btnEl });
```

| `level` | What it warms | Best for |
|---------|---------------|----------|
| `'connect'` *(default)* | preconnect + idle asset prefetch | most pages |
| `'intent'` | warms on hover/focus/scroll-into-view of `trigger` | general pages — zero cost for visitors who never engage |
| `'eager'` | also pre-mounts a hidden iframe (full bundle) | dedicated, high-click-through KYC pages |
| `'none'` | nothing | disable |

### `FlonkKYC.preloadBranding(opts)`

Resolves the project's brand color ahead of time (module-level cache, 5-min TTL)
so the loader paints your color on the first frame with no branding round-trip
at click time. Safe to call repeatedly; concurrent calls dedupe.

```ts
FlonkKYC.preloadBranding({ publishableKey: 'pk_live_…' });
```

> [Script-tag](/docs/script-tag) integration? It self-prewarms on load; add
> `data-prewarm="eager"` to the tag for the eager level.

---

## Debugging

Every SDK degradation is observable — nothing fails silently. Pass
`onDiagnostic`, or flip a global flag to mirror events to the console:

```ts
const kyc = new FlonkKYC({
  onDiagnostic: (e) => console.log(`[flonk:${e.code}] ${e.message}`, e.detail),
});

// Or, without code (also honored by the script-tag build, as is `data-debug`):
window.__FLONK_DEBUG__ = true;
```

Console output is silent unless `onDiagnostic` is set or `__FLONK_DEBUG__` is
truthy, so there's no noise in production. Common codes: `LOADER_SCRIPT_BLOCKED`,
`LOADER_FALLBACK_BUNDLED`, `PREWARM_SKIPPED`, `READY_TIMEOUT_REVEAL`,
`PROTOCOL_VERSION_MISMATCH`. See
[Troubleshooting → Widget / Loader Issues](/docs/troubleshooting#widget-loader-issues).

---

## Framework notes

### Next.js / SSR

`FlonkKYCWidget` is a client component — it touches the DOM and uses
`useEffect`. In the App Router, render it from a file marked `'use client'`:

```tsx
'use client';
import { FlonkKYCWidget } from '@flonkid/kyc';

export function Verify() {
  return <FlonkKYCWidget publishableKey="pk_live_..." serverUrl="/api/kyc/create-session" />;
}
```

The SDK compiles JSX with React's **automatic runtime** (`react/jsx-runtime`),
so it works under SSR and bundlers like Turbopack without any `globalThis.React`
shim. See the [Changelog → SDK](/docs/changelog#sdk) for the version this landed
in (`1.7.0`).

### React StrictMode

In development StrictMode mounts effects twice. The SDK guards against
double-initialization, so you don't need to disable StrictMode or add your own
mount guard.

### Vue / Nuxt / other SSR

The `FlonkKYC` class touches `window`, so call `init` **only on the client** —
from a Vue method, `onMounted`, or behind a `<ClientOnly>` boundary in Nuxt,
never during server render. The `prewarm`/`preloadBranding` statics are SSR-safe
(they no-op on the server).

---

## Cleanup

- **React:** unmounting `<FlonkKYCWidget>` tears the widget down automatically.
- **Vanilla:** call `widget.destroy()` when you're done.

---

**Next:** [Frontend ↔ Backend Integration →](/docs/integration-frontend-backend) ·
[Webhooks →](/docs/webhooks)

Embed the Flonk KYC widget in any web app — React or vanilla TypeScript. Props, init flows, instant branding, and framework notes.

Frontend SDK


For pages that have no build step — WordPress, Shopify, a Rails or Django
template, a CMS block, a plain HTML landing page — load the widget with one
`<script>` tag and drive it through the `window.KYCWidget` global. No bundler,
no ES modules, no npm install.

```html
<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."></script>
```

The file is the same browser SDK the npm package ships, built as a single
self-contained IIFE. Behaviour, wire protocol and diagnostics are identical to
`@flonkid/kyc/core`; only the way you configure and call it differs.

> **Which path do I want?** React → `@flonkid/kyc`. Vue / Angular / Svelte /
> vanilla-TS **with** a bundler → `FlonkKYC` from `@flonkid/kyc/core`. No build
> step at all → this page. Native app or fully custom UI → [Direct API](/docs/direct-api).

---

## 1. Load and configure the tag

Configuration comes from `data-*` attributes on the script tag itself. They map
onto the same options the npm SDK takes — there is no separate loader-only
configuration.

| Attribute | Maps to | Default |
|---|---|---|
| `data-publishable-key` (alias `data-pk`) | `publishableKey` — your `pk_live_*` / `pk_sandbox_*`. Browser-safe. | none |
| `data-api` | `apiBase` — the REST base **including** the `/v1` suffix. | `https://api.flonk.id/v1` |
| `data-primary-color` | `colors.primaryColor` for `preview()` and `embed()` **only** — the live widget takes its branding from your key or session. | none |
| `data-overlay-color` | Any CSS color for the modal backdrop, alpha included. | dark translucent scrim |
| `data-email` | **Required** for `init()` and `redirect()`. The email of the person being verified; merged into `clientMetadata` as `email`. Pass it on the call instead if it is only known then. `preview()` and `embed()` never ask for it — they render mock data and reach no API. | none |
| `data-client-id` | Merged into `clientMetadata` as `clientId`. Optional. | none |
| `data-widget-url` | Origin the widget iframe is loaded from. Leave it unset in production. It exists because this script is served by the API, so — unlike the v1 loader — it cannot infer the widget origin from its own URL; set it only to point a page at a local or staging widget build. | the SDK's default |
| `data-prewarm` | `connect`, `intent`, `eager`, `none`. See [Prewarming](#prewarming). Unrecognised values are ignored. | `connect` |
| `data-debug` | Present (no value needed) → mirror SDK diagnostics to the console. | off |

Attributes not in this table are ignored.

Every attribute is a **default**: an argument you pass to `init()`, `preview()`,
`embed()` or `redirect()` wins over the tag. Only `data-api` is fixed at load —
it is read once, when the script constructs its client.

> **Pass `data-pk` even when your backend creates the session.** With the key on
> the tag the script resolves your brand color in parallel with session setup and
> paints it on the first frame; without it the loading screen is neutral grey
> until a round-trip completes. The key is publishable — it is meant to sit in
> page source.

## 2. Start a verification

The secret key never touches the browser on this path either. Your backend
creates the session; the page receives only `sessionId` + `embedToken`.

```html
<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-api="https://api.flonk.id/v1"></script>

<button id="verify">Verify identity</button>

<script>
  document.getElementById('verify').onclick = async () => {
    // Your authenticated backend creates the session with the SECRET key and
    // returns { sessionId, embedToken, qrCodeUrl }.
    const res = await fetch('/api/kyc/create-session', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + token }, // your app's session/JWT
    });
    const { sessionId, embedToken, qrCodeUrl } = await res.json();

    window.KYCWidget.init({
      sessionId,
      embedToken,
      qrCodeUrl, // without it the desktop -> mobile QR step cannot render
      // Required by init(): the email of the person being verified. Put it on
      // the tag as data-email instead when it is known at page render.
      clientMetadata: { email: user.email },
      onSuccess: (result) => console.log('Verified:', result),
      onError:   (error)  => console.error('Failed:', error),
      onCancel:  ()       => console.log('Cancelled'),
    });
  };
</script>
```

You can also let the script call your endpoint for you — pass `serverUrl`
instead of a session, exactly like the SDK's Option A:

```html
<script>
  window.KYCWidget.init({
    serverUrl: '/api/kyc/create-session',
    requestHeaders: { Authorization: 'Bearer ' + token },
    // Required by init(), here or as data-email on the tag.
    clientMetadata: { email: user.email },
    onSuccess: (result) => console.log('Verified:', result),
    onError:   (error)  => console.error('Failed:', error),
    onCancel:  ()       => console.log('Cancelled'),
  });
</script>
```

Your endpoint must respond with `{ sessionId, embedToken, qrCodeUrl }` — see
[Frontend & Backend → Backend](/docs/integration-frontend-backend#1-backend-create-session-endpoint).

> `onSuccess` firing does **not** mean the user is verified. Branch on
> `result.status` (`completed`, `manual_review`, `action_required`, `failed`) and
> confirm server-side from the [webhook](/docs/webhooks) or
> [`GET /v1/verifications/{sessionId}`](/docs/api-verification).

## 3. The `window.KYCWidget` surface

| Member | What it does |
|---|---|
| `init(config)` | Opens the widget in a full-screen modal. Takes `{ serverUrl }` **or** `{ sessionId, embedToken }` **or** `{ publishableKey }`, plus `lang`, `overlayColor`, `qrCodeUrl`, `clientMetadata`, `requestHeaders` and the `onSuccess` / `onError` / `onCancel` / `onReady` callbacks. Returns `{ iframe, destroy() }`. |
| `redirect(config)` | Navigates the whole page to the widget instead of framing it — the mode for in-app browsers, where the camera prompt has to come from a first-party origin. One-way: the page is gone, so only `onError` (failure *before* the navigation) can still fire. Pass `replace: true` to keep Back from returning here. |
| `preview(config)` | Renders the widget with **mock data and no camera**, for layout and branding checks. Creates no session. |
| `embed(config)` | The same preview, mounted into a container element of yours instead of a modal. **Preview only** — see below. |
| `version` | Version of the SDK this script was built from. |
| `noConflict()` | Restores whatever `window.KYCWidget` pointed at before this script loaded, and returns the Flonk object so you can keep a reference to it. Useful while the legacy loader is still on the page. |

### `embed()` renders a preview, not a verification

`embed()` mounts a themed **preview** — mock data, no camera, no session, no
result. It exists for dashboard-style "this is how the widget will look in your
brand colors" panels. It cannot verify anyone, and no callback will ever report
a verification from it.

There is no script-tag equivalent of the npm SDK's `mountInline()` — the mode
that runs a *live* verification inside your own layout. If you need a real
verification embedded in the page rather than in a modal, use the npm path with
a bundler. On this path, a real verification is `init()` (modal) or `redirect()`
(full page).

## Prewarming

The script warms the connection to the widget origin as soon as it runs. Raise
the level on a page where the click is likely:

```html
<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-prewarm="eager"></script>
```

| Value | What it warms |
|---|---|
| `connect` *(default)* | preconnect + idle prefetch of the loader/branding assets |
| `eager` | also pre-mounts a hidden iframe, so the full widget bundle is loaded before the click |
| `none` | nothing |

`intent` is accepted too, but it warms on hover/focus of a *trigger element*
that only the npm path can pass; from a script tag there is none, so it degrades
to idle warming — the same thing `connect` does.

## Content Security Policy

This path adds a script to *your* page, so `script-src` is a hard requirement
here — unlike the npm path, where a blocked loader script only costs you
dashboard-driven branding:

```
Content-Security-Policy:
  script-src  https://api.flonk.id;
  frame-src   https://verify.flonk.id;
  connect-src https://api.flonk.id;
```

If `script-src` blocks `api.flonk.id`, nothing runs at all: `window.KYCWidget`
is never defined and your `init()` call throws a `TypeError`.

The widget origin belongs in `frame-src` only — it hands your page no script.
`redirect()` needs neither, since it navigates your page instead of framing
anything.

> **`Permissions-Policy` is what breaks the camera**, not CSP. If your site
> sends a restrictive one, the iframe's `allow="camera;microphone"` delegation
> is refused and verification dies at the first capture step. See
> [Troubleshooting](/docs/troubleshooting#widget-loader-issues).

## Debugging

Add `data-debug` to the tag (or set `window.__FLONK_DEBUG__ = true` before the
widget opens) to mirror every SDK diagnostic to the console — blocked loader
script, prewarm skipped, no `READY` from the iframe, protocol mismatch. Silent
by default.

```html
<script src="https://api.flonk.id/v1/public/widget-v2.js"
        data-pk="pk_live_..."
        data-debug></script>
```

## Migrating from the legacy `widget.js`

Existing pages load `https://widget.flonk.id/v1/widget.js`. That loader keeps
working; the migration is a URL swap, because the global keeps its name and the
methods keep their signatures.

| | Legacy `widget.js` | `widget-v2.js` |
|---|---|---|
| URL | `https://widget.flonk.id/v1/widget.js` | `https://api.flonk.id/v1/public/widget-v2.js` |
| CSP | `script-src https://widget.flonk.id` | `script-src https://api.flonk.id` — the origin your policy already names for the loader and the API |
| Widget origin | derived from the script's own URL | the SDK default, `https://verify.flonk.id`; not settable from the tag |
| `data-api` | API **origin**, without `/v1` | full REST base, **with** `/v1` |
| `redirect()` | not available | available |
| `generateSecondaryColor()` | exposed on the global | removed — the widget derives the secondary color from your brand color itself |
| Everything else | `init`, `preview`, `embed`, `version`, `noConflict` | unchanged names and shapes |

Both scripts register `window.KYCWidget`. If a page ends up with both during a
migration, the second one to load wins; call `noConflict()` from the one you
don't want.


Embed the Flonk KYC widget on a page with no bundler: one script tag from api.flonk.id, configured with data-* attributes, driven through the window.KYCWidget global.

Script Tag (No Build Step)


Webhooks allow your server to receive real-time notifications about KYC verification status changes.

## What are Webhooks?

Webhooks are HTTP POST requests that Flonk sends to your server when verification events occur:

- `verification.completed` — Automated verification finished (AI/system decision). This same event also fires when a reviewer **approves** a session that was in [manual review](/docs/direct-api#manual-review). When **Proof of Address** is enabled in the project settings with **Wait for PoA result in real time** turned **on**, this event already contains the final `poaStatus`. With the toggle **off**, `verification.completed` fires after the identity step and a follow-up `verification.updated` arrives later with the PoA outcome — see [Proof of Address](/docs/proof-of-address) for the full flow.
- `verification.status_changed` — A status change made by an admin from the dashboard **or** as the outcome of [manual review](/docs/direct-api#manual-review): the reviewer decision (`approved` / `rejected`; a rejection carries `rejection_reason` and `reviewed_by`), an **automatic** rejection taken by the checks themselves (`rejected` with a machine-readable `rejection_reason` and no `reviewed_by`), **and** — informational only — the moment a session *enters* `manual_review` or `action_required` (the latter carries the additive `next_action` field). The informational entry events let your KYC page show a "verification pending" state without polling.
- `verification.updated` — Verification data was manually edited by admin (document fields, uploaded files), **or** the asynchronous PoA review finished (delivers `poaStatus` and `poaConfidenceScore`).

> **Review entry is now announced.** When automated checks route a session to `manual_review` or `action_required`, an **informational** `verification.status_changed` fires with that `newStatus` (no decision yet). The final outcome still arrives later: approval fires `verification.completed`; rejection fires `verification.status_changed` with `status: "rejected"`. These entry events are additive — integrators that only handle the reviewer decision can ignore them.

## Setup

### 1. Create endpoint in your application

<CodeTabs
  items={[
    { label: 'Node.js (SDK)', snippetId: 'backend/sdk-webhook-verify' },
    { label: 'Python', snippetId: 'backend/python-webhook' },
    { label: 'Java', snippetId: 'backend/java-webhook' },
    { label: 'Go', snippetId: 'backend/go-webhook' },
    { label: 'Rust', snippetId: 'backend/rust-webhook' },
  ]}
/>

### 2. Configure URL in Flonk Dashboard

1. Go to [Flonk Dashboard](https://panel.flonk.id)
2. Select **Settings** → **Webhooks**
3. Add your endpoint URL: `https://yourdomain.com/api/kyc/webhook`
4. Save and get your **webhook secret**

## Webhook Payload Format

All webhook payloads follow this structure:

```json
{
  "id": "evt_1234567890",
  "type": "verification.completed",
  "created": 1640995200,
  "livemode": true,
  "data": {
    "object": {
      "id": "verification_attempt_id",
      "client_id": "user_1761052168279",
      "client_metadata": {},
      "status": "completed",
      "confidence": 0.9442,
      "document_type": "id_card",
      "extracted_data": {
        "full_name": "JOHN DOE",
        "first_name": "JOHN",
        "last_name": "DOE",
        "date_of_birth": "1990-01-15",
        "nationality": "UKR",
        "sex": "M"
      },
      "duplicate_verification": {
        "is_duplicate": true,
        "previous_verification_id": "cmohkbzfq000686fezoudgcuc",
        "previous_verified_at": "2026-04-27T19:01:03.000Z",
        "match_type": "document_number",
        "similarity_score": 1
      },
      "created_at": "2025-10-21T13:10:10.584Z",
      "test_mode": false
    }
  }
}
```

The signature is sent in the headers (not in the body). Flonk sends **two**,
both HMAC-SHA256 with your webhook secret:

```
X-Signature: t=1700000000, v1=abc123...     ← also replay-protected (signed timestamp)
X-Signature-256: sha256=def456...           ← HMAC of the body
X-Event-Type: verification.completed
X-Event-Id: evt_1234567890
```

**Both are fully valid signatures** — both prove the request came from Flonk and
the body wasn't tampered with. The only difference: `X-Signature` also signs a
timestamp, so a captured request is rejected outside the skew window (default
5 min) — i.e. replay protection. `X-Signature-256` has no timestamp, so a
captured request stays valid; close that gap by [deduping on `event.id`](#1-idempotency)
(recommended anyway). Prefer `X-Signature` when you want replay protection at the
signature layer; `X-Signature-256` is perfectly safe for authenticity + integrity.

## Event Types

### `verification.completed`
Sent when automated verification finishes (AI/system decision). Status is always `completed`.

#### Duplicate verification signal

When a verification completes successfully, Flonk checks whether the same document or person was already verified in the same project. If a match is found, the `verification.completed` webhook includes an optional `duplicate_verification` object.

This is a signal for your own risk logic. Flonk still completes the verification normally; your application decides whether to allow the user, block the user, send the case to manual review, or apply a custom threshold.

Duplicate checks are scoped to a project. The same person or document can be verified in a different project without being marked as a duplicate for your project.

Example:

```json
{
  "duplicate_verification": {
    "is_duplicate": true,
    "previous_verification_id": "cmohkbzfq000686fezoudgcuc",
    "previous_verified_at": "2026-04-27T19:01:03.000Z",
    "match_type": "document_number",
    "similarity_score": 1
  }
}
```

Fields:

| Field | Type | Description |
|-------|------|-------------|
| `is_duplicate` | `boolean` | Always `true` when the object is present |
| `previous_verification_id` | `string` | ID of the earlier successful verification in the same project |
| `previous_verified_at` | `string` | ISO 8601 timestamp of the earlier verification |
| `match_type` | `"document_number" \| "personal_data"` | How the duplicate was detected |
| `similarity_score` | `number` | Match confidence from `0.0` to `1.0` |

`match_type` values:

| Value | Meaning | Typical score |
|-------|---------|---------------|
| `document_number` | Exact blind-index match on the document number. This usually means the same physical document was used before. | `1.0` |
| `personal_data` | Blind-index match on last name + date of birth. This can catch the same person using another document type, for example passport first and ID card later. | `0.95` |

When no duplicate is detected, `duplicate_verification` is omitted from the webhook payload.

### `verification.status_changed`
Sent when a verification's `status` changes. Two kinds of change use this event:

- **Reviewer decision** — `status` is `approved` or `rejected`, made by an admin from the dashboard or as the outcome of [manual review](/docs/direct-api#manual-review). A rejection carries `rejection_reason` and `reviewed_by`; `previous_status` is `manual_review`.
- **Automatic rejection** — `status` is `rejected` with `previous_status: "processing"` and no `reviewed_by`: the checks reached a verdict no review could change, so the session was never queued. `rejection_reason` is a machine-readable code — today only `DOCUMENT_EXPIRED` (the document is past its expiry date; the holder needs a new one and must start a new session).
- **Review entry (informational)** — `status` is `manual_review` or `action_required`, fired the moment automated checks route the session there. No decision has been made yet; `previous_status` is `processing`. An `action_required` entry additionally carries `next_action` (`resubmit_front` / `resubmit_back`). These entry events are additive — ignore them if you only act on the final decision.

> A manual-review **approval** does **not** use this event — it fires `verification.completed` instead. Only rejections (reviewer or automatic) and the informational review-entry events above arrive as `verification.status_changed`.

Additional fields in `data.object`:

| Field | Type | Description |
|-------|------|-------------|
| `previous_status` | `string` | Status before the change (e.g. `completed`, `manual_review`, `processing`) |
| `rejection_reason` | `string?` | Reason for rejection (only when `status` is `rejected`) — free text from a reviewer, or a code such as `DOCUMENT_EXPIRED` from an automatic rejection |
| `reviewed_by` | `string?` | Identifier of who made the decision (admin email or reviewer role); absent on an automatic rejection |
| `next_action` | `string?` | On an `action_required` entry: the side to re-upload — `resubmit_front` or `resubmit_back` |

```json
{
  "id": "evt_1234567891",
  "type": "verification.status_changed",
  "created": 1640995300,
  "livemode": true,
  "data": {
    "object": {
      "id": "verification_attempt_id",
      "client_id": "user_1761052168279",
      "status": "rejected",
      "confidence": 0.95,
      "document_type": "passport",
      "extracted_data": {
        "full_name": "JOHN DOE",
        "first_name": "JOHN",
        "last_name": "DOE"
      },
      "previous_status": "completed",
      "rejection_reason": "Document expired",
      "reviewed_by": "admin@company.com",
      "created_at": "2025-10-21T13:10:10.584Z"
    }
  }
}
```

### `verification.updated`
Sent when an admin manually edits verification data (document fields, uploads new files) from the dashboard.

Additional fields in `data.object`:

| Field | Type | Description |
|-------|------|-------------|
| `updated_at` | `string` | ISO 8601 timestamp of the update |
| `updated_by` | `string?` | Email of the admin who made the edit |
| `extracted_data` | `object` | Updated extracted data (`issue_date`, `expiry_date`, `place_of_birth`, …). `document_number` is **not** included — see the note below. |

```json
{
  "id": "evt_1234567892",
  "type": "verification.updated",
  "created": 1640995400,
  "livemode": true,
  "data": {
    "object": {
      "id": "verification_attempt_id",
      "client_id": "user_1761052168279",
      "status": "completed",
      "document_type": "passport",
      "extracted_data": {
        "full_name": "JOHN DOE",
        "first_name": "JOHN",
        "last_name": "DOE",
        "date_of_birth": "1990-01-15",
        "nationality": "UKR",
        "sex": "M",
        "issue_date": "2020-01-01",
        "expiry_date": "2030-01-01",
        "place_of_birth": "Kyiv"
      },
      "created_at": "2025-10-21T13:10:10.584Z",
      "updated_at": "2026-03-31T12:00:00.000Z",
      "updated_by": "admin@company.com",
      "test_mode": false
    }
  }
}
```
### Handling Event Types

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

switch (event.type) {
  case 'verification.completed':
    // Automated AI decision
    await handleAutomatedVerification(event.data.object);
    break;
  case 'verification.status_changed':
    // Admin manual decision
    await handleAdminDecision(event.data.object);
    break;
  case 'verification.updated':
    // Admin edited verification data
    await handleDataUpdate(event.data.object);
    break;
}
```

## Signature Verification (Security)

**Important:** Always verify webhook signature for security!

### Using the SDK (Recommended)

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

const flonk = new FlonkKYCServer({
  secretKey: process.env.FLONK_SECRET_KEY!,
});

// Automatically detects signature format (t=,v1= or sha256=)
const event = flonk.webhooks.constructEvent(
  rawBody,          // raw request body as string
  signatureHeader,  // X-Signature header (recommended) or X-Signature-256
  webhookSecret,    // your webhook secret
);

console.log(event.type);            // 'verification.completed', 'verification.status_changed', or 'verification.updated'
console.log(event.data.object.id);  // verification ID
```

### Manual Verification

If you verify without the SDK, use a **constant-time** comparison —
`===` on the signature string leaks how many leading characters matched via
timing and is exploitable. Use `crypto.timingSafeEqual`:

```typescript
import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');

  // Constant-time compare. HMAC both sides so the buffers are equal length
  // regardless of input, then timingSafeEqual — no early length/return branch.
  const key = crypto.randomBytes(32);
  const a = crypto.createHmac('sha256', key).update(signature).digest();
  const b = crypto.createHmac('sha256', key).update(expected).digest();
  return crypto.timingSafeEqual(a, b);
}
```

> Prefer the SDK's `constructEvent` — it does exactly this for you and also
> handles the timestamped `t=,v1=` format.

## Best Practices

### 1. Idempotency

Flonk delivers **at-least-once** (see [Retry Logic](#3-retry-logic)), so the same
event can arrive more than once. **Dedupe by `event.id`** — store the ids you've
processed and skip ones you've already seen. This is the same pattern you'd use
for Stripe; keep it in your own durable store, separate from the signature check.

A unique index on the event id (atomic, durable) is the simplest:

```typescript
app.post('/api/kyc/webhook', async (req, res) => {
  const event = flonk.webhooks.constructEvent(req.rawBody, req.headers['x-signature'], secret);

  try {
    await db.webhookEvents.create({ data: { eventId: event.id } }); // unique constraint
  } catch (e) {
    if (isUniqueViolation(e)) return res.status(200).end(); // already processed
    throw e;
  }

  await processWebhook(event);
  res.status(200).end();
});
```

Or with Redis — `SET NX` returns null when the key already existed:

```typescript
const fresh = await redis.set(`whk:${event.id}`, '1', 'PX', 6 * 60_000, 'NX');
if (fresh === null) return res.status(200).end(); // retry — already handled
```

### 2. Quick Response
Respond quickly (< 5 seconds), process asynchronously:

```typescript
@Post('webhooks/flonk')
async handleWebhook(@Body() payload: any) {
  // Quick validation
  if (!this.verifySignature(payload)) {
    throw new UnauthorizedException();
  }

  // Add to processing queue
  await this.queue.add('process-webhook', payload);

  // Respond immediately
  return { received: true };
}
```

### 3. Retry Logic

Flonk makes up to **8 delivery attempts** per event: the first immediately, then
one every **5 minutes** — a flat interval, not exponential backoff. So the last
attempt lands roughly 35 minutes after the first.

| Setting | Value |
|---------|--------------|
| Attempts | 8 (1 immediate + 7 retries) |
| Interval | 5 minutes, flat |
| Per-attempt timeout | 30 seconds |
| Counts as delivered | any `2xx` |
| Retried | any other status, plus timeouts and connection errors |
| Never retried | `400` and `401` — we read those as "this endpoint will never accept it" |

After the 8th failed attempt the delivery is marked **dead** and stops on its
own. Dead and failed deliveries can be replayed by hand from **Settings →
Webhooks** in the [dashboard](https://panel.flonk.id), optionally against a
different URL — a replay sends the original body, so your signature check still
passes.

Because a slow endpoint burns attempts, respond `200` first and process
afterwards (see [Quick Response](#2-quick-response)).

### 4. Logging
Log all received webhooks. The fields live on the event, not on a wrapper:

```typescript
logger.info('Webhook received', {
  eventId: event.id,               // 'evt_...' — also the X-Event-Id header
  type: event.type,                // 'verification.completed'
  verificationId: event.data.object.id,
  clientId: event.data.object.client_id,
  created: event.created,          // Unix seconds
});
```



Setup and handle webhook notifications from Flonk KYC

Webhooks

Run the full KYC flow with plain REST calls — no widget, no SDK: create a session, upload documents, upload the face, submit, receive the webhook or poll the result.

Direct API (No SDK)


Notable changes to the Flonk KYC platform and the official SDK. Dates are in
UTC. The SDK follows [semantic versioning](https://semver.org/).

---

## Platform

### 2026-06 — API versioning + idempotency

- **Date-pinned API versioning.** Requests may send a `Flonk-Version` header;
  the server resolves it (absent/unknown → current baseline), echoes it back, and
  the API is additive-only within a version. Lays the rails for future breaking
  changes without breaking deployed clients. No behaviour change for existing
  callers.
- **Idempotent session creation.** `POST /v1/sessions` accepts an
  `Idempotency-Key` header — a retry returns the original session instead of a
  duplicate (concurrent in-flight retry → `409`). Keys scoped per project, 24h.

### 2026-06 — Replay-protected webhook signatures

- **Webhooks now include a timestamped `X-Signature` header** (`t=<unix>, v1=<hex>`)
  in addition to the existing `X-Signature-256` (`sha256=`). The timestamp is
  signed, so a captured request is rejected once it's outside the skew window
  (5 min) — real replay protection. `X-Signature-256` is unchanged and stays for
  backward compatibility; existing integrations keep working. Verify either with
  the SDK's `constructEvent`, and dedupe retries by `event.id`.

### 2026-05 — Faster widget theming

- **Design tokens are now cached in Redis per project.** The
  `GET /public/design-tokens` endpoint — the widget's first, blocking request —
  previously ran a database join on every widget load. It now serves from a
  Redis cache (5-minute TTL) keyed by project, with the cache invalidated
  automatically whenever a project's branding color changes. The widget's brand
  color resolves from a sub-millisecond cache read on the hot path.

---

## SDK

The browser/Node package published as
[`@flonkid/kyc`](https://www.npmjs.com/package/@flonkid/kyc).

### 2.0.0

**Breaking — read this before upgrading.**

- **`verify.flonk.id` is the default widget origin.** An integration that never
  passed `widgetUrl` was rendering the previous widget and now renders
  widget-v2: different capture UX, auto-capture and face detection. No exported
  signature moved, which is exactly why this is a major — it would otherwise
  arrive silently on an `npm update`. Pin
  `new FlonkKYC({ widgetUrl: 'https://widget.flonk.id' })` to stay where you
  were. If you already set `widgetUrl`, nothing changes for you.
- **The CSP block changed, and it is not a rename.** `frame-src` names
  `verify.flonk.id`; `script-src` names `api.flonk.id` only — the widget origin
  hands the host page no script and is **removed** from that directive, not
  renamed; `img-src` is gone entirely because both loaders draw the spinner with
  `createElementNS` and fetch no image. Copy the block from the
  [README](https://www.npmjs.com/package/@flonkid/kyc) rather than editing the
  old one in place.
- **`Permissions-Policy` is documented for the first time.** It is the most
  common cause of a camera that never starts on an otherwise correct
  integration: the SDK delegates `camera` to the frame, but `allow` can only
  hand down what the host page holds. Not new behaviour — it worked this way on
  the previous widget too — but it now appears where a 2.0 upgrader will read it.

**Added**

- **A `<script>` tag build.** `GET /v1/public/widget-v2.js` registers
  `window.KYCWidget` and reads its configuration from `data-*` attributes, so a
  site with no build step can integrate. `data-email` is required — the person
  being verified has to be named.
- **A live inline mount.** `mountInline()` runs a real verification inside your
  own layout — same session flows, same wire — with no overlay, no scroll lock
  and no z-index takeover. Not to be confused with `embed()`, which is a themed
  mock for dashboards.
- **`redirect()`** sends the whole page to the widget, creating the session
  first so a failing backend surfaces through `onError` before the page is left.
  For in-app browsers and WebViews, where a first-party origin is far likelier
  to be granted the camera than an iframe.

**Fixed**

- **The modal was an invisible sheet over a page that looked live.** Nothing
  painted a backdrop once the loader was destroyed at reveal, so the host page
  sat bright and apparently interactive under a sheet that swallowed every
  click. There is now one scrim, alive from open to close, carrying the dialog
  semantics and the focus ring — and it owns the body-scroll lock, which two
  places used to fight over and leave the host page permanently fixed after
  close.
- **The loader painted Flonk's own brand colour on the merchant's page** before
  the project's colour resolved, and a later fix stopped an unknown colour from
  overwriting the one the server had already baked in.
- **Two of four subpaths shipped no type declarations** (`/server` and
  `/types` — a race in the build's clean step), and `require.types` pointed at
  ESM declarations, so a CJS consumer under `node16` hit TS1479.
- **The server client refused the one key shape that enables test mode.**
- **The desktop modal hid 136 px of every content-heavy screen.**
- **`prewarm` at level `intent` behaved like `eager` when given no trigger** —
  it loaded the full widget bundle on every page view instead of degrading to
  `connect`. The script-tag path cannot supply a trigger at all, so every page
  that asked for the middle level was silently getting the heaviest one. Its
  design-token prefetch was also requesting a URL that had 404'd since it was
  written, so that half of prewarm never warmed anything.

### 1.9.4

- **Faster widget start — dropped a redundant token round-trip.** In the
  `serverUrl` and `sessionId`+`embedToken` flows the SDK passed the embed token to
  the widget iframe only as `token`, not `embedToken`. The widget keys its fast
  path on the `embedToken` param, so without it it fell back to a deprecated
  server exchange — an extra `POST /public/session/:id/token` before verification
  could start. The SDK now sends `embedToken` too (as the classic `widget.js`
  loader already did), so the widget initializes directly and that request is
  gone. No integration changes needed.

### 1.9.3

- **New: `@flonkid/kyc/core` — a React-free entry.** The default `@flonkid/kyc`
  entry re-exports the `FlonkKYCWidget` React component, so it imports `react`.
  In a **non-React** project (Vue, Angular, Svelte, vanilla) that has no `react`
  installed, that broke the production bundler build. Import the `FlonkKYC` class
  from **`@flonkid/kyc/core`** instead — same class, zero React, zero config.
  Fully **additive** — React users keep importing from `@flonkid/kyc` unchanged.
  See [Frontend SDK → Other frameworks](/docs/frontend-sdk#other-frameworks--the-flonkkyc-class).

### 1.9.2

- **Fixed: desktop→mobile QR didn't render in the `serverUrl` flow.** The SDK
  now forwards `qrCodeUrl` to the widget. Your create-session endpoint should
  respond with `{ sessionId, embedToken, qrCodeUrl }` (the `sessionId` + `embedToken`
  flow can also pass `qrCodeUrl` in `init`). Previously only the classic
  `widget.js` loader passed it.
- **Docs:** clarified that the `serverUrl` endpoint must return `{ sessionId,
  embedToken }` (the API's `id` mapped to `sessionId`) — returning the raw session
  object silently broke the widget at the welcome step.

### 1.9.1

- **Observability — `onDiagnostic` hook.** The SDK now emits a structured
  diagnostic at every degradation/branch point (loader fallback, blocked loader
  script, prewarm skipped, ready-timeout reveal, protocol mismatch) instead of
  failing silently. Pass `onDiagnostic`, or set `window.__FLONK_DEBUG__ = true`
  to mirror events to the console. Zero-cost when unused. See
  [Frontend SDK → Debugging](/docs/frontend-sdk#debugging).
- **Versioned SDK ⇄ iframe contract.** The wire between the SDK and the widget
  iframe is now versioned (`PROTOCOL_VERSION`) separately from the package
  version and is **additive-only**, so any SDK build stays compatible with any
  iframe build. A `PROTOCOL_VERSION_MISMATCH` diagnostic surfaces a stale-cached
  widget.
- **Webhooks — added a replay-protected signature.** Flonk now also sends a
  timestamped `X-Signature` (`t=,v1=`) header alongside `X-Signature-256` (both
  HMAC-SHA256 with your secret). The signed timestamp adds replay protection
  (old requests rejected outside the skew window); `X-Signature-256` stays fully
  valid for authenticity + integrity. `constructEvent` verifies either. Signature
  comparison is now branchless constant-time. Dedupe retries by `event.id` in
  your own store — see [Webhooks → Idempotency](/docs/webhooks#1-idempotency).

### 1.9.0

- **Self-prewarming.** New static `FlonkKYC.prewarm({ level })` — preconnect +
  idle asset prefetch, with `level:'intent'` (warm on hover/focus/in-view) and
  `level:'eager'` (pre-mount a hidden iframe so the full bundle loads before the
  click). The classic `widget.js` loader self-prewarms on load
  (`data-prewarm="eager"` for the eager level). Never pre-creates a session;
  SSR-safe. See [Frontend SDK → Performance](/docs/frontend-sdk#performance-prewarming).
- **Server-hosted loader.** The branded loading screen is now served from the
  API (`/v1/public/loader.js`) so it can be restyled and fixed for all
  integrations **without** a client SDK bump. The SDK falls back to its bundled
  loader if the script is blocked (CSP/CORP/offline).
- **Fixed: loader could hang on "Initialisierung…".** The widget signalled
  `READY` from a `requestAnimationFrame` callback, which the browser pauses for
  a hidden/backgrounded iframe — deadlocking the reveal for some users. `READY`
  is now driven by timers only, and the SDK reveals on a safety timeout even if
  `READY` is missing, so a permanent stuck loader can't happen.

### 1.7.0

- **Fixed: `React is not defined` under SSR / Turbopack.** The build emitted bare
  `React.createElement(...)` calls without importing React, which crashed in
  environments without a global `React` (Next.js App Router, Turbopack runtime).
  The bundle now compiles JSX with React's **automatic runtime**
  (`react/jsx-runtime`), so no `globalThis.React` shim is needed. `react` and
  `react/jsx-runtime` remain peer/external — your app's React is used.
- **Improved: instant branding now works in the `sessionId` + `embedToken`
  flow.** Previously `publishableKey` only sped up branding in the `serverUrl`
  flow; in the manual-session flow it was ignored and branding waited on the
  session request. Now, when `publishableKey` is supplied, the SDK resolves the
  brand color from the key **in parallel** with the session (raced against an
  800 ms budget, color updated in place when full tokens arrive) — matching the
  `serverUrl` fast path.
- **Docs:** `WidgetInitConfig.publishableKey` JSDoc updated to describe instant
  branding in both flows.

### 1.5.1

- Fixed branded loader not appearing after the `serverUrl` session resolved.

### 1.5.0

- Added the `requestHeaders` prop to send authentication headers (e.g. a JWT)
  with the `serverUrl` POST request.
- Introduced `publishableKey`-driven instant branded loader for the `serverUrl`
  flow.

### 1.4.x

- `1.4.2` — Hardened against double initialization in React StrictMode using a
  generation counter.
- `1.4.1` — Surface server error bodies; show errors in the loader for the
  `serverUrl` flow instead of failing silently.
- `1.4.0` — Replaced loose `any` types with precise types across the SDK;
  aligned `onSuccess` to emit a typed `VerificationResult`.

---

See the [Frontend SDK](/docs/frontend-sdk) guide for current usage.


Release notes for the Flonk KYC platform and the @flonkid/kyc SDK.

Changelog


# Authentication

Flonk KYC uses secret keys to authenticate server-side API requests. Manage your API keys in the [Flonk Dashboard](https://dashboard.flonk.id).

## API Keys

Each key belongs to a **project environment**. Manage them in
[Dashboard → API Keys](https://dashboard.flonk.id).

| Key | Where | Use |
|-----|-------|-----|
| **Publishable** `pk_live_*` / `pk_sandbox_*` | Browser | Loads project branding; safe to expose. |
| **Secret** `sk_live_*` / `sk_sandbox_*` | Server only | Creates sessions, authenticates the API. |

> **Never expose a secret key** (`sk_*`) in client-side code.

## Secret Key Authentication

### Using the SDK (Recommended)

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

const flonk = new FlonkKYCServer({
  secretKey: process.env.FLONK_SECRET_KEY!,
});

// SDK handles Authorization header automatically
const session = await flonk.createSession({
  clientMetadata: { email: 'user@example.com' },
});
```

### Manual (fetch)

```typescript
const response = await fetch('https://api.flonk.id/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientMetadata: { email: 'user@example.com' }
  })
});
```

## API Versioning

The REST API is versioned by date, pinned with an optional `Flonk-Version`
request header (the SDK sends the version it was built against automatically):

```
Flonk-Version: 2026-06-01
```

The API is **additive-only within a version** — new optional fields and
endpoints never change behaviour for existing callers. A genuinely breaking
change would ship under a **new** date, and requests pinned to the older date
keep getting the old response shape. Omitting the header resolves to the current
version. The server echoes the resolved version in the `Flonk-Version` response
header.

## Install SDK

```bash
npm install @flonkid/kyc
# or
yarn add @flonkid/kyc
```

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

## Environment Variables

Configure your keys in environment variables:

```bash
# Server-side (never expose to frontend)
FLONK_SECRET_KEY=sk_live_xxxxxxxxxxxx
FLONK_API_URL=https://api.flonk.id/v1
FLONK_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
```

## Security Best Practices

- **Never expose secret keys** in frontend code, git repositories, or logs
- **Use environment variables** to store keys
- **Rotate keys regularly** if you suspect a leak
- **Use test keys** (`sk_test_*`) for development

## Rate Limits

| Endpoint | Rate Limit |
|----------|------------|
| Create Session | 100 req/min |
| Get Session | 500 req/min |
| Webhooks | Unlimited |

If you exceed rate limits, you'll receive a `429 Too Many Requests` response.






Authentication


# Error Handling

Flonk API uses standard HTTP status codes and returns detailed error information.

## Error Response Format

Error bodies are flat. `statusCode` and `message` are always present; `code` is a
stable, machine-branchable identifier present on the documented failures below
(and expanding over time):

```json
{
  "statusCode": 404,
  "code": "session_not_found",
  "message": "Session sess_123 not found or does not belong to your project",
  "timestamp": "2026-06-03T00:00:00.000Z"
}
```

Branch on `code`, not on `message` text (messages may change; codes are stable).

## HTTP Status Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid or missing API key |
| `403` | Forbidden - Access denied |
| `404` | Not Found - Resource doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error |

## Error Codes

### Authentication Errors

| Code | Description |
|------|-------------|
| `invalid_api_key` | API key is invalid or expired |
| `missing_api_key` | Authorization header is missing |
| `insufficient_permissions` | Key doesn't have required permissions |

### Session Errors

| Code | Status | Description |
|------|--------|-------------|
| `session_not_found` | 404 | Session ID doesn't exist or isn't in your project |
| `session_expired` | 400 | Session has passed its expiry |
| `session_invalid_state` | 400 | Session can't be used/updated in its current state (completed/failed/non-pending) |

The `code` field is also exposed by the SDK as `error.code` (typed
`FlonkErrorCode`, an open union) — see below.

## Handling Errors

### Using the SDK

The SDK throws typed error classes that you can catch and handle:

```typescript
import { FlonkKYCServer } from '@flonkid/kyc/server';
import {
  FlonkAuthenticationError,
  FlonkValidationError,
  FlonkAPIError,
} from '@flonkid/kyc/types';

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

try {
  const session = await flonk.createSession({
    clientMetadata: { email: 'user@example.com' },
  });
} catch (error) {
  if (error instanceof FlonkAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof FlonkValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof FlonkAPIError) {
    // Branch on the stable code, not the message text.
    switch (error.code) {
      case 'session_not_found': /* … */ break;
      case 'session_expired':   /* re-create the session */ break;
      default: console.error(`API error ${error.statusCode}:`, error.message);
    }
  }
}
```

`error.code` is typed `FlonkErrorCode` (an open union), so a `switch` stays
type-safe while tolerating codes added later.

### Manual (fetch)

```typescript
try {
  const response = await fetch('https://api.flonk.id/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${secretKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        console.error('Invalid API key');
        break;
      case 429:
        console.error('Rate limited, retry later');
        break;
      default:
        console.error('API error:', error.error.message);
    }
  }
} catch (error) {
  console.error('Network error:', error);
}
```

## Retry Strategy

**The SDK retries transient errors (429 / 5xx / network) for you** with jittered
exponential backoff, honouring `Retry-After`. GETs always retry; writes retry
only when idempotent. Tune or disable via `new FlonkKYCServer({ maxRetries })`.

If you call the API manually, implement backoff yourself:

```typescript
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000;
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    return response;
  }
  throw new Error('Max retries exceeded');
}
```






Errors


# Sessions API

Sessions are the core of KYC verification. Create a session on your backend, then initialize the widget on your frontend — or drive the whole flow yourself via the [Direct API](/docs/direct-api).

## Using the SDK

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

const flonk = new FlonkKYCServer({
  secretKey: process.env.FLONK_SECRET_KEY!,
});

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

// Get session
const details = await flonk.getSession(session.id);

// Update session
await flonk.updateSession(session.id, {
  clientMetadata: { email: 'updated@example.com' },
});
```

---

## REST API Reference

### Create Session

**POST** `/v1/sessions`

Creates a new KYC verification session.

#### Request

```json
{
  "clientMetadata": {
    "email": "user@example.com",
    "userId": "user_123",
    "name": "John Doe"
  },
  "language": "de",
  "expiryMinutes": 30
}
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `clientMetadata` | object | No | Custom data to associate with session |
| `clientMetadata.email` | string | No | User email (recommended for webhook matching) |
| `clientMetadata.userId` | string | No | Your internal user ID |
| `clientMetadata.name` | string | No | User display name |
| `language` | string | No | Widget language: `en`, `de`, `uk` (default: `de`) |
| `expiryMinutes` | number | No | Session expiry in minutes, 1-60 (default: 5) |

> **Note:** All `clientMetadata` fields are optional. Pass any key-value pairs you need — they are returned in webhook events, so you can match verifications to your users.

#### Idempotency

Send an optional `Idempotency-Key` header to make a create safely retriable: a
retry with the same key returns the **original** session instead of creating a
duplicate (a concurrent retry while the first is still in flight gets `409`).
Keys are scoped to your project and remembered for 24h. The Node SDK sets one
automatically, so `createSession` retries can never duplicate.

```
Idempotency-Key: 6f0c…-uuid
```

#### Response

```json
{
  "id": "clxxxxxxxxxxxxxxxxx",
  "embedToken": "eyJhbGciOi...",
  "status": "pending",
  "expiresAt": "2026-01-15T12:30:00Z",
  "createdAt": "2026-01-15T12:00:00Z",
  "widgetUrl": "https://verify.flonk.id/?sessionId=...",
  "qrCodeUrl": "https://verify.flonk.id/?sessionId=...",
  "allowManualUpload": false,
  "testMode": false
}
```

### Get Session

**GET** `/v1/sessions/{sessionId}`

Retrieves details of an existing session.

#### Response

```json
{
  "id": "clxxxxxxxxxxxxxxxxx",
  "status": "completed",
  "clientMetadata": {
    "email": "user@example.com",
    "userId": "user_123"
  },
  "createdAt": "2026-01-15T12:00:00Z",
  "expiresAt": "2026-01-15T12:30:00Z",
  "updatedAt": "2026-01-15T12:05:00Z"
}
```

## Session Statuses

| Status | Description |
|--------|-------------|
| `pending` | Session created, waiting for user to open widget |
| `connected` | User opened the widget |
| `processing` | Documents uploaded, AI verification in progress |
| `completed` | Verification finished and approved (check webhook for result) |
| `failed` | Verification failed — reopens for resubmission within TTL (see [Direct API](/docs/direct-api#resubmission-after-a-failed-attempt)) |
| `expired` | Session expired before completion |
| `manual_review` | Automated checks were inconclusive; a human reviewer is deciding. Frozen: does not expire on TTL and rejects further uploads. See [Manual review](/docs/direct-api#manual-review) |
| `rejected` | A reviewer rejected the verification. Closed permanently — create a new session |


Create and manage KYC verification sessions

Sessions


# Verification API

After a user completes KYC, you receive verification results via webhooks or by polling `GET /v1/verifications/{sessionId}` with your secret key — see [Direct API → Getting the result](/docs/direct-api#getting-the-result).

## Verification Object

```typescript
{
  "id": "ver_xxxxxxxxxxxxxxxx",
  "sessionId": "ses_xxxxxxxxxxxxxxxx",
  "status": "approved",
  "confidence": 0.98,
  "documentType": "id_card",
  "extractedData": {
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-15",
    "documentNumber": "L01X00T47",
    "nationality": "DE",
    "sex": "M",
    "expiryDate": "2029-05-14"
  },
  "clientMetadata": {
    "email": "user@example.com",
    "userId": "user_123"
  },
  "createdAt": "2024-01-15T12:05:00Z"
}
```

## Verification Statuses

| Status | Description |
|--------|-------------|
| `approved` | Identity verified successfully |
| `rejected` | Verification failed |

## Extracted Data Fields

| Field | Description |
|-------|-------------|
| `fullName` | Complete name from document |
| `firstName` | First/given name |
| `lastName` | Last/family name |
| `dateOfBirth` | Date of birth (YYYY-MM-DD) |
| `documentNumber` | Document ID number |
| `nationality` | Nationality code (ISO 3166-1 alpha-2) |
| `sex` | Sex: `M`, `F`, or `X` |
| `expiryDate` | Document expiry date |

## Confidence Score

The `confidence` field (0.0 - 1.0) indicates verification reliability:

| Score | Meaning |
|-------|---------|
| 0.95 - 1.0 | High confidence |
| 0.80 - 0.94 | Medium confidence |
| < 0.80 | Low confidence |

## Webhook Events

### `verification.completed`

When automated verification completes, you receive:

```typescript
{
  "type": "verification.completed",
  "data": {
    "object": {
      "id": "ver_xxxxxxxxxxxxxxxx",
      "status": "completed",
      "confidence": 0.98,
      "extracted_data": { ... },
      "duplicate_verification": {
        "is_duplicate": true,
        "previous_verification_id": "cmohkbzfq000686fezoudgcuc",
        "previous_verified_at": "2026-04-27T19:01:03.000Z",
        "match_type": "document_number",
        "similarity_score": 1
      },
      "client_metadata": { ... }
    }
  }
}
```

`duplicate_verification` is optional. It is included only when Flonk detects that the same document or person was already successfully verified in the same project. The verification still completes normally; use this signal for your own fraud prevention, manual review, or account-linking logic. See [Webhooks](/docs/webhooks#duplicate-verification-signal) for field details.

### `verification.status_changed`

When a verification is approved or rejected — by an admin from the dashboard, or when a [manual review](/docs/direct-api#manual-review) is **rejected** (a manual-review approval fires `verification.completed` instead). For a rejected manual-review session `previous_status` is `manual_review`:

```typescript
{
  "type": "verification.status_changed",
  "data": {
    "object": {
      "id": "ver_xxxxxxxxxxxxxxxx",
      "status": "approved",       // or "rejected"
      "confidence": 0.98,
      "extracted_data": { ... },
      "previous_status": "completed",
      "rejection_reason": "...",  // only for rejected
      "reviewed_by": "admin@company.com"
    }
  }
}
```

### `verification.updated`

When an admin manually edits verification data (document fields, file uploads):

```typescript
{
  "type": "verification.updated",
  "data": {
    "object": {
      "id": "ver_xxxxxxxxxxxxxxxx",
      "status": "completed",
      "document_type": "passport",
      "extracted_data": {
        "full_name": "John Doe",
        "document_number": "AB1234567",
        "issue_date": "2020-01-01",
        "expiry_date": "2030-01-01"
      },
      "updated_at": "2026-03-31T12:00:00.000Z",
      "updated_by": "admin@company.com"
    }
  }
}
```

See [Webhooks](/docs/webhooks) for full setup and handling guide.






Verification


A drop-in **system prompt** that makes an AI coding agent integrate Flonk
correctly. It reads your stack, asks the questions that matter, shows a plan,
and only then implements, using the patterns your repository already has
instead of inventing structure.

## Use it in your AI coding agent

Add the [prompt below](#the-prompt) as a rules or instructions file so it
applies to every chat (recommended), or paste it once before asking for the
integration.

| Agent | Where to put it |
|-------|-----------------|
| **Claude Code** | `CLAUDE.md` at the repo root |
| **Cursor** | `.cursor/rules/flonk.mdc` (or legacy `.cursorrules`) |
| **GitHub Copilot** | `.github/copilot-instructions.md` |
| **Windsurf** | `.windsurf/rules/flonk.md` (or `.windsurfrules`) |
| **OpenAI Codex** | `AGENTS.md` at the repo root |
| **Cline / Roo Code** | `.clinerules` |
| **Gemini CLI / Jules** | `GEMINI.md` (or `AGENTS.md`) |
| **Aider, Zed, JetBrains AI, others** | paste as a system prompt or conventions file |

> Rules-file conventions change. If your agent uses a different file, check its
> docs. The prompt is plain instructions and works the same either way.

## The prompt

Copy the whole prompt into your agent's rules file, or paste it once before
asking for the integration. It is discovery-first: it asks before it writes
code and refuses to guess.

<AgentPrompt id="agent/integration-prompt" />

---

See [Frontend & Backend Integration](/docs/integration-frontend-backend), [Frontend SDK](/docs/frontend-sdk),
[Script Tag](/docs/script-tag), [Direct API](/docs/direct-api) and [Webhooks](/docs/webhooks) for the concrete
code each step references. Inline and redirect mounts are documented in the npm README.


Drop-in system prompt for AI coding agents (Claude Code, Cursor, Codex, Windsurf, Copilot, …) to integrate Flonk KYC — discovery-first, with hard rules.

AI Integration Prompt


> Building a native mobile app or a fully custom UI without the widget? See
> [Direct API (No SDK)](/docs/direct-api) — the same flow driven with plain REST calls.

## Quick Start (Node.js SDK)

```bash
npm install @flonkid/kyc
```

| Import | Use |
|--------|-----|
| `@flonkid/kyc` | Browser — widget iframe + postMessage |
| `@flonkid/kyc/server` | Node.js — sessions API + webhook verification |
| `@flonkid/kyc/types` | TypeScript types only |

---

## 1. Backend: Create session endpoint

Your backend creates a KYC session using the secret key, then returns `sessionId` + `embedToken` (+ `qrCodeUrl` for the mobile-transfer QR) to the frontend.

<CodeTabs
  items={[
    { label: 'Node.js (SDK)', snippetId: 'backend/sdk-server-session' },
    { label: 'Python', snippetId: 'backend/python-create-session' },
    { label: 'Java', snippetId: 'backend/java-create-session' },
    { label: 'Go', snippetId: 'backend/go-create-session' },
    { label: 'Rust', snippetId: 'backend/rust-create-session' },
  ]}
/>

## 2. Frontend: Start KYC

> The snippets below are React. **Vue / Svelte / Angular** use the same
> `FlonkKYC` class imported from **`@flonkid/kyc/core`** (the React-free entry —
> see [Frontend SDK](/docs/frontend-sdk#other-frameworks--the-flonkkyc-class)),
> and **no-build pages** (WordPress, Rails, plain HTML) load one `<script>` tag
> from the API — see [Script Tag (No Build Step)](/docs/script-tag).
> The session flow (A vs B) below is identical across all of them.

There are two integration approaches. Choose one:

### Option A: SDK handles everything (`serverUrl`)

SDK auto-creates the session via your backend endpoint, opens the widget, and handles cleanup. **Simplest approach — one component, zero state management.**

If your backend requires authentication, pass `requestHeaders`:

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

> `publishableKey` loads your project branding (colors, logo) instantly while the session is being created. Find it in **Dashboard → API Keys**.

<CodeTabs
  items={[
    { label: 'React', snippetId: 'frontend/sdk-react-component' },
    { label: 'Vue', snippetId: 'frontend/sdk-vue' },
    { label: 'Angular', snippetId: 'frontend/sdk-angular' },
    { label: 'Script tag', snippetId: 'frontend/sdk-script-tag' },
    { label: 'TypeScript', snippetId: 'frontend/sdk-browser-init' },
  ]}
/>

> **React** → `@flonkid/kyc`. **Vue / Angular / vanilla** → `FlonkKYC` from
> `@flonkid/kyc/core` (React-free). **No build step** → one `<script>` tag from
> `https://api.flonk.id/v1/public/widget-v2.js`, driven through the
> `window.KYCWidget` global ([full reference](/docs/script-tag)).

### Option B: You control session creation (`sessionId + embedToken`)

Your frontend creates the session first (via your API), then passes credentials to the widget. **More control — you decide when and how to create sessions.**

Best for:
- Custom UI before verification (e.g. confirmation screen, age check)
- Conditional session creation (e.g. only after payment)
- Existing backend API integration

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

function KYCVerification() {
  const [session, setSession] = useState(null);

  const startKYC = async () => {
    // Your backend creates the session
    const res = await fetch('/api/kyc/create-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: user.email }),
    });
    const data = await res.json();
    setSession(data);  // { sessionId, embedToken, qrCodeUrl }
  };

  return (
    <>
      <button onClick={startKYC}>Start Verification</button>

      {session && (
        <FlonkKYCWidget
          sessionId={session.sessionId}
          embedToken={session.embedToken}
          qrCodeUrl={session.qrCodeUrl}
          lang="de"
          onSuccess={(result) => {
            setSession(null);
            console.log('Verified:', result);
          }}
          onError={(error) => {
            setSession(null);
            console.error('Failed:', error);
          }}
          onCancel={() => setSession(null)}
        />
      )}
    </>
  );
}
```

### Which one to choose?

| | Option A (`serverUrl`) | Option B (`sessionId + embedToken`) |
|---|---|---|
| **Setup** | 1 component | Button + state + API call + component |
| **Control** | SDK manages session lifecycle | You manage session lifecycle |
| **Best for** | Quick integration, simple flows | Custom UX, conditional flows |
| **Auth** | `requestHeaders` prop | Your own fetch with auth |

## 3. Webhooks: Handle verification results

Verify the HMAC-SHA256 signature, then process the event.

<CodeTabs
  items={[
    { label: 'Node.js (SDK)', snippetId: 'backend/sdk-webhook-verify' },
    { label: 'Python', snippetId: 'backend/python-webhook' },
    { label: 'Java', snippetId: 'backend/java-webhook' },
    { label: 'Go', snippetId: 'backend/go-webhook' },
    { label: 'Rust', snippetId: 'backend/rust-webhook' },
  ]}
/>

**Detailed documentation:** [Webhooks Integration →](/docs/webhooks)


Integrate Flonk KYC with full TypeScript SDK or REST API for any backend language.

Frontend ↔ Backend Integration


# Proof of Address (PoA)

PoA is an optional verification step that asks the user to upload a document
confirming their residential address — a utility bill, bank statement, or a
letter from a government authority. The widget extracts the name and address
from the document with a vision-language model and reconciles them against
the identity document the user already submitted.

This page explains the two settings on the **Settings → PoA** tab and what
your end user experiences for each combination.

## Settings overview

| Setting | What it does |
|---------|--------------|
| **Enable PoA verification** | Adds the PoA step to the widget flow. When off, the widget skips the step and verification finishes after the identity document. |
| **Wait for PoA result in real time** | Decides whether the widget waits for the PoA review before showing the user a final decision, or whether it completes KYC immediately and delivers the PoA outcome later via webhook. |

Both toggles are per-environment (Live / Sandbox), so you can experiment in
Sandbox without affecting your live flow.

## "Wait for PoA result in real time" — explained

This is the toggle that most often surprises integrators, so it is worth
walking through carefully.

### Toggle ON — synchronous

When the toggle is **on**, the widget pauses after the user uploads the PoA
file and waits for the address review to finish before completing the
verification. The end user sees a single processing screen and then the
final decision.

* **Typical wait:** **40 seconds to 3 minutes** for most documents.
* **Worst-case wait:** up to ~15 minutes during peak load (rare).
* **End-user experience:** one progress card, then the verification result.
  No second visit to your app required.
* **Webhook timing:** `verification.completed` is fired **once**, after
  both the identity document and the PoA have been reviewed. Its payload
  already contains the final outcome.

Pick this mode when:

* You want the user to see the verification outcome on screen before they
  leave your funnel.
* Your funnel cannot easily resume after the user has navigated away (for
  example, a one-page sign-up that gates account creation on the result).

### Toggle OFF — asynchronous

When the toggle is **off**, the widget treats PoA as a background task. The
KYC session is marked complete as soon as the identity document and face
checks finish; the PoA review happens server-side afterwards.

* **End-user experience:** the user sees the verification finish
  immediately after the identity step and can leave your app right away.
* **Webhook timing:** you receive the standard
  `verification.completed` webhook for the identity / face decision. When
  the PoA review finishes, the verification record is updated and a
  follow-up webhook is fired with the PoA status (`auto_approved`,
  `manual_review`, or `rejected`) and confidence score on the
  `verification` object.
* **Server load:** absorbed entirely on our side — your user never waits.

Pick this mode when:

* Your funnel can deal with an asynchronous decision (for example, you
  send an email when the user is fully verified).
* You optimise for the lowest perceived completion time.

## What the end user sees while waiting

When **Wait for PoA result in real time** is on, the widget shows a
processing card with a circular brand loader, the document name, a
calm progress message, and a small "Usually takes about 1–3 minutes"
hint. Copy is intentionally non-alarming — we do not show the 15-minute
upper bound on screen so that occasional slow runs don't trigger
abandonment.

After ~5 minutes the message switches to a softer "A bit busier than
usual — your document is in the queue and will be reviewed shortly"
without naming a specific time. The session itself stays open up to 15
minutes; if the model has not produced a result by then, the verification
will be marked as `manual_review` and a moderator handles it.

## PoA fields on the verification object

After PoA runs (whether sync or async), the verification record exposes
the following data:

```json
{
  "poaStatus": "auto_approved",
  "poaConfidenceScore": 0.91,
  "documents": [
    {
      "type": "poa",
      "fileName": "poa_<attemptId>",
      "signedUrl": "https://flonk-id.t3.storage.dev/...",
      "extractedData": {
        "fullName": "KOVALENKO OLEKSANDR",
        "address": "Ukraine, region Kyivska, ...",
        "city": "Kyiv",
        "postalCode": "04080",
        "country": "Ukraine",
        "documentType": "registration document",
        "issueDate": "10.04.2021",
        "issuer": "4620",
        "poaStatus": "auto_approved",
        "poaConfidenceScore": 0.91
      }
    }
  ]
}
```

`poaStatus` values:

| Status | Meaning |
|--------|---------|
| `auto_approved` | Address extracted with high confidence and matches the identity document. |
| `manual_review` | Confidence below the auto-approve threshold; queued for a human moderator. |
| `rejected` | Cross-validation failed (different name on PoA vs. identity document) or the document was unreadable. |
| `pending` | Still being processed (only seen briefly in the async mode). |

## Webhook reference

* **Sync mode (toggle ON):** the regular `verification.completed`
  webhook already includes the final PoA fields. No follow-up event is
  emitted purely for PoA.
* **Async mode (toggle OFF):** `verification.completed` fires after the
  identity step. When PoA finishes, `verification.updated` is dispatched
  with the same payload shape — your handler should look at
  `data.object.poaStatus` to react.

See the [Webhooks](/docs/webhooks) page for signature verification and
event-handling boilerplate.

## Common questions

**Will my user be charged for the wait time?**
No. PoA does not consume an additional verification credit by itself; it
is a sub-step of the regular KYC verification.

**Can I switch between sync and async per session?**
Not currently. The toggle is project-wide per environment. If you need
session-level control, contact support.

**What file types are accepted?**
PDF, PNG, JPG, JPEG up to 10 MB. PDFs are rendered on our side; the user
does not need to convert them.

**What happens if the user's PoA is rejected?**
The verification record is marked `rejected` for PoA but the identity
verification result is independent — your `poaStatus === 'rejected'`
handler decides whether to allow the user to retry or to fail the whole
flow.


How the Proof of Address (PoA) step works, when to wait for it in real time, and what your end users see.

Proof of Address


# Security

Flonk KYC is designed with security in mind. Follow these guidelines to maintain a secure integration.

## API Key Security

### Never Expose Secret Keys

Secret keys should only be used server-side:

```typescript
// Good: Server-side
const secretKey = process.env.FLONK_SECRET_KEY;

// Bad: Client-side (NEVER do this)
const secretKey = 'sk_live_xxxxx'; // Exposed in browser
```

### Environment Variables

Store keys in environment variables, not in code:

```bash
# .env (never commit to git)
FLONK_SECRET_KEY=sk_live_xxxxxxxxxxxx
KYC_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
```

Add to `.gitignore`:

```
.env
.env.local
.env.*.local
```

## Webhook Security

### Always Verify Signatures

Every webhook request includes a signature header. Always verify it.

**Using the SDK (Recommended):**

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

const flonk = new FlonkKYCServer({
  secretKey: process.env.FLONK_SECRET_KEY!,
});

// SDK handles both signature formats automatically
const event = flonk.webhooks.constructEvent(
  rawBody,
  req.headers['x-signature-256'],
  process.env.FLONK_WEBHOOK_SECRET!,
);
```

**Manual verification:**

```typescript
function verifySignature(payload: Buffer, signature: string): boolean {
  if (!signature?.startsWith('sha256=')) {
    return false;
  }

  const sigHex = signature.slice(7);
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(sigHex),
    Buffer.from(expected)
  );
}
```

### Use Raw Body

Verify against the raw request body, not parsed JSON:

```typescript
// NestJS
@Post('webhook')
handleWebhook(@Req() req: RawBodyRequest<Request>) {
  const isValid = verifySignature(
    req.rawBody,
    req.get('X-Signature-256')
  );
}
```

## Data Protection

### Minimize Stored Data

Store only what you need:

```typescript
// Good: Store minimal data
await db.user.update({
  where: { id: userId },
  data: {
    kycVerified: true,
    kycVerifiedAt: new Date()
  }
});

// Avoid: Storing all extracted data unnecessarily
```

### Encrypt Sensitive Data

If storing verification data, encrypt it:

```typescript
const encryptedData = encrypt(JSON.stringify(extractedData));
await db.kycData.create({
  data: { userId, encryptedData }
});
```

## Network Security

### Use HTTPS

All API calls and webhook endpoints must use HTTPS:

```typescript
// Good
const apiUrl = 'https://api.flonk.id/v1';

// Bad
const apiUrl = 'http://api.flonk.id/v1';
```

### Webhook IP Allowlist

For additional security, restrict webhook endpoints to Flonk IP ranges. Contact support for current IP ranges.

## Compliance

### GDPR

- Inform users about KYC data collection
- Provide data deletion mechanism
- Document data retention policies

### Data Retention

- Delete verification data when no longer needed
- Implement automatic data expiration
- Log all data access for audit






Security best practices for KYC integration

Security


# Troubleshooting

Solutions for common KYC integration issues.

## SDK Issues

### Module Not Found

**Symptom:** `Cannot find module '@flonkid/kyc'`

**Solution:** Install the SDK:
```bash
npm install @flonkid/kyc
```

### SSR Error (Next.js)

**Symptom:** `window is not defined` or `document is not defined`

**Solution:** Use dynamic import to avoid SSR:
```typescript
// Wrong: top-level import runs on server
import { FlonkKYC } from '@flonkid/kyc';

// Correct: dynamic import runs only in browser
const startKYC = async () => {
  const { FlonkKYC } = await import('@flonkid/kyc');
  const kyc = new FlonkKYC();
  // ...
};
```

### serverUrl HTTPS Error

**Symptom:** `serverUrl must use HTTPS in production`

**Solution:** The SDK enforces HTTPS for absolute URLs. Use a relative path or HTTPS:
```typescript
// Relative path (OK)
serverUrl: '/api/kyc/create-session'

// HTTPS (OK)
serverUrl: 'https://api.myapp.com/kyc/create-session'

// HTTP (rejected, except localhost)
serverUrl: 'http://api.myapp.com/kyc/create-session' // Error!
```

## Widget / Loader Issues

### Turn on debug logging first

Before anything else, make the SDK tell you what it's doing. Every degradation
(blocked loader script, prewarm skipped, no `READY` from the iframe, protocol
mismatch) is reported — silent by default, visible when you opt in:

```typescript
// Anywhere before the widget opens — no rebuild needed:
window.__FLONK_DEBUG__ = true;

// Or capture events in code:
const kyc = new FlonkKYC({
  onDiagnostic: (e) => console.log(`[flonk:${e.code}] ${e.message}`, e.detail),
});
```

On the [script-tag path](/docs/script-tag), add `data-debug` to the tag (or set
the same global). Then reproduce and read the `[flonk:*]` codes.

### Loader stuck / widget never appears

**Symptom:** the loading overlay stays up; the widget content never shows.

**Diagnose:** enable debug logging (above) and look for:

| Code | Cause | Fix |
|------|-------|-----|
| `READY_TIMEOUT_REVEAL` | The iframe never sent `READY` (usually a CSP `frame-src` block or a hard error inside the iframe). | Allow the widget origin in `frame-src` — `https://verify.flonk.id` unless you pinned `widgetUrl` (see below); check the iframe's own console. |
| `LOADER_SCRIPT_BLOCKED` | The branded loader script was blocked (CSP `script-src`, CORP, or offline). | Allow `https://api.flonk.id` in `script-src`. The SDK still works with its bundled loader. |
| `PROTOCOL_VERSION_MISMATCH` | The SDK and the cached iframe speak different wire versions. | Hard-refresh / clear the site's cache to drop the stale widget. |

The SDK reveals the widget on a safety timeout even if `READY` is missing, so a
permanent "stuck loader" should not happen — if it does, it's almost always a
`frame-src` CSP block stopping the iframe from loading at all.

### Content Security Policy (CSP) blocks the widget

**Symptom:** the iframe or loader script is blocked; console shows a CSP
violation or `ERR_BLOCKED_BY_RESPONSE`.

**Solution:** if your site sends a `Content-Security-Policy`, allow our origins:

```
Content-Security-Policy:
  frame-src   https://verify.flonk.id;
  script-src  https://api.flonk.id;
  connect-src https://api.flonk.id;
```

Three directives, one origin each:

- **`frame-src`** — the widget iframe. `https://verify.flonk.id` is the default
  from SDK 2.0; if you pinned `widgetUrl: 'https://widget.flonk.id'` to stay on
  the previous widget, name that instead.
- **`script-src`** — the server-hosted loader
  (`api.flonk.id/v1/public/loader.js`), the only cross-origin script the SDK
  adds to *your* page. On the [script-tag path](/docs/script-tag) it also
  carries the SDK bundle itself, so there it is not optional.
- **`connect-src`** — the SDK's own `fetch` calls, all to the API. The widget's
  own REST and WebSocket traffic happens *inside* the frame and answers to the
  frame's policy, not yours.

> **Upgrading from a pre-2.0 policy: the widget origin is removed from
> `script-src`, not renamed.** It hands your page no script — only the framed
> document, which loads its own bundle under its own policy. `img-src` is gone
> too: both loaders draw the spinner with `createElementNS` and fetch no image.

You do **not** need any CORS or `Cross-Origin-Resource-Policy` config on your
side — our public assets already send the right cross-origin headers, and the
API handles CORS for the SDK's requests. If the loader script specifically is
blocked, the SDK falls back to its bundled loader and still works (you just lose
dashboard-driven loader branding).

### The camera never starts, and CSP looks fine

**Symptom:** the widget loads and reaches the capture step, but the camera
prompt never appears — or appears and immediately fails.

**Solution:** this is almost always `Permissions-Policy`, not CSP. The SDK
delegates `camera` to the iframe via its `allow` attribute, but `allow` can only
hand down a capability *your page already holds*. A restrictive header on your
side kills capture in the sub-frame:

```
Permissions-Policy: camera=(self "https://verify.flonk.id"), microphone=(self "https://verify.flonk.id")
```

If you send no `Permissions-Policy` at all, nothing is restricted and the camera
works. The header only becomes a problem once you start sending one.

## API Issues

### 401 Unauthorized

**Symptom:** `invalid_api_key` error.

**Checklist:**

- [ ] Using correct secret key (not publishable key)
- [ ] Key is for correct environment (test/live)
- [ ] `Bearer` prefix in Authorization header
- [ ] No extra spaces in key

```typescript
// Correct
headers: {
  'Authorization': `Bearer ${secretKey}`,
}

// Wrong
headers: {
  'Authorization': secretKey,  // Missing Bearer
  'Authorization': `Bearer ${secretKey} `,  // Extra space
}
```

### 400 Bad Request

**Symptom:** Request validation errors.

**Common causes:**

1. Invalid or missing data:
```typescript
{
  "clientMetadata": {
    "email": "user@example.com",  // recommended
    "userId": "user_123"          // optional
  }
}
// All clientMetadata fields are optional, but email is
// recommended so webhook events can be matched to users.
```

2. Invalid JSON:
```typescript
// Use JSON.stringify
body: JSON.stringify(data)

// Not
body: data
```

## Webhook Issues

### Webhooks Not Received

**Checklist:**

- [ ] Endpoint is publicly accessible (not localhost)
- [ ] HTTPS enabled
- [ ] URL registered in Flonk Dashboard
- [ ] Server returns 200 OK

**Test with ngrok for local development:**
```bash
ngrok http 3000
# Use ngrok URL in Dashboard
```

### Invalid Signature

**Symptom:** Signature verification fails.

**Solutions:**

1. Use raw body, not parsed JSON:
```typescript
// NestJS - enable raw body
app.useGlobalPipes(new ValidationPipe());
app.use(json({ verify: (req, res, buf) => {
  req.rawBody = buf;
}}));
```

2. Verify correct webhook secret
3. Pass the right header — `X-Signature` (recommended, replay-protected) or the
   `X-Signature-256`. `constructEvent` accepts either. If you verify
   manually, use a constant-time compare (`crypto.timingSafeEqual`), not `===`.

### Duplicate Webhooks

**Symptom:** Same event processed multiple times.

**Cause:** delivery is at-least-once (Flonk retries on non-200), so duplicates
are expected. Dedupe by `event.id` in your own store — a unique DB index or
Redis `SET NX`:

```typescript
const fresh = await redis.set(`whk:${event.id}`, '1', 'PX', 6 * 60_000, 'NX');
if (fresh === null) return; // retry — already handled
await processEvent(event);
```

See [Webhooks → Idempotency](/docs/webhooks#1-idempotency) for the DB-unique-index
variant.

## Getting Help

If you can't resolve an issue:

1. Check [Integration Guide](/docs/integration-frontend-backend)
2. Check [API Reference](/docs/api-authentication)
3. Contact support: support@flonk.id

Include in support requests:
- Session ID
- Error messages
- Timestamp
- Request/response logs (without sensitive data)






Documentation

Integrate with your AI coding agent

Quick start

API reference

Support

Getting started