Pular para o conteúdo principal
Use um endpoint dedicado de carteira para verificar uma pessoa a partir da sua própria aplicação. Você não precisa criar nem publicar um fluxo de verificação (workflow), nem informar um workflow_id. O seu backend inicia a verificação e obtém o resultado; a sua interface conduz a pessoa pela autenticação exigida pela carteira.
Uma integração via API continua exigindo que a pessoa se autentique e aprove o compartilhamento da sua identidade. Não é possível verificar alguém enviando o identificador pessoal dessa pessoa sem essa interação.

Como a verificação funciona

  1. O seu backend consulta o catálogo de carteiras e, em seguida, chama o endpoint de início de uma carteira disponível usando a chave de API da sua aplicação.
  2. A Didit retorna uma referência da verificação e a ação que a pessoa precisa realizar.
  3. A sua aplicação abre a página de autenticação ou exibe as instruções de aprovação da carteira.
  4. A pessoa se autentica com a sua carteira.
  5. O seu backend obtém o resultado da verificação e trata as notificações de conclusão.
A autenticação por carteira é assíncrona. Uma requisição de início bem-sucedida significa que a autenticação começou; não significa que a identidade foi verificada. Sempre confira o resultado final antes de tratar a pessoa como verificada.

Integração no backend

Use Listar carteiras de identidade digital para obter os endpoints atuais, os campos obrigatórios e a disponibilidade para a sua aplicação. Mantenha a sua x-api-key no backend. Não a coloque em um bundle de navegador nem em uma aplicação mobile. Use uma Idempotency-Key distinta para cada nova tentativa de verificação e reutilize essa chave ao tentar novamente a mesma requisição de início. Alterar a requisição reutilizando a chave dela é um conflito, não uma nova tentativa de verificação. Cada carteira tem sua própria URL de início, como /v3/id-verification/wallets/ftn/ para a Finnish Trust Network. O request_id identifica a verificação independente nas operações seguintes. Use vendor_data para a sua própria referência, com até 2.000 bytes UTF-8, e metadata para um objeto JSON opcional. Ambos são retornados no resultado e no webhook de conclusão. Essas operações usam a chave de API da aplicação que iniciou a verificação. A consulta periódica (polling) e a disponibilidade da autenticação dependem da carteira selecionada. Um cancelamento recusa uma verificação pendente sem cobrar por ela e retorna uma verificação concluída sem alterações. Para Smart-ID e Mobile-ID, um cancelamento que chega enquanto uma consulta está verificando a aprovação aguarda alguns segundos por essa consulta. Em seguida, ele recusa a verificação ou a retorna como verified se a pessoa já tiver aprovado. Uma verificação que a pessoa está concluindo naquele momento não pode ser cancelada: a resposta é 409 com error: "verification_in_progress" e um cabeçalho Retry-After. Tente novamente depois desse número de segundos para ler o resultado concluído.

Registre o seu destino de retorno

Carteiras com redirecionamento enviam a pessoa de volta à sua aplicação após a autenticação. Registre o hostname exato antes de iniciar uma verificação:
Depois, envie uma return_url HTTPS, como https://app.example.com/identity/complete, na requisição de início. Use apenas hostnames em allowed_return_hosts, sem esquema, caminho ou curinga. Registre separadamente cada subdomínio que você usa, até 20 hostnames. Atualizar allowed_return_hosts substitui a lista registrada, então inclua todos os hostnames que deseja manter. GET /v3/webhook/ retorna a lista atual; consulte Configuração de webhook. Você não precisa de um fluxo nem de um domínio de marca própria para registrar um destino de retorno. O destino é uma página de retorno no navegador; configure os webhooks de conclusão separadamente para o seu backend.

Exemplo: Finnish Trust Network

Depois de registrar o seu hostname de retorno, inicie uma verificação pela Finnish Trust Network:
Salve o request_id retornado e envie o navegador da pessoa para wallet_verification.next_action.url quando o type da ação for redirect. Depois que a pessoa retornar, obtenha o resultado a partir do seu backend:
Confira wallet_verification.outcome: Use a identidade somente quando o resultado for verified e simulated for false, no caso de uma verificação de identidade real. Uma resposta pendente pode trazer uma próxima ação; respostas finais não têm próxima ação.

Experiências de autenticação

Carteiras com redirecionamento retornam uma URL de autenticação. Abra essa URL no navegador da pessoa, deixe que ela conclua o processo de autenticação da carteira e leve-a de volta ao destino que você registrou. Leia o resultado pelo seu backend em vez de confiar em um parâmetro da URL de retorno como prova de identidade. Smart-ID e Mobile-ID usam uma solicitação de aprovação no celular da pessoa. Sua interface coleta o identificador pessoal exigido; o Mobile-ID também precisa do número de telefone associado. Exiba o código de comparação e oriente a pessoa a aprovar somente quando ele corresponder ao código mostrado no celular dela. O PIN dela deve ser digitado na carteira ou na solicitação do celular, nunca no seu formulário nem em uma requisição de API. Faça polling pelo seu backend no intervalo poll_interval_seconds retornado para acompanhar a solicitação. A Didit também verifica em segundo plano as aprovações pendentes no celular, então a conclusão pode chegar ao seu webhook depois que a pessoa fechar sua página. O Google Wallet é solicitado pela sua própria página ou aplicativo por meio da Digital Credentials API, sem redirecionamento; consulte Carteiras Digital Credentials (Google Wallet). A interação disponível depende da carteira selecionada. Não presuma que toda carteira oferece suporte a formulário incorporado, QR code ou autenticação sem navegador.

Carteiras de credenciais digitais (Google Wallet)

O Google Wallet é acionado diretamente pela sua página web ou pelo seu aplicativo Android, usando a W3C Digital Credentials API. Não há redirecionamento, nem página hospedada pela Didit, nem QR code da Didit. Ele está como Em breve em produção: funciona com aplicações de sandbox e em staging, e o acesso em produção depende da aprovação do Google. Consulte Listar carteiras de identidade digital para ver o que sua aplicação já pode iniciar.
1

Inicie com a sua origem

Seu backend chama POST /v3/id-verification/wallets/google-wallet/ com o country da pessoa (USA, GBR, BRA, SGP ou TWN) e o origin que vai acionar a carteira. O origin é a origem HTTPS da sua página, como https://app.example.com, cujo host deve ser um dos seus hostnames de retorno registrados ou o seu domínio de marca própria. Para um aplicativo Android, é android:apk-key-hash: seguido do SHA-256 em base64 do certificado de assinatura do seu aplicativo, sem padding. A carteira recusa uma requisição feita a partir de qualquer outra origem. Não há return_url.
2

Acione a carteira em resposta a um gesto do usuário

A resposta contém wallet_verification.interaction = "digital_credentials" e next_action.type = "request_digital_credential". Passe next_action.digital_credentials.request para o navegador ou para o Android Credential Manager, a partir de um toque ou clique no origin com que você iniciou. No desktop, o navegador exibe o próprio QR code quando a carteira está em outro dispositivo.
3

Envie o que a carteira retornou

Envie o {protocol, data} retornado ao seu backend e, de lá, para POST /v3/id-verification/wallets/verifications/{request_id}/response/ como {"response": {...}}. A requisição pode ser enviada uma única vez; um segundo envio retorna a verificação já concluída.
4

Leia o resultado

A resposta do envio é a verificação concluída. Você também pode lê-la com GET /v3/id-verification/wallets/verifications/{request_id}/ ou recebê-la no webhook de conclusão.
No navegador, acione a carteira a partir de um handler de clique:
Ofereça o método somente onde o navegador oferecer suporte, por exemplo quando "DigitalCredential" in window for verdadeiro. navigator.credentials.get deve ser executado em um gesto do usuário, então chame-o a partir do handler de clique, e não depois de uma etapa assíncrona. No Android, use o Jetpack Credential Manager (androidx.credentials 1.5.0 ou posterior) com a mesma requisição:
Erros a tratar: Uma credencial que não passa na verificação gera uma verificação concluída com resultado failed, e não uma resposta de erro. Somente os campos solicitados pela verificação saem da carteira, e o resultado contém os atributos de identidade que a carteira retornou. Um passe de identidade do Google Wallet ou uma carteira de motorista digital de um estado dos EUA não retorna foto do rosto. Em uma aplicação de sandbox, o fluxo é simulado com as mesmas etapas e retorna simulated: true. Qualquer resposta enviada define o resultado da verificação de acordo com o sandbox_scenario, então você pode construir toda a jornada no navegador ou no aplicativo sem uma credencial real.

Webhooks de conclusão

Configure um destino do webhook da aplicação para status.updated usando o guia de integração de webhooks. Use webhook_version: "v3" para obter a estrutura de decisão descrita aqui. Verifique a assinatura do webhook no seu backend antes de processá-lo. O session_id do webhook corresponde ao request_id retornado pela API de carteira. Uma identidade de carteira concluída aparece no array decision.id_verifications do webhook com verification_method: "wallet". Você também pode usar o identificador para obter o resultado da API dedicada de carteira. Trate as notificações de aprovação e de recusa, incluindo verificações canceladas e expiradas. Torne o handler do seu webhook idempotente, porque entregas com falha são reenviadas. Um retorno pelo navegador não é um webhook de conclusão, e seus parâmetros de consulta não são prova de identidade.

Identidade retornada

Use os campos de identidade normalizados para nomes e datas de nascimento quando esses campos forem retornados. Os atributos específicos de cada carteira descrevem as informações de identidade compartilhadas pela carteira selecionada. Os atributos disponíveis variam conforme a carteira e o país. Uma identidade autenticada não significa que um retrato, o endereço ou qualquer outro atributo solicitado esteja disponível.

Testar no sandbox

Uma aplicação no modo sandbox da Didit simula a verificação por carteira sem contatar um provedor de carteira e sem consumir créditos. A resposta identifica essas requisições com wallet_verification.simulated: true. Uma aprovação simulada são dados de exemplo, não uma identidade real verificada. Para uma carteira com redirecionamento, acesse a URL retornada para testar o callback e voltar à sua aplicação. Para Smart-ID ou Mobile-ID, use o endpoint de polling para concluir a aprovação simulada; nenhuma notificação é enviada a um telefone. Para testar o tratamento de falhas, defina sandbox_scenario como wallet_cancelled, wallet_timeout ou wallet_provider_error ao iniciar uma requisição. Aplicações em produção rejeitam sandbox_scenario. A simulação no sandbox da Didit é diferente de testar no ambiente de testes do próprio provedor. Uma simulação bem-sucedida não garante acesso ao provedor em produção nem disponibilidade em produção.

Sandbox do provedor ConnectID

O sandbox do provedor ConnectID usa bancos de teste e é diferente da simulação no sandbox da Didit. Quando o acesso ao sandbox do provedor estiver configurado para a sua integração, envie o authorisation_server_id do banco selecionado ao endpoint de início do ConnectID. Use o ID retornado pelo seletor de bancos do ConnectID; não envie a URL de um banco nem um emissor arbitrário. Se você omitir o campo, o banco de teste padrão será selecionado. O campo é específico do ConnectID e não altera os atributos de identidade solicitados. O pacote inicial solicita nome, sobrenome e data de nascimento. Siga o next_action retornado para se autenticar e, em seguida, recupere o resultado da verificação ou consulte-o por polling. Somente um resultado concluído com status aprovado confirma que a verificação foi bem-sucedida; o retorno à sua aplicação não confirma isso. O ConnectID continua como Coming soon em produção enquanto o onboarding e a certificação são concluídos.

Disponibilidade e preços

A cobertura de endpoints e a ativação das carteiras em produção são coisas distintas. Uma carteira pode ter uma página de referência da API e continuar indisponível para autenticação em produção. Verifique a cobertura de países e o status de produção da carteira antes de implementar uma jornada em produção. Consulte os preços das carteiras de identidade digital para ver as tarifas publicadas e a disponibilidade. A verificação de carteira é faturada separadamente da captura de documentos.

Como escolher uma integração

Use estas APIs quando quiser controlar a interface e a lógica da aplicação ao redor da verificação. Use a Sessions API quando quiser a jornada de verificação hospedada da Didit, as regras do fluxo de verificação (workflow) e as etapas alternativas configuradas. Nas duas abordagens, o processo de autenticação e consentimento da carteira continua sendo obrigatório.
Última modificação em 1 de novembro de 2026