Verificação de identidade por iframe: KYC web incorporado

Incorpore o fluxo de verificação da Didit diretamente na sua aplicação usando um iframe. Assim, a experiência fica fluida, sem redirecionar os usuários para fora do seu site.

Visão geral

Recurso	UniLink (sem backend)	Sessão via API (com backend)
Tempo de configuração	< 1 minuto	5-10 minutos
Exige backend	❌ Não	✅ Sim
`vendor_data` personalizado	❌ Não	✅ Sim
`metadata` personalizado	❌ Não	✅ Sim
Callback por sessão	❌ Não	✅ Sim
Rastreamento de sessões	❌ Não	✅ Sim

Iframe com UniLink (sem backend)

A forma mais rápida de começar: basta copiar e colar a URL do seu UniLink.

O que você precisa

Um fluxo de verificação (workflow) da Didit (criado no Didit Console)
A URL do seu UniLink (clique em Copy Link no seu fluxo)

Implementação

<iframe 
  src="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64"
  style="width: 100%; height: 700px; border: none;" 
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

⚠️ Obrigatório: o atributo allow é obrigatório para o acesso à câmera durante a prova de vida.

Principais vantagens

Configuração em menos de 1 minuto: sem backend, sem chaves de API
Zero configuração: a URL de retorno é definida nas configurações do fluxo
Ideal para MVPs: comece imediatamente

Iframe com sessão via API (com backend)

Para integrações avançadas que precisam de personalização por sessão.

Quando usar

Enviar vendor_data ou metadata personalizados por sessão
Definir URLs de retorno diferentes por sessão
Rastrear sessões no servidor antes de a verificação começar
Associar sessões aos IDs dos seus usuários

Implementação

Etapa 1: criar uma sessão (backend) A resposta de criação de sessão usa um campo chamado url: use-o como src do iframe.

// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: userId,
      callback: 'https://yourapp.com/verification-callback',
      metadata: { source: 'web-app', timestamp: Date.now() },
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  // 201 per OpenAPI: { session_id, session_number, session_token, url, vendor_data,
  //                    metadata, status, workflow_id, workflow_version, callback }
  const session = await response.json();
  res.json({ sessionId: session.session_id, verificationUrl: session.url });
});

Etapa 2: incorporar no iframe (frontend)

<iframe 
  id="didit-verification"
  src="" <!-- Set dynamically from API response -->
  style="width: 100%; height: 650px; border: none;" 
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    document.getElementById('didit-verification').src = verificationUrl;
  }
</script>

Monitoramento de eventos (postMessage)

A página de verificação envia eventos para a janela pai. Toda mensagem tem este envelope:

{
  type: 'didit:<event>',   // e.g. 'didit:completed'
  data: { /* payload */ }, // event-specific; may be undefined
  timestamp: 1718000000000 // ms epoch
}

O payload é aninhado: leia event.data.data.sessionId, e não event.data.sessionId:

window.addEventListener('message', (event) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;

  const { type, data } = event.data || {};

  if (type === 'didit:ready') {
    console.log('Session ID:', data.sessionId); // available as soon as the page loads
  }
  if (type === 'didit:completed') {
    console.log('Done:', data.sessionId, data.status); // e.g. "Approved" | "Declined" | "In Review"
    // UI hint only — the canonical decision arrives on your backend via webhook
  }
});

Principais eventos: didit:ready ({ sessionId }), didit:started, didit:step_started / didit:step_completed / didit:step_changed ({ step, ... }), didit:status_updated ({ status }), didit:completed ({ sessionId, status }), didit:cancelled, didit:error ({ error, step? }), didit:close_request e didit:layout ({ contentHeight, colorScheme, dir }, veja abaixo). A referência de eventos do SDK JavaScript lista os eventos de verificação disponíveis como callbacks tipados. A partir da versão 0.5.0, o SDK trata as mensagens de layout internamente, em vez de repassá-las para onEvent.

Dimensione o iframe a partir de `didit:layout`

A página de verificação informa quanto espaço precisa por meio de uma mensagem didit:layout. Ela envia uma ao carregar e outra sempre que a altura do conteúdo, o tema ou a direção do texto mudam:

