Pular para o conteúdo principal

Como incorporar o link de KYC Onboarding no seu site?

Depois de gerar um linkOnboarding com o endpoint POST /api/v1/kyc/onboarding, você pode entregá-lo ao merchant de três formas:

  1. Redirecionamento — enviar o merchant diretamente para a página de KYC (recomendado)
  2. Nova aba / popup — abrir o KYC sem perder o contexto do seu site
  3. Iframe — renderizar o KYC dentro de uma página do seu site

Este guia cobre as três abordagens e como detectar a conclusão do onboarding.

Pré-requisitos

Antes de incorporar, você precisa ter o linkOnboarding em mãos. Caso ainda não tenha, siga Como criar um onboarding KYC via API?.

Referência completa

Para o schema, parâmetros e exemplos interativos do endpoint que gera o linkOnboarding, veja a API Reference.

Opção 1 — Redirecionamento (recomendado)​

A forma mais simples e segura de integrar é redirecionar o merchant diretamente para o linkOnboarding. O merchant preenche todo o cadastro na página da Woovi e, quando terminar, você pode trazê-lo de volta via um botão no seu sistema ou consultando o status pela API.

<a href="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5..." >
  Iniciar cadastro KYC
</a>

Ou, programaticamente:

window.location.href = data.linkOnboarding;

Opção 2 — Nova aba / popup​

Se você quer manter o merchant no seu site enquanto ele preenche o KYC, abra o link em uma nova aba:

<a
  href="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5..."
  target="_blank"
  rel="noopener noreferrer"
>
  Iniciar cadastro KYC
</a>

Ou como popup:

const popup = window.open(
  data.linkOnboarding,
  'woovi-kyc',
  'width=480,height=800',
);

Opção 3 — Iframe​

O frontend de KYC não envia headers X-Frame-Options nem Content-Security-Policy: frame-ancestors, então é possível renderizá-lo dentro de um <iframe> no seu site.

<iframe
  src="https://kyc.woovi.com/onboarding/QWNjb3VudFJlZ2lzdGVyOjY5..."
  width="100%"
  height="900"
  style="border: 0; max-width: 640px;"
  title="Cadastro KYC"
  allow="camera; clipboard-read; clipboard-write"
></iframe>

Atributos recomendados​

AtributoValor sugeridoPor quê
width100% (até ~640px)O formulário é otimizado para telas estreitas/mobile
height900 ou maisO formulário é multi-step e pode precisar de scroll interno
allowcamera; clipboard-read; clipboard-writeÚtil para upload de documentos via câmera e colar dados
titleCadastro KYCAcessibilidade

Limitações do iframe​

  • Não há comunicação postMessage do KYC para a página pai. Você não recebe eventos de "formulário enviado" ou "passo concluído" dentro do iframe.
  • Para saber quando o merchant finalizou o cadastro, você precisa consultar o status via API.
  • Upload de arquivos dentro de iframe pode ter restrições em alguns navegadores mobile — teste o fluxo completo antes de subir para produção.

Detectando a conclusão do onboarding​

A API não envia webhook quando o merchant conclui o cadastro. Para saber em que estágio ele está, consulte o status do AccountRegister usando o correlationID ou taxID enviados na criação.

Estados possíveis​

StatusSignificado
PENDINGLink criado, merchant ainda não submeteu
IN_REVIEWMerchant submeteu — em análise pela equipe
APPROVEDCadastro aprovado
REJECTEDCadastro rejeitado

Estratégias​

  • Polling: consulte a cada N minutos, especialmente se o merchant estiver dentro de um iframe
  • Callback manual: coloque um botão "Já finalizei o cadastro" no seu site que dispara a consulta
  • Verificação antes de liberar funcionalidades: consulte o status sempre que o merchant tentar acessar recursos que dependem de KYC aprovado

Exemplo completo — backend + iframe​

// 1. Crie o onboarding a partir do seu backend
app.post('/start-kyc', async (req, res) => {
  const { taxID, correlationID } = req.body;

  const response = await fetch('https://api.woovi.com/api/v1/kyc/onboarding', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': process.env.WOOVI_APPID,
    },
    body: JSON.stringify({
      taxID,
      correlationID,
    }),
  });

  const data = await response.json();

  // Devolva apenas o link para o frontend (nunca o AppID!)
  res.json({ linkOnboarding: data.linkOnboarding });
});

Pré-visualização​

Selecione um status para renderizar o linkOnboarding correspondente:

Nunca exponha o AppID no frontend

Sempre gere o linkOnboarding no seu backend. O AppID é uma credencial sensível e não deve ser enviado para o navegador.

Boas práticas​

  • Use sempre HTTPS na página que hospeda o iframe — browsers bloqueiam iframes HTTP em páginas HTTPS.
  • Envie um correlationID único (ex: o ID do pedido no seu sistema) para facilitar a consulta de status depois.
  • Reutilize o link: a API é idempotente por correlationID. Se o merchant fechar o site antes de terminar, você pode devolver o mesmo link sem criar um registro novo.
  • Comunique o passo ao merchant: antes de abrir o iframe/redirect, explique que ele será levado para o cadastro da Woovi.
  • Trate o retorno: após detectar APPROVED, libere as funcionalidades do BaaS no seu produto.