> For a complete page index, fetch https://docs.transak.com/llms.txt

# Headless KYC

**Headless KYC** is a UI module that enables partners to integrate the multi-step KYC flow directly into their applications by simply loading Transak's KYC widget.

## Current Limitations

<table>
  <thead>
    <tr>
      <th>
        Limitation
      </th>

      <th>
        Details
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Headless KYC APIs ([Transaction Session API](/api/whitelabel/headless-kyc/transaction-session-api))**
      </td>

      <td>
        APIs are to be called only from the partner backend and subjected to the whitelisting of partner IP addresses. We don’t support API calls from the frontend due to security restrictions.
      </td>
    </tr>

    <tr>
      <td>
        **Camera permission**
      </td>

      <td>
        Partner app must grant camera permission at the manifest or browser level. If permission isn't available, the module shows fallback automatically.
      </td>
    </tr>

    <tr>
      <td>
        **Supported for JS, React, and React Native integrations**
      </td>

      <td>
        The Transak UI SDK is available for JS, React, and React Native integrations.
      </td>
    </tr>

    <tr>
      <td>
        **KYC approved but FCA submission pending (For UK Users)**
      </td>

      <td>
        UK users can be KYC approved in the [Get User Details](/api/whitelabel/user/get-user-details) API but still be unable to place an order if FCA is not completed. Click below for more details -
        \
        \


        When to open Headless KYC Module for FCA
      </td>
    </tr>
  </tbody>
</table>

#### When to open Headless KYC Module for FCA (For UK users only)

#### Check the KYC status

Call the [Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement) API. If FCA is pending, `status` is `ADDITIONAL_FORMS_REQUIRED`.

**`Sample Response`**

```json title="Sample Response"
{
  "data": {
    "status": "ADDITIONAL_FORMS_REQUIRED",
    "kycType": "STANDARD"
  }
}
```

| Field          | Description                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `data.status`  | The user's KYC status. `ADDITIONAL_FORMS_REQUIRED` means more forms, such as FCA, are pending. Go to the next step. |
| `data.kycType` | The KYC level of the user, for example `SIMPLE`, `STANDARD` or `ENHANCED`.                                          |

#### Check the FCA status

Call the [Get Additional Requirements](/api/whitelabel/kyc/get-additional-requirements) API. If `formsRequired` has a form with `type: FCA`, read `metadata.status` and `metadata.waitUntil`.

**`Blocked Retry`**

```json title="Blocked Retry"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "BLOCKED_RETRY"
        }
      }
    ]
  }
}
```

**`Cooling Period`**

```json title="Cooling Period"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "COOLING_PERIOD",
          "waitUntil": "2026-11-06T10:30:00.000Z"
        }
      }
    ]
  }
}
```

**`Risk Assessment Failed (Retry Later)`**

```json title="Risk Assessment Failed (Retry Later)"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "RISK_ASSESSMENT_FAILED",
          "waitUntil": "2026-11-06T06:12:16.000Z"
        }
      }
    ]
  }
}
```

**`Risk Assessment Failed (Immediate Retry)`**

```json title="Risk Assessment Failed (Immediate Retry)"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "RISK_ASSESSMENT_FAILED"
        }
      }
    ]
  }
}
```

**`Risk Assessment Pending`**

```json title="Risk Assessment Pending"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "RISK_ASSESSMENT_PENDING"
        }
      }
    ]
  }
}
```

**`Agreement Pending`**

```json title="Agreement Pending"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "AGREEMENT_PENDING"
        }
      }
    ]
  }
}
```

**`Categorization Pending`**

```json title="Categorization Pending"
{
  "data": {
    "formsRequired": [
      {
        "type": "FCA",
        "metadata": {
          "status": "CATEGORIZATION_PENDING"
        }
      }
    ]
  }
}
```