{
  type: 'didit:layout',
  data: {
    contentHeight: 612,    // CSS px
    colorScheme: 'light',  // 'light' | 'dark'
    dir: 'ltr'             // 'ltr' | 'rtl'
  },
  timestamp: 1718000000000
}

Campo	Tipo	Descrição
`contentHeight`	`number`	A altura natural do conteúdo da página em pixels CSS, incluindo a barra superior
`colorScheme`	`'light' \| 'dark'`	O tema em que a página é exibida. Com cores de marca própria, quem decide é a sua cor de fundo, e não a configuração do dispositivo
`dir`	`'ltr' \| 'rtl'`	A direção do texto do idioma da página

Para receber didit:layout no seu próprio iframe, adicione sdk_presentation=embedded à URL de verificação dele. A partir da versão 0.5.0, o SDK JavaScript define a apresentação para você. Sem um parâmetro de apresentação, a página usa o layout autônomo e não envia mensagens de layout.

Este host segue os tamanhos recomendados: um card fixo a partir de 1024px de largura, tela cheia em 540px ou menos e, entre esses valores, um iframe de 500px de largura que assume a altura informada pela página:

<iframe
  id="didit-verification"
  class="didit-iframe"
  title="Didit verification"
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

<style>
  /* 541px to 1023px wide: 500px wide and as tall as the content */
  .didit-iframe {
    display: block;
    width: 500px;
    max-width: 100%;
    height: var(--didit-content-height, 700px); /* 700px until the first didit:layout */
    max-height: 90vh;
    max-height: 90dvh;
    margin: 0 auto;
    border: none;
    border-radius: 16px;
  }

  /* 1024px and wider: the computer card */
  @media (min-width: 1024px) {
    .didit-iframe {
      width: 960px;
      max-width: 90vw;
      height: 660px;
    }
  }

  /* 540px and below: full screen */
  @media (max-width: 540px) {
    .didit-iframe {
      position: fixed;
      inset: 0;
      width: 100%;
      height: 100vh;
      height: 100dvh;
      max-height: none;
      border-radius: 0;
    }
  }
</style>

<script>
  const DIDIT_ORIGIN = 'https://verify.didit.me'; // or your white-label domain
  const iframe = document.getElementById('didit-verification');

  // verificationUrl: the session `url` from your backend, or your UniLink
  const src = new URL(verificationUrl);
  src.searchParams.set('sdk_presentation', 'embedded');
  window.addEventListener('message', (event) => {
    if (event.origin !== DIDIT_ORIGIN || event.source !== iframe.contentWindow) return;
    const { type, data } = event.data || {};
    if (type !== 'didit:layout') return;
    const height = data?.contentHeight;
    if (typeof height !== 'number' || !Number.isFinite(height) || height <= 0) return;

    // Only the 541px to 1023px size reads it; the other two sizes are fixed
    iframe.style.setProperty('--didit-content-height', `${height}px`);
  });
  iframe.src = src.toString();
</script>

Entre 541px e 1023px, este exemplo usa uma altura inicial de 700px até chegar uma mensagem de layout, limitada a 90% da altura visível da janela. Os tamanhos para computador e celular são aplicados imediatamente. Nos celulares, o iframe cobre a janela, então ofereça no seu host uma forma de sair da verificação. Use colorScheme e dir para alinhar os controles que você desenhar ao redor do iframe ao tema e à direção do texto da página. Se a conexão do usuário cair, a página mostra uma tela de “Sem conexão com a internet”, que se fecha sozinha quando a conexão volta. Se o usuário escolher Exit Verification nessa tela, a página envia didit:error com error: "network_error" e, em seguida, didit:cancelled: feche o iframe ao receber didit:cancelled.

Para uma experiência de modal refinada que se sobrepõe à sua página:

HTML/CSS/JS

