Passar para o conteúdo principal

Migração para o novo fluxo de KYC

Prazo para adequação: 30/07/2026

Em atendimento às novas exigências regulatórias, o fluxo atual de KYC será descontinuado em 30/07/2026.

Após essa data, apenas o novo fluxo estará disponível e todas as novas contas deverão utilizar o novo processo de validação de identidade.

Este artigo reúne todas as informações necessárias para que parceiros API e White Label compreendam as alterações, os impactos da migração e as ações necessárias para adequação.

O que muda?

O processo de KYC foi remodelado para separar as etapas de cadastro, validação de identidade e envio de documentos.

A principal mudança é que a validação de identidade deixa de ocorrer através do fluxo antigo e passa a utilizar uma WebView exclusiva para cada pessoa participante do processo.

Isso significa que cada participante possui:

  • Sua própria sessão;

  • Seu próprio Signup Token;

  • Sua própria validação de identidade;

  • Seu próprio resultado de análise.

A conta somente será ativada quando todas as validações obrigatórias forem concluídas e aprovadas.

Cronograma

Data de descontinuação

O fluxo atual será desligado em:

30/07/2026

Após essa data ele não poderá mais ser utilizado.

Haverá período de convivência?

Não.

O fluxo antigo será completamente substituído.

Todos os parceiros deverão concluir sua homologação antes da data de corte.

Novo fluxo

Novo fluxo

Upload realizado pela WebView

Documentos enviados diretamente pelo usuário

Nova WebView

Uma sessão para cada participante

Um Signup Token para cada entidade

Captura realizada na WebView

Como funciona o novo fluxo

O onboarding continua iniciando pela criação da conta.

Após a criação:

  1. São geradas as sessões de validação;

  2. São disponibilizados os Signup Tokens;

  3. Cada participante realiza sua biometria;

  4. Os documentos são enviados pela WebView;

  5. Ocorre a análise;

  6. Após todas as aprovações obrigatórias, a conta é ativada.

Fluxo para Pessoa Física

Para contas de Pessoa Física:

  • Existe apenas um participante;

  • O titular realiza toda a validação;

  • É gerado um único Signup Token.

O cadastro continua sendo realizado normalmente pela API.

Os documentos deixam de ser enviados pelo backend do parceiro.

Fluxo para Pessoa Jurídica

Para contas de Pessoa Jurídica:

todos os sócios deverão realizar sua própria validação.

Quando houver representantes legais cadastrados e obrigatórios para aquele processo, eles também deverão realizar a biometria.

Caso a biometria expire, tenha uma rejeição ou necessidade de nova sessão, é possível reenviar o link para validação da biometria.

Cada participante possui:

  • Signup Token próprio;

  • Sessão própria;

  • Status próprio;

  • Resultado próprio.

A conta somente poderá avançar quando todas as validações obrigatórias forem concluídas.

Representantes legais

Representantes legais não são obrigatórios em todos os cenários.

Eles podem ser cadastrados quando houver necessidade jurídica ou operacional.

Representantes devidamente autorizados poderão, após análise e aprovação manual, realizar etapas de validação de identidade em nome da empresa ou de um ou mais sócios.

O cadastro de um representante:

  • Não elimina automaticamente a obrigatoriedade de cadastro dos sócios;

  • Não elimina automaticamente a validação dos sócios;

  • Não garante substituição automática;

  • Depende de análise e aprovação manual;

  • Deve respeitar a legislação e os documentos de representação apresentados.

Tipos de representantes suportados

O campo de representantes legais pode ser utilizado para cadastrar os seguintes tipos de relacionamentos:

  • Representante legal (legal_representative);

  • Procurador (attorney_in_fact);

  • Representante estrangeiro (representative_foreign).

Informações necessárias para o cadastro