| Field                  | Description                                                                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formsRequired[].type` | The form that is pending. `FCA` means the user must complete the FCA flow.                                                                                          |
| `metadata.status`      | The next pending FCA step: `CATEGORIZATION_PENDING`, `AGREEMENT_PENDING`, `RISK_ASSESSMENT_PENDING`, `RISK_ASSESSMENT_FAILED`, `BLOCKED_RETRY` or `COOLING_PERIOD`. |
| `metadata.waitUntil`   | When the current wait ends, in ISO 8601 UTC format. Returned only during the 24-hour wait after `RISK_ASSESSMENT_FAILED`, and during `COOLING_PERIOD`.              |

#### Decide whether to open the Headless KYC Module

| Status                                                                     | Action                                                                                                                                               |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CATEGORIZATION_PENDING`, `AGREEMENT_PENDING` or `RISK_ASSESSMENT_PENDING` | Open [Headless KYC Module](/features/transak-kyc-headless#load-the-headless-kyc-component-via-transak-ui-sdk) so the user can complete the FCA step. |
| `RISK_ASSESSMENT_FAILED` without `waitUntil`                               | Open [Headless KYC Module](/features/transak-kyc-headless#load-the-headless-kyc-component-via-transak-ui-sdk) for retry.                             |
| `RISK_ASSESSMENT_FAILED` with `waitUntil`                                  | Do not open [Headless KYC Module](/features/transak-kyc-headless#load-the-headless-kyc-component-via-transak-ui-sdk) until the `waitUntil` time.     |
| `COOLING_PERIOD` with `waitUntil`                                          | Do not open [Headless KYC Module](/features/transak-kyc-headless#load-the-headless-kyc-component-via-transak-ui-sdk) until the `waitUntil` time.     |
| `BLOCKED_RETRY`                                                            | Do not open [Headless KYC Module](/features/transak-kyc-headless#load-the-headless-kyc-component-via-transak-ui-sdk).                                |

## How to integrate?

#### Whitelist Your API Key & Enable Headless KYC

| Action                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------- |
| Follow the steps in the [Need help in Integration](/getting-started/help-and-support#need-help-in-integration) section |
| Request **API key whitelisting**                                                                                       |
| Share your public IP addresses with Transak for whitelisting to use our APIs in your backend                           |

#### User Authentication

You can use either of the following authentication options:

| Option               | Description                                                                                                                                                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **White-label Auth** | Use the standard Transak authentication flow to generate a user access token. Partners can do this by calling the [Send User OTP API](/api/whitelabel/user/send-user-otp) followed by the [Verify User API](/api/whitelabel/user/verify-user-otp) to generate the access token. Learn more  |
| **Auth Reliance**    | Use [Auth Reliance](/features/auth-reliance) by passing these headers with every request: `x-user-identifier` and `x-access-token`                                                                                                                                                          |

Please refer to the tutorial on [how to create partner access token](/guides/how-to-create-partner-access-token).

#### Generate a quote using the Quote API

Call the [Get Quote API](https://docs.transak.com/api/whitelabel/lookup/get-quote) to get a quote for the transaction. Pass the apiKey, fiat amount, fiat currency, crypto currency, network, and order type.

A successful response returns a `quoteId`.

#### Create a transaction session (using Backend only)

Call the [Transaction Session API](/api/whitelabel/headless-kyc/transaction-session-api) from your backend, passing the `quoteId` from the previous step and a new `module` field set to `"kyc"`.

| Parameter | Description                                                                                                                  |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `quoteId` | Quote ID returned by the [Get Quote API](https://docs.transak.com/api/whitelabel/lookup/get-quote) in the previous step      |
| `module`  | Set to `"kyc"` to initialize a Headless KYC session                                                                          |
| `config`  | Optional. `colorMode` (`DARK` or `LIGHT`) to theme the KYC component and `colors` object to override individual theme colors |

A successful response returns a `sessionId`.

#### Load the Headless KYC Component via Transak UI SDK

Use the Transak UI SDK to render the KYC component. Pass the `sessionId` received in the previous step.

The module renders no Next/Back buttons of its own, wire your own UI to the SDK's `next()` / `back()` methods.

#### JS

```bash
npm install @transak/ui-components
```

```tsx
import { createTransakKyc } from '@transak/ui-components';

// Your own Back/Next buttons and step title
const backBtn = document.getElementById('back-btn');
const nextBtn = document.getElementById('next-btn');
const title = document.getElementById('step-title');

const kyc = createTransakKyc({
  sessionId, // sessionId from previous step
  environment, // 'STAGING' | 'PRODUCTION'
  onReady: () => {
    // Component is ready
  },
  onStateChange: (state) => {
    // Current step state changed. No user data included.
    // Use this to update your own Back/Next buttons and step title.
    backBtn.disabled = !state.canGoBack;
    nextBtn.hidden = state.ctaText === null;
    nextBtn.disabled = !state.canGoNext || state.isSubmitting;
    nextBtn.textContent = state.isSubmitting ? 'Submitting...' : state.ctaText ?? '';
    title.textContent = state.name ?? '';
  },
  onSubmitted: ({ kycStatus }) => {
    // All required forms submitted. kycStatus is 'SUBMITTED' (KYC is under review);
    // track final approval separately via the KYC status API or webhook.
  },
  onError: ({ code }) => {
    // Handle error
  },
  onDismiss: () => {
    // Close the KYC module and navigate the user back to your app.
    kyc.unmount();
  },
});

await kyc.mount('kyc-slot');

// Call back() and next() when the user clicks on back and next buttons
backBtn.addEventListener('click', () => kyc.back());
nextBtn.addEventListener('click', () => kyc.next());
```

Call `kyc.unmount()` to remove the component from the page when the user leaves the KYC screen.

#### React

```bash
npm install @transak/ui-components-react
```

```tsx
import { useRef, useState } from 'react';
import { TransakKyc } from '@transak/ui-components-react';

const ref = useRef(null);
const [step, setStep] = useState({ canGoBack: false, canGoNext: false, isSubmitting: false, ctaText: null });

// Your own step title
<h2>{step.name ?? ''}</h2>

<TransakKyc
  ref={ref}
  sessionId={sessionId} // sessionId from previous step
  environment={environment} // 'STAGING' | 'PRODUCTION'
  onReady={() => {
    // Component is ready
  }}
  onStateChange={(state) => {
    // Current step state changed. No user data included.
    // Store it to update your own Back/Next buttons and step title.
    setStep(state);
  }}
  onSubmitted={({ kycStatus }) => {
    // All required forms submitted
  }}
  onError={({ code }) => {
    // Handle error
  }}
  onDismiss={() => {
    // Close the KYC module and navigate the user back to your app.
  }}
/>

// Call back() and next() when the user clicks on back and next buttons
<button disabled={!step.canGoBack} onClick={() => ref.current?.back()}>
  Back
</button>
{step.ctaText !== null && (
  <button
    disabled={!step.canGoNext || step.isSubmitting}
    onClick={() => ref.current?.next()}
  >
    {step.isSubmitting ? 'Submitting...' : step.ctaText}
  </button>
)}
```

#### React Native

```bash
npm install @transak/ui-components-rn
```

```tsx
import { useRef, useState } from 'react';
import { Pressable, Text } from 'react-native';
import { TransakKyc } from '@transak/ui-components-rn';

const ref = useRef(null);
const [step, setStep] = useState({ canGoBack: false, canGoNext: false, isSubmitting: false, ctaText: null });

// Your own step title
<Text>{step.name ?? ''}</Text>

<TransakKyc
  ref={ref}
  sessionId={sessionId} // sessionId from previous step
  environment={environment} // 'STAGING' | 'PRODUCTION'
  onReady={() => {
    // Component is ready
  }}
  onStateChange={(state) => {
    // Current step state changed. No user data included.
    // Store it to update your own Back/Next buttons and step title.
    setStep(state);
  }}
  onSubmitted={({ kycStatus }) => {
    // All required forms submitted
  }}
  onError={({ code }) => {
    // Handle error
  }}
  onDismiss={() => {
    // Close the KYC module and navigate the user back to your app.
  }}
/>

// Call back() and next() when the user clicks on back and next buttons
<Pressable disabled={!step.canGoBack} onPress={() => ref.current?.back()}>
  <Text>Back</Text>
</Pressable>
{step.ctaText !== null && (
  <Pressable
    disabled={!step.canGoNext || step.isSubmitting}
    onPress={() => ref.current?.next()}
  >
    <Text>{step.isSubmitting ? 'Submitting...' : step.ctaText}</Text>
  </Pressable>
)}
```

> **Info**
>
> The React Native wrapper is WebView-based and must set `mediaCapturePermissionGrantType` and camera permissions so `Onfido` can access the camera inside the WebView.

#### `onStateChange` callback

The callback returns an object with these fields:

```ts
{
  canGoBack: boolean,
  canGoNext: boolean,
  isSubmitting: boolean,
  ctaText: string | null,
  name?: string
}
```

| Field          | Meaning                                                   | Map to                          |
| -------------- | --------------------------------------------------------- | ------------------------------- |
| `name`         | Title of the current step                                 | Step title                      |
| `canGoBack`    | User can go to the previous step                          | Back button enabled/disabled    |
| `canGoNext`    | Current step is complete and valid                        | Next button enabled/disabled    |
| `isSubmitting` | Current step is being submitted                           | Next button loading state       |
| `ctaText`      | Label for the Next button. If `null`, no label is present | Next button text and visibility |

The callback fires only after `onReady`, and only when a value changes.

#### `back()` and `next()` methods

These methods are mandatory and help the user navigate between KYC forms. Add your own Back and Next buttons, and call these methods when the user clicks them.

| Method   | Description                                                                                                                                     |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `back()` | Returns the user to the previous form so they can update it. On the first step it does nothing, with no event and no error                      |
| `next()` | Submits the current form, and navigates to the next form. If the form is invalid, the field errors show inline and the flow stays on that form. |

Both methods do nothing before `mount()` or after `unmount()`.

#### `onSubmitted` callback

Completion is signalled only by `onSubmitted({ kycStatus })`. There is no completion state in `onStateChange`.

* `kycStatus` is always `SUBMITTED`, which means the KYC is under review. The final approval comes from the [KYC Webhooks](/features/webhooks#kyc-webhooks).
* If the user has already completed every step, `onSubmitted` fires immediately on load.

#### `onDismiss` callback

The `onDismiss` callback has no parameters. When it fires, close the KYC module and take the user back to your app.

#### `onError` callback

The `onError` callback returns `{ code, message? }`. Use the `code` to handle each failure case, and treat any unknown code as a generic error.

| Code                       | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `INVALID_OPTIONS`          | Invalid or missing options passed to the SDK                                |
| `INVALID_STATE`            | The component is already mounted                                            |
| `IFRAME_LOAD_FAILED`       | The KYC component failed to load                                            |
| `CONFIG_LOAD_FAILED`       | The `sessionId` is invalid or expired. Create a new session and mount again |
| `STEP_SUBMIT_FAILED`       | The current step failed to submit. The user can correct it and continue     |
| `FILE_UPLOAD_FAILED`       | Document upload failed                                                      |
| `KYC_PROVIDER_UNAVAILABLE` | The KYC provider is temporarily unavailable                                 |
| `CAMERA_PERMISSION_DENIED` | Camera access was denied. Ask the user to allow camera access               |
| `USER_BLOCKED`             | A UK user failed the risk assessment and is blocked                         |

#### Handle the ID proof and selfie step

The ID proof and selfie step is handled inside the module via `Onfido`, no separate integration is required. Keep the following in mind:

* Your app is responsible for granting camera permission (native app manifest or browser).
* If permission isn't available, the module automatically shows a fallback.
* If the user denies camera access, `onError` returns `CAMERA_PERMISSION_DENIED`.
* This step has its own in-frame buttons, so `onStateChange` returns `ctaText: null`. Hide your Next button on this step.

#### Track the final KYC status

The module's `onSubmitted` callback fires once all required forms are submitted with `kycStatus: SUBMITTED`, it does not guarantee final approval. Use the [Get KYC Requirement API](/api/whitelabel/kyc/get-kyc-requirement) to poll for the final status.

Partner can also use the [KYC Webhooks](/features/webhooks#kyc-webhooks) to receive a notification when the final status is available.

## API Overview

#### [Transaction Session API](/api/whitelabel/headless-kyc/transaction-session-api)

Creates a transaction session using a quote ID and `module: "kyc"`, returns a `sessionId` to initialise the Headless KYC component.

## API Errors

#### Transaction Session API

| Status Code | Error Code | Message                                                               | Next Step                                                                                                                                                               | Terminal State |
| ----------- | ---------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| 401         | 1002       | Invalid or missing authentication token.                              | Pass a valid `authorization` header, or `x-user-identifier` and `x-access-token` headers for [Auth Reliance](/features/auth-reliance), then retry creating the session. | No             |
| 422         | 6003       | This feature is not enabled for your account. Please contact support. | Contact Transak to enable Headless KYC for your account.                                                                                                                | Yes            |
| 422         | 6005       | Quote not found or could not be loaded.                               | Get a new quote with **[Get Quote](/api/whitelabel/lookup/get-quote)**, then retry creating the session.                                                                | No             |
| 500         | 6005       | Failed to create a session for the user.                              | Retry creating the session after a few seconds.                                                                                                                         | No             |