<!DOCTYPE html>
<html>
<head>
  <style>
    .didit-modal-overlay {
      display: none;
      position: fixed;
      inset: 0;
      background: rgba(0, 0, 0, 0.6);
      z-index: 9999;
      backdrop-filter: blur(4px);
    }
    
    .didit-modal-container {
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
      width: 90%;
      max-width: 480px;
      height: 85vh;
      max-height: 750px;
      background: white;
      border-radius: 16px;
      overflow: hidden;
      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    }
    
    .didit-modal-close {
      position: absolute;
      top: 12px;
      right: 12px;
      z-index: 10;
      width: 32px;
      height: 32px;
      border: none;
      background: rgba(0, 0, 0, 0.1);
      border-radius: 50%;
      cursor: pointer;
      font-size: 18px;
      display: flex;
      align-items: center;
      justify-content: center;
    }
    
    .didit-modal-close:hover {
      background: rgba(0, 0, 0, 0.2);
    }
    
    .didit-iframe {
      width: 100%;
      height: 100%;
      border: none;
    }
  </style>
</head>
<body>
  <button onclick="openVerification()">Verify Identity</button>

  <div id="didit-modal" class="didit-modal-overlay">
    <div class="didit-modal-container">
      <button class="didit-modal-close" onclick="closeVerification()">✕</button>
      <iframe 
        id="didit-iframe"
        class="didit-iframe"
        allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
      ></iframe>
    </div>
  </div>

  <script>
    const UNILINK_URL = 'https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64';
    
    function openVerification() {
      document.getElementById('didit-iframe').src = UNILINK_URL;
      document.getElementById('didit-modal').style.display = 'block';
      document.body.style.overflow = 'hidden';
    }
    
    function closeVerification() {
      document.getElementById('didit-iframe').src = '';
      document.getElementById('didit-modal').style.display = 'none';
      document.body.style.overflow = '';
    }
    
    // Close on escape key
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') closeVerification();
    });
    
    // Close on overlay click
    document.getElementById('didit-modal').addEventListener('click', (e) => {
      if (e.target.id === 'didit-modal') closeVerification();
    });
  </script>
</body>
</html>

Componente React

Um componente React reutilizável para verificação baseada em modal:

import { useState, useEffect } from 'react';

interface DiditInContextProps {
  /**
   * Either the `url` returned by POST /v3/session/ (API session)
   * or your UniLink URL copied from the Console (Workflows → Copy Link).
   * Don't derive the UniLink yourself — the path segment is a 22-character
   * base64url encoding of the workflow UUID's raw bytes, not btoa(workflowId).
   */
  verificationUrl: string;
  isOpen: boolean;
  onClose: () => void;
  onComplete?: (sessionId: string, status: string) => void;
}

export function DiditInContext({ 
  verificationUrl, 
  isOpen, 
  onClose,
  onComplete 
}: DiditInContextProps) {
  const [iframeSrc, setIframeSrc] = useState<string>('');

  useEffect(() => {
    if (isOpen) {
      setIframeSrc(verificationUrl);
      document.body.style.overflow = 'hidden';
    } else {
      setIframeSrc('');
      document.body.style.overflow = '';
    }
  }, [isOpen, verificationUrl]);

  // Listen for postMessage from iframe
  // Messages look like: { type: 'didit:<event>', data: {...}, timestamp }
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      // Use your white-label domain here if you have one configured
      if (event.origin !== 'https://verify.didit.me') return;

      if (event.data?.type === 'didit:completed' && onComplete) {
        onComplete(event.data.data?.sessionId, event.data.data?.status);
        onClose();
      }
    };

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [onComplete, onClose]);

  // Handle escape key
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape' && isOpen) onClose();
    };
    
    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div 
      className="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      onClick={(e) => e.target === e.currentTarget && onClose()}
    >
      <div className="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          onClick={onClose}
          className="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
          aria-label="Close"
        >
          ✕
        </button>
        <iframe 
          src={iframeSrc}
          className="w-full h-full border-0"
          allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
          title="Didit Verification"
        />
      </div>
    </div>
  );
}

Uso

import { useState } from 'react';
import { DiditInContext } from './DiditInContext';

function App() {
  const [isVerificationOpen, setIsVerificationOpen] = useState(false);
  
  return (
    <>
      <button onClick={() => setIsVerificationOpen(true)}>
        Verify Identity
      </button>
      
      <DiditInContext
        verificationUrl="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64" // UniLink from Console, or the API session `url`
        isOpen={isVerificationOpen}
        onClose={() => setIsVerificationOpen(false)}
        onComplete={(sessionId, status) => {
          console.log(`Verification ${status}: ${sessionId}`);
          if (status === 'Approved') {
            // Navigate to success page
          }
        }}
      />
    </>
  );
}

