Troubleshooting

Solutions for common KYC integration issues.

SDK Issues

Module Not Found

Symptom: Cannot find module '@flonkid/kyc'

Solution: Install the SDK:

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:

// 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:

// 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:

// 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, 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:

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 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

// 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:

{
  "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:

// 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:

ngrok http 3000
# Use ngrok URL in Dashboard

Invalid Signature

Symptom: Signature verification fails.

Solutions:

1. Use raw body, not parsed JSON:

// 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:

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 for the DB-unique-index variant.

Getting Help

If you can't resolve an issue:

1. Check Integration Guide
2. Check API Reference
3. Contact support: support@flonk.id

Include in support requests:

• Session ID
• Error messages
• Timestamp
• Request/response logs (without sensitive data)