Headless KYC

Whitelist Your API Key & Enable Headless KYC

User Authentication

You can use either of the following authentication options:

Generate a quote using the Quote API

Call the Get Quote API 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 from your backend, passing the quoteId from the previous step and a new module field set to "kyc".

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 Back/Next/Submit buttons of its own, wire your own UI to the SDK’s next() / back() methods.

npm install @transak/ui-components

import { createTransakKyc } from '@transak/ui-components';
const kyc = createTransakKyc({
  sessionId, // sessionId from previous step
  environment, // 'STAGING' | 'PRODUCTION'
  onReady: () => {
    // Component is ready
  },
  onStateChange: (state) => {
    // Current step changed (e.g. personalDetails, address, idProof) — no user data included.
    // Use this to enable/disable your own Back/Next buttons.
  },
  onSubmitted: ({ kycStatus }) => {
    // All required forms submitted. kycStatus is almost always 'SUBMITTED';
    // track final approval separately via the KYC status API or webhook.
  },
  onError: ({ code }) => {
    // Handle error
  },
});
await kyc.mount('kyc-slot');
// wire to your own Back/Next buttons:
kyc.back();
kyc.next();
// and then
kyc.unmount();

Error codes

The onError callback receives a code value. Use it to handle specific failure scenarios:

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.

Track the final KYC status

The module’s onSubmitted callback fires once all required forms are submitted, it does not guarantee final approval. Use the Get KYC Requirement API to poll for the final status.

Partner can also use the KYC Webhooks to receive a notification when the final status is available.