Componente Vue

<template>
  <Teleport to="body">
    <div 
      v-if="isOpen"
      class="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      @click.self="$emit('close')"
    >
      <div class="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          @click="$emit('close')"
          class="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
        >
          ✕
        </button>
        <iframe 
          :src="iframeSrc"
          class="w-full h-full border-0"
          allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
        />
      </div>
    </div>
  </Teleport>
</template>

<script setup lang="ts">
import { computed, watch, onMounted, onUnmounted } from 'vue';

const props = defineProps<{
  isOpen: boolean;
  // The `url` from POST /v3/session/, or your UniLink URL copied from the
  // Console (Workflows → Copy Link). Don't derive the UniLink with btoa() —
  // its path segment is base64url of the workflow UUID's raw bytes.
  verificationUrl: string;
}>();

const emit = defineEmits<{
  close: [];
  complete: [sessionId: string, status: string];
}>();

const iframeSrc = computed(() => (props.isOpen ? props.verificationUrl : ''));

// Handle escape key
const handleEscape = (e: KeyboardEvent) => {
  if (e.key === 'Escape' && props.isOpen) emit('close');
};

// Handle postMessage — messages look like { type: 'didit:<event>', data: {...}, timestamp }
const handleMessage = (event: MessageEvent) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;
  if (event.data?.type === 'didit:completed') {
    emit('complete', event.data.data?.sessionId, event.data.data?.status);
  }
};

onMounted(() => {
  document.addEventListener('keydown', handleEscape);
  window.addEventListener('message', handleMessage);
});

onUnmounted(() => {
  document.removeEventListener('keydown', handleEscape);
  window.removeEventListener('message', handleMessage);
});

// Lock body scroll when open
watch(() => props.isOpen, (isOpen) => {
  document.body.style.overflow = isOpen ? 'hidden' : '';
});
</script>

Configuração

Permissões necessárias

Use esta lista completa de permissões para captura, localização, cópia e compatibilidade de mídia:

allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"

Permissão	Para que serve e o que acontece sem ela
`camera`	Leitura do documento e captura facial. Sem ela, a câmera não inicia e o usuário vê orientações sobre o acesso à câmera
`microphone`	Áudio opcional durante a captura em vídeo do documento e do rosto. Sem ela, a captura continua sem áudio
`geolocation`	A etapa de localização lê a posição do dispositivo. Sem ela, o usuário vê O acesso à localização está desativado, mesmo que tenha permitido a localização no navegador
`clipboard-write`	Cópia da referência da sessão ou do link de verificação, inclusive na tela do navegador integrado ao app. Sem ela, a ação de copiar pode falhar e o usuário precisa copiar manualmente o texto visível ou o endereço do navegador
`fullscreen`	Permite que os controles de mídia solicitem tela cheia. Sem ela, esses controles ficam dentro do iframe
`autoplay`	Permite que vídeos de instrução e pré-visualizações da câmera sejam reproduzidos automaticamente, de acordo com as regras do navegador. Sem ela, a reprodução pode aguardar uma ação do usuário
`encrypted-media`	Mantida para compatibilidade com mídia protegida. As etapas de captura atuais não a exigem; sem ela, a reprodução de mídia protegida seria bloqueada
`digital-credentials-get`	Compartilhamento de uma identidade digital a partir de uma carteira como o Google Wallet por meio da Digital Credentials API do navegador. Sem ela, o navegador recusa a requisição da carteira dentro do seu iframe e o usuário não consegue compartilhar ali uma identidade da carteira

O atributo allow delega permissões; ele não substitui a escolha do usuário nem um cabeçalho Permissions-Policy mais restritivo na sua página de hospedagem.

Tamanho do iframe

O fluxo de verificação ajusta seu layout ao tamanho do iframe. Dimensione o iframe de acordo com a janela em que ele é exibido:

