> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify by Widget

> Let the Fluz widget handle identity verification as a built-in step, with no identity data passing through your systems.

If you embed the Fluz widget, verification comes with it. You do not build a verification flow, collect identity fields, or handle documents — the widget presents verification as a gate and clears it before letting the customer continue.

This is the only path where a customer's identity information never touches your infrastructure, which is usually the deciding factor in choosing it.

<Info>
  **Prerequisites**

  * A widget application configured in the Developer Portal, with OAuth settings in place. See [Configure App Widget](/developers/configure-app-widget).
  * The `VERIFY_KYC` scope enabled on your application by Fluz. See [Required scope](/user-kyc-verification#required-scope).
  * A registered webhook endpoint. See [Verify Customers](/user-kyc-verification#set-up-a-webhook).
</Info>

## Where verification fits

Verification is a step in the widget's normal sequence, not a separate integration:

<Steps>
  <Step title="Your page calls FluzEmbedded.init()">
    The widget opens in an iframe.
  </Step>

  <Step title="The customer signs in or registers">
    If they do not yet have a Fluz account, the widget creates one.
  </Step>

  <Step title="The widget checks verification status">
    If the customer is already verified, it moves straight on. If not, verification runs here.
  </Step>

  <Step title="The customer completes any remaining steps">
    PIN setup and OAuth scope authorization.
  </Step>

  <Step title="The customer completes their transaction">
    Confirmation, then completion.
  </Step>
</Steps>

Because verification sits ahead of the transaction, a customer who cannot verify will not reach the transaction step at all.

## What the customer experiences

When an unverified customer reaches the gate, the widget first attempts to verify them silently in the background. Many customers clear the gate at this point without being asked for anything.

If that does not resolve, the widget presents a verification form inside the iframe, prefilled with whatever Fluz already holds. The customer reviews it, supplies what is missing, and submits. The widget then shows a waiting state while the result is processed and advances automatically once it resolves.

If verification still does not succeed, the widget escalates the customer to document verification — capturing their government-issued ID and a selfie — within the same iframe.

<Note>
  All of this happens inside the widget. You do not need to detect which stage a customer is at or trigger the escalation yourself.
</Note>

## Scopes

Widget applications request the scopes they need automatically during the OAuth authorization step, including `VERIFY_KYC`. You do not have to add it to the widget's scope list manually.

You do still need `VERIFY_KYC` enabled on the application itself by Fluz. If it is not, the widget will fail to load with a missing-permissions error rather than skipping verification.

<Warning>
  When generating the short-lived token you pass to the widget as `patToken`, use your **API Key** for the `Authorization: Basic` header — not your OAuth client ID and not your `app_id`. Using the wrong value is the most common cause of a widget failing to load. See [Obtain Your API Credentials](/get-started/api-credentials).
</Warning>

## Knowing the outcome

The widget tells the customer their result directly, but your application should not infer verification state from the widget closing. Rely on webhooks instead.

Fluz emits `WIDGET_KYC_INITIATION` when a customer **begins** verification in the widget. This requires the `VERIFY_KYC` scope.

```json theme={null}
{
  "eventType": "WIDGET_KYC_INITIATION",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "externalReferenceId": "your-reference-123"
}
```

<Note>
  This event marks the **start** of verification, not the result. Use `externalReferenceId` to map the event to your own customer record, and subscribe to the verification outcome events as well so you know how it resolved. See [Webhooks](/fluz-dashboard/webhooks).
</Note>

## Combining the widget with the API

The widget and the API share one verification state per customer, so the two approaches compose cleanly:

* A customer verified through the API will pass straight through the widget's gate.
* A customer verified in the widget is verified for your API calls too.
* A customer who has exhausted their attempts in one channel has exhausted them in both.

This matters if you verify customers through the API during onboarding and later hand them to the widget: check the customer's current verification status rather than assuming the widget will offer them another attempt.

## Testing

Run the full widget flow in staging against the published test identities, including a deliberate decline so you can see the escalation to document verification. Staging widgets point at the staging environment rather than production — confirm you are loading the staging widget script and base URL. See [Testing KYC Flows](/test-kyc-flows) and [Staging vs. Live Environment](/concepts/environments).