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 Next/Back 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';
// 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());

onStateChange callback

The callback returns an object with these fields:

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

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.

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

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 to poll for the final status.

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