Ao cadastrar um representante legal, deverão ser informados os dados cadastrais da pessoa, incluindo:

  • Tipo de relacionamento;

  • CPF;

  • Nome completo;

  • Data de nascimento;

  • E-mail;

  • Telefone;

  • Renda mensal;

  • Endereço completo (logradouro, número, complemento, bairro, CEP, cidade e UF).

Signup Token

O Signup Token identifica a sessão de validação de cada participante.

Cada entidade possui um token exclusivo.

O token não deve ser reutilizado entre pessoas diferentes.

Como o token é criado?

Após a criação da conta, os Signup Tokens ficam disponíveis para consulta.

Não é necessário criar manualmente um token inicial.

Validade

Cada Signup Token possui validade de:

72 horas

Quando ele pode ser reutilizado?

Pode ser reutilizado quando:

  • A sessão ainda não foi concluída;

  • Ainda está dentro das 72 horas.

Será necessário gerar um novo token quando:

  • Houver rejeição da identidade;

  • O token expirar;

  • A sessão já tiver sido concluída.

Reenvio do token

Caso seja necessário gerar uma nova sessão, deverá ser utilizada a rota de reenvio de Signup Token.

Em contas PJ é possível recriar apenas a sessão de um participante específico.

Nova WebView

Toda validação passa a utilizar a nova WebView.

Durante o processo o usuário:

  • Aceita os termos;

  • Realiza a prova de vida;

  • Envia os documentos;

  • Finaliza a sessão.

Importante:

A conclusão da WebView não significa que a identidade foi aprovada.

Ela apenas indica que as informações foram enviadas para análise.

Status da conta

O fluxo esperado permanece:

Pendente ↓ Aguardando Documentos ↓ Em revisao ↓ Ativo

A alteração dos status ocorre automaticamente.

O parceiro não deve alterar manualmente o status da conta.

O que foi descontinuado?

Deixam de existir:

  • SDK antigo de biometria;

  • Aplicação antiga de biometria;

  • Rota antiga /biometrics;

  • Upload de selfie pelo backend do parceiro;

  • Upload de RG;

  • Upload de CNH;

  • Upload de documentos de identidade pelo backend;

  • Utilização do POST /documents para documentos de identidade.

O que continua funcionando?

O endpoint de documentos permanece disponível apenas para:

  • Contrato social;

  • Estatuto;

  • Documento societário equivalente.

Esses documentos continuam podendo ser enviados normalmente.

Documentos

Os documentos de identidade passam a ser enviados exclusivamente pela WebView.

Não devem mais ser enviados pelo backend do parceiro.

A presença de um documento na consulta não significa que a identidade foi aprovada.

Sempre utilize:

  • Status da conta;

  • Webhooks;

  • Consulta da API.

Webhooks

O novo fluxo disponibiliza Webhooks específicos para acompanhamento do processo.

Eventos de identidade

  • identity_verification.approved

  • identity_verification.rejected

  • identity_verification.expired

Eventos de documentos

  • document.upload.success

  • document.upload.failed

Os Webhooks podem ser recebidos mais de uma vez.

A integração deve tratar os eventos de forma idempotentes.

Como acompanhar corretamente o processo

Recomendamos utilizar conjuntamente:

  • WebView

  • Webhooks

  • Consulta da API

Não recomendamos depender exclusivamente de:

  • Polling;

  • Webhooks;

  • Conclusão da WebView.

Contas existentes

Contas ativas

Nenhuma ação é necessária.

Contas pendentes

Contas que permanecerem pendentes durante a migração serão avaliadas individualmente.

Isso inclui contas em:

  • Awaiting Documents;

  • Awaiting Corrections;

  • Waiting Analysis;

  • Under Review;

  • Demais estados equivalentes.

Parceiros White Label

Os parceiros White Label não precisarão realizar desenvolvimento para utilizar o novo fluxo.

Entretanto, é importante compreender as alterações no processo de abertura de contas, principalmente em relação à nova experiência de validação de identidade e ao funcionamento da biometria.

Parceiros API

Os parceiros que utilizam integração via API deverão realizar a adequação de suas implementações antes da data de corte.

Entre os principais pontos de atenção estão:

  • Utilização da nova WebView;

  • Consulta do Signup Token;

  • Tratamento dos novos Webhooks;

  • Remoção do upload de documentos de identidade pelo backend;

  • Implementação da renovação do Signup Token;

  • Utilização das rotas recomendadas para consulta de documentos.

Checklist de migração

Antes de publicar em produção, confirme que:

  • O fluxo antigo foi removido;

  • A nova WebView foi implementada;

  • Os Signup Tokens são consultados corretamente;

  • O reenvio de tokens está implementado;

  • Os Webhooks estão sendo tratados;

  • A consulta de documentos utiliza a rota recomendada;

  • O upload de documentos de identidade pelo backend foi removido;

  • Foram homologados cenários de aprovação, rejeição e expiração.

❓Perguntas Frequentes (FAQ)

Cronograma e migração

1. O fluxo anterior será desligado em 30/07/2026?

Sim. A desativação está prevista para 30/07/2026 e decorre de exigência regulatória.

2. Haverá convivência entre os fluxos?

Não. O corte será direto.

3. Onde o novo fluxo pode ser homologado?

No ambiente:

https://seu_tenant.idez.dev

Criação da conta e onboarding

4. A conta é criada sem documentos?

Sim. O cadastro pela API permanece apenas cadastral.

5. Qual status a conta recebe após a criação?

A conta inicia com o status Pending e avança automaticamente para Awaiting Documents, conforme a representação utilizada pela API.

6. O campo Fingerprint continua obrigatório?

Sim.

Validação de identidade

7. Quem precisa realizar a biometria em uma conta Pessoa Física?

O titular da conta.

8. Quem precisa realizar a biometria em uma conta Pessoa Jurídica?

Todos os sócios obrigatórios e os representantes que fizerem parte do processo aplicável.

9. MEI possui fluxo diferente?

Não. MEI, ME e demais pessoas jurídicas utilizam o mesmo modelo de validação individual.

Representantes legais

10. Representante legal é obrigatório?

Não.

11. O representante substitui automaticamente um sócio?

Não. A substituição depende de autorização, documentação, análise e aprovação manual.

12. O cadastro do representante elimina a validação dos sócios?

Não automaticamente.

Signup Token

13. Cada sócio possui um Signup Token diferente?

Sim.

14. Quando os Signup Tokens são criados?

Após a criação da conta, para as entidades aplicáveis.

15. Qual é a validade do Signup Token?

72 horas.

16. O Signup Token pode ser reutilizado?

Sim, durante as 72 horas, desde que a sessão ainda não tenha sido finalizada.

17. O que fazer quando o usuário fecha a WebView antes de concluir?

Reabra a mesma URL enquanto o Signup Token estiver válido.

18. O que fazer quando a identidade é rejeitada?

Solicite uma nova sessão utilizando a rota de reenvio do Signup Token.

19. O que fazer quando o Signup Token expira?

Solicite uma nova sessão utilizando a rota de reenvio.

20. A Idez pode enviar o link por e-mail?

Sim. A rota de reenvio possui o campo send_email. Ainda assim, o parceiro deve acompanhar o processo por meio dos Webhooks e da API.

WebView

21. Qual é a nova URL da biometria?

[URL_TENANT]/signup/biometrics?token={signup_token}

22. A URL biometrics-app.idez.com.br continuará funcionando?

Ela está sendo descontinuada e não deve ser utilizada em novas integrações.

23. O que significa o postMessage de conclusão?

Significa que o usuário concluiu a interação com a WebView.

24. O postMessage confirma a aprovação da identidade?

Não.

25. Como saber se a identidade foi aprovada?

Por meio do evento identity_verification.approved, da consulta pela API e do status da conta.

Webhooks

26. Quais Webhooks de identidade existem?

  • identity_verification.approved

  • identity_verification.rejected

  • identity_verification.expired

27. Quais Webhooks de documentos existem?

  • document.upload.success

  • document.upload.failed

28. O Webhook identifica qual sócio foi processado?

Sim. Por meio dos campos entity_type e entity_id.

29. O Webhook informa o CPF e o nome?

Os eventos de identidade informam os campos document e name.

30. O Webhook de upload informa o motivo detalhado do erro?

Ele informa uma mensagem textual no campo error, porém atualmente não existe um catálogo padronizado de códigos de rejeição.

31. Os Webhooks podem ser enviados mais de uma vez?

Sim. A integração deve tratar os eventos de forma idempotente.

32. Como validar a origem dos Webhooks?

Utilize o header Signature e valide o HMAC-SHA256 do corpo utilizando o secret cadastrado.

33. Qual é o timeout de entrega?

3 segundos por tentativa.

34. Existem retentativas?

Sim. Até 3 tentativas utilizando backoff exponencial.

35. O Webhook de expiração sempre será enviado?

Pode não ser enviado em situações raras de ambiguidade envolvendo múltiplas entidades pendentes.

36. Como tratar possíveis eventos ausentes?

Implemente a reconciliação utilizando a API.

Documentos

37. Qual rota deve ser utilizada para consultar documentos?

GET /v2/admin/accounts/{account}/documents

38. A rota /documents/status deve ser utilizada?

Ela pode existir por compatibilidade, mas não deve ser utilizada como rota principal em novas integrações.

39. O parceiro ainda deve enviar RG, CNH ou selfie?

Não. Esses documentos passam a ser enviados exclusivamente pela WebView.

40. Para que serve o endpoint POST /documents?

Somente para envio de contrato social ou documento societário equivalente, quando aplicável.

41. O contrato social pode ser enviado pelo BackOffice?

Sim.

Status da conta

42. A conta fica ativa quando uma pessoa conclui a WebView?

Não necessariamente. Todas as validações obrigatórias devem ser concluídas e aprovadas.

43. Qual é o fluxo de status esperado?

O fluxo esperado é:

Pending → Awaiting Documents → Under Review → Active

Podem existir estados intermediários ou nomenclaturas equivalentes.

Contas existentes

44. Contas já ativas precisam migrar?

Não.

45. O que acontece com contas pendentes na data da migração?

Serão avaliadas manualmente pela Idez e pelo provedor financeiro, caso a caso.

46. Sócios que enviaram documentos no fluxo anterior precisarão refazer o processo?

Não existe uma regra única para todas as contas pendentes. Cada caso será avaliado individualmente.

Cartão

47. Parceiros que não trabalham com cartão precisam implementar Cardholder?

Não.

48. Existe alguma outra dependência relacionada a cartão para utilização do novo KYC?

Não para parceiros que não emitem cartão.

Informações gerais

49. A aprovação do upload significa aprovação da identidade?

Não. O upload dos documentos representa apenas uma etapa do processo de validação.

50. Qual é a fonte definitiva em caso de divergência?

Em caso de divergência, prevalecem a documentação vigente da API, os payloads efetivamente retornados pelos endpoints e os comunicados oficiais da Idez.

A migração para o novo fluxo de KYC representa uma evolução importante no processo de validação de identidade, proporcionando maior segurança, padronização e conformidade com os requisitos regulatórios.

Recomendamos que todos os parceiros revisem suas integrações e processos operacionais com antecedência, realizem a homologação do novo fluxo e validem todos os cenários aplicáveis antes da data de descontinuação do fluxo atual.

Em caso de dúvidas durante a implementação ou necessidade de suporte, nossa equipe permanece à disposição para auxiliar durante o processo de migração. Após a conclusão da adequação, todas as novas contas deverão utilizar exclusivamente o novo fluxo de KYC.

Respondeu à sua pergunta?