Largura da janela	Tamanho recomendado do iframe
1024px ou mais (computador)	960px por 660px, com no máximo 90% da largura e da altura da janela. Mantenha esse tamanho em todas as etapas
De 541px a 1023px	500px de largura e altura igual à do conteúdo: use a altura do `contentHeight` da mensagem `didit:layout`, com no máximo 90% da altura da janela
540px ou menos (celular)	Tela cheia: toda a largura e toda a altura visível da janela, sem cantos arredondados

Para a faixa intermediária, comece com 500px por 700px até a chegada da primeira mensagem didit:layout, com o mesmo limite de altura. O exemplo de didit:layout aplica os três tamanhos, incluindo os tamanhos para computador e celular antes da chegada de qualquer mensagem.

Política de Segurança de Conteúdo (CSP)

Se você usa CSP, adicione a Didit à sua diretiva frame-src:

Content-Security-Policy: frame-src https://verify.didit.me;

Verificação entre dispositivos

O iframe InContext oferece suporte automático à verificação entre dispositivos:

O usuário inicia a verificação no computador
Se a câmera não estiver disponível, um QR code é exibido
O usuário escaneia o QR code no celular
O usuário conclui a verificação no celular
O iframe no computador é atualizado automaticamente com o resultado

Isso acontece automaticamente, sem nenhuma configuração adicional.

Solução de problemas

A câmera não funciona

Certifique-se de que o iframe inclui a lista completa de permissões
Verifique se o seu site é servido via HTTPS
Confirme que o usuário concedeu permissão de câmera ao seu domínio
Experimente o método Redirect se o acesso à câmera no iframe falhar

O iframe não carrega

Verifique se há problemas com a Content Security Policy (CSP)
Adicione https://verify.didit.me à sua diretiva frame-src
Verifique se há erros no console do navegador

postMessage não recebido

Confirme que você está escutando a origem correta (https://verify.didit.me ou o seu domínio de marca própria)
Verifique se o listener de eventos é adicionado antes de abrir o iframe
Verifique o nome e o formato do evento: os tipos têm prefixo (didit:completed, não verification_complete) e o payload fica aninhado em event.data.data

Repositório de exemplo

Repositório no GitHub

Veja o código-fonte e exemplos no GitHub

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

Verificação de identidade por iframe: KYC web incorporado

Visão geral

Iframe com UniLink (sem backend)

O que você precisa

Implementação

Principais vantagens

Iframe com sessão via API (com backend)

Quando usar

Implementação

Monitoramento de eventos (postMessage)

Dimensione o iframe a partir de `didit:layout`

HTML/CSS/JS

Componente React

Uso

Componente Vue

Configuração

Permissões necessárias

Tamanho do iframe

Política de Segurança de Conteúdo (CSP)

Verificação entre dispositivos

Solução de problemas

A câmera não funciona

O iframe não carrega

postMessage não recebido

Repositório de exemplo

Repositório no GitHub

​Visão geral

​Iframe com UniLink (sem backend)

​O que você precisa

​Implementação

​Principais vantagens

​Iframe com sessão via API (com backend)

​Quando usar

​Implementação

​Monitoramento de eventos (postMessage)

​Dimensione o iframe a partir de didit:layout

​Implementação em modal

​HTML/CSS/JS

​Componente React

​Uso

​Componente Vue

​Configuração

​Permissões necessárias

​Tamanho do iframe

​Política de Segurança de Conteúdo (CSP)

​Verificação entre dispositivos

​Solução de problemas

​A câmera não funciona

​O iframe não carrega

​postMessage não recebido

​Repositório de exemplo

Repositório no GitHub

Visão geral

Iframe com UniLink (sem backend)

O que você precisa

Implementação

Principais vantagens

Iframe com sessão via API (com backend)

Quando usar

Implementação

Monitoramento de eventos (postMessage)

Dimensione o iframe a partir de `didit:layout`

Implementação em modal

HTML/CSS/JS

Componente React

Uso

Componente Vue

Configuração

Permissões necessárias

Tamanho do iframe

Política de Segurança de Conteúdo (CSP)

Verificação entre dispositivos

Solução de problemas

A câmera não funciona

O iframe não carrega

postMessage não recebido

Repositório de exemplo