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
- 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.
- A Didit retorna uma referência da verificação e a ação que a pessoa precisa realizar.
- A sua aplicação abre a página de autenticação ou exibe as instruções de aprovação da carteira.
- A pessoa se autentica com a sua carteira.
- O seu backend obtém o resultado da verificação e trata as notificações de conclusão.
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 suax-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: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: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:
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 intervalopoll_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."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:
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 parastatus.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 comwallet_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 oauthorisation_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.