Saltar al contenido principal
Usa un endpoint de wallet dedicado para verificar a una persona desde tu propia aplicación. No necesitas crear ni publicar un flujo de verificación (workflow), ni proporcionar un workflow_id. Tu backend inicia la verificación y obtiene su resultado; tu interfaz guía a la persona durante la autenticación exigida por la wallet.
Una integración por API sigue requiriendo que la persona se autentique y apruebe compartir su identidad. No puedes verificar a alguien enviando su identificador personal sin esa interacción.

Cómo funciona la verificación

  1. Tu backend consulta el catálogo de wallets y luego llama al endpoint de inicio de una wallet disponible con la clave de API de tu aplicación.
  2. Didit devuelve una referencia de verificación y la acción que debe realizar la persona.
  3. Tu aplicación abre la página de autenticación o muestra las instrucciones de aprobación de la wallet.
  4. La persona se autentica con su wallet.
  5. Tu backend obtiene el resultado de la verificación y gestiona las notificaciones de finalización.
La autenticación con wallet es asíncrona. Una solicitud de inicio exitosa significa que la autenticación ha comenzado; no significa que la identidad se haya verificado. Comprueba siempre el resultado final antes de considerar verificada a la persona.

Integración en el backend

Usa Listar wallets de identidad digital para obtener los endpoints actuales, los campos obligatorios y la disponibilidad para tu aplicación. Mantén tu x-api-key en tu backend. No la incluyas en un bundle del navegador ni en una aplicación móvil. Usa un Idempotency-Key distinto para cada nuevo intento de verificación y reutiliza esa clave al reintentar la misma solicitud de inicio. Cambiar la solicitud mientras reutilizas su clave es un conflicto, no un nuevo intento de verificación. Cada wallet tiene su propia URL de inicio, como /v3/id-verification/wallets/ftn/ para Finnish Trust Network. El request_id identifica la verificación independiente en las operaciones posteriores. Usa vendor_data para tu propia referencia, de hasta 2000 bytes UTF-8, y metadata para un objeto JSON opcional. Ambos se devuelven con el resultado y con el webhook de finalización. Estas operaciones usan la clave de API de la aplicación que inició la verificación. La disponibilidad del sondeo y de la autenticación depende de la wallet seleccionada. Una cancelación rechaza una verificación pendiente sin cobrarla, y devuelve sin cambios una verificación ya completada. En Smart-ID y Mobile-ID, una cancelación que llega mientras un sondeo está comprobando la aprobación espera unos segundos a que termine ese sondeo. Después rechaza la verificación, o la devuelve como verified si la persona ya la había aprobado. No se puede cancelar una verificación que la persona está completando en ese momento: la respuesta es 409 con error: "verification_in_progress" y un encabezado Retry-After. Reintenta pasados esos segundos para leer el resultado completado.

Registra tu destino de retorno

Las wallets con redirección devuelven a la persona a tu aplicación tras la autenticación. Registra el nombre de host exacto antes de iniciar una verificación:
Después envía un return_url HTTPS, como https://app.example.com/identity/complete, en la solicitud de inicio. Usa nombres de host simples en allowed_return_hosts, sin esquema, ruta ni comodín. Registra por separado cada subdominio que uses, hasta 20 nombres de host. Actualizar allowed_return_hosts reemplaza la lista registrada, así que incluye todos los nombres de host que quieras conservar. GET /v3/webhook/ devuelve la lista actual; consulta Configuración de webhooks. No necesitas un flujo ni un dominio de marca blanca para registrar un destino de retorno. El destino es una página de retorno en el navegador; configura por separado los webhooks de finalización para tu backend.

Ejemplo: Finnish Trust Network

Después de registrar tu nombre de host de retorno, inicia una verificación con Finnish Trust Network:
Guarda el request_id devuelto y envía el navegador de la persona a wallet_verification.next_action.url cuando el type sea redirect. Cuando la persona regrese, obtén el resultado desde tu backend:
Comprueba wallet_verification.outcome: Usa la identidad solo cuando el resultado sea verified y simulated sea false para una comprobación de identidad real. Una respuesta pendiente puede incluir una siguiente acción; las respuestas finales no tienen siguiente acción.

Experiencias de autenticación

Las wallets con redirección devuelven una URL de autenticación. Abre esa URL en el navegador de la persona, deja que complete el proceso de autenticación de la wallet y redirígela a tu destino registrado. Consulta el resultado desde tu backend en lugar de confiar en un parámetro de la URL de retorno como prueba de identidad. Smart-ID y Mobile-ID usan una solicitud de aprobación en el teléfono de la persona. Tu interfaz recoge el identificador personal requerido; Mobile-ID también necesita el número de teléfono asociado. Muestra el código de comparación e indica a la persona que apruebe solo cuando coincida con el código de su teléfono. Su PIN se introduce en la wallet o en la solicitud del teléfono, nunca en tu formulario ni en una solicitud a la API. Consulta el estado desde tu backend cada poll_interval_seconds devuelto para obtener actualizaciones sobre la solicitud. Didit también comprueba en segundo plano las aprobaciones pendientes en el teléfono, por lo que la finalización puede llegar a tu webhook después de que la persona cierre tu página. Google Wallet se solicita desde tu propia página o aplicación mediante la Digital Credentials API, sin redirección; consulta Wallets de Digital Credentials (Google Wallet). La interacción disponible depende de la wallet seleccionada. No des por hecho que todas las wallets admiten un formulario integrado, un código QR o la autenticación sin navegador.

Wallets de Digital Credentials (Google Wallet)

Google Wallet se solicita directamente desde tu página web o tu aplicación Android, mediante la W3C Digital Credentials API. No hay redirección, ni página alojada por Didit, ni código QR de Didit. En producción está en Próximamente: funciona con aplicaciones de sandbox y en staging, y el acceso en producción depende de la aprobación de Google. Consulta Listar wallets de identidad digital para ver qué puede iniciar tu aplicación ahora.
1

Inicia con tu origen

Tu backend llama a POST /v3/id-verification/wallets/google-wallet/ con el country de la persona (USA, GBR, BRA, SGP o TWN) y el origin que solicitará la wallet. El origin es el origen HTTPS de tu página, como https://app.example.com, cuyo host debe ser uno de tus nombres de host de retorno registrados o tu dominio de marca blanca. Para una aplicación Android es android:apk-key-hash: seguido del SHA-256 en base64 del certificado de firma de tu aplicación, sin relleno. La wallet rechaza cualquier solicitud hecha desde otro origen. No hay return_url.
2

Solicita la wallet dentro de un gesto del usuario

La respuesta contiene wallet_verification.interaction = "digital_credentials" y next_action.type = "request_digital_credential". Pasa next_action.digital_credentials.request al navegador o a Android Credential Manager, como respuesta a un toque o clic en la página del origin con el que iniciaste. En escritorio, el navegador muestra su propio código QR cuando la wallet está en otro dispositivo.
3

Envía lo que devolvió la wallet

Envía el {protocol, data} devuelto a tu backend y, desde allí, a POST /v3/id-verification/wallets/verifications/{request_id}/response/ como {"response": {...}}. La solicitud solo se puede enviar una vez; un segundo envío devuelve la verificación ya decidida.
4

Consulta el resultado

La respuesta al envío es la verificación decidida. También puedes consultarla con GET /v3/id-verification/wallets/verifications/{request_id}/ o recibirla en el webhook de finalización.
En el navegador, solicita la wallet desde un manejador de clic:
Ofrece el método solo donde el navegador lo admita, por ejemplo cuando "DigitalCredential" in window sea verdadero. navigator.credentials.get debe ejecutarse dentro de un gesto del usuario, así que llámalo desde el manejador de clic y no después de un paso asíncrono. En Android, usa Jetpack Credential Manager (androidx.credentials 1.5.0 o posterior) con la misma solicitud:
Errores que debes gestionar: Una credencial que no supera la verificación es una verificación decidida con resultado failed, no una respuesta de error. Solo salen de la wallet los campos que solicita la verificación, y el resultado contiene los atributos de identidad que devolvió la wallet. Un pase de identificación de Google Wallet o una licencia de conducir móvil de un estado de EE. UU. no devuelve un retrato. En una aplicación de sandbox, el flujo se simula con los mismos pasos y devuelve simulated: true. Cualquier respuesta enviada decide la verificación según el sandbox_scenario, de modo que puedes construir todo el recorrido en el navegador o en la aplicación sin una credencial real.

Webhooks de finalización

Configura un destino de webhook de la aplicación para status.updated siguiendo la guía de integración de webhooks. Usa webhook_version: "v3" para la estructura de decisión descrita aquí. Verifica la firma del webhook en tu backend antes de procesarlo. El session_id del webhook coincide con el request_id devuelto por la API de wallets. Una identidad de wallet finalizada aparece en el array decision.id_verifications del webhook con verification_method: "wallet". También puedes usar el identificador para obtener el resultado de la API de wallets dedicada. Gestiona las notificaciones de aprobación y rechazo, incluidas las verificaciones canceladas y expiradas. Haz que tu manejador de webhooks sea idempotente, porque las entregas fallidas se reintentan. Un retorno del navegador no es un webhook de finalización y sus parámetros de consulta no son prueba de identidad.

Identidad devuelta

Usa los campos de identidad normalizados para los nombres y las fechas de nacimiento cuando se proporcionen. Los atributos específicos de cada wallet describen la información de identidad compartida por la wallet seleccionada. Los atributos disponibles varían según la wallet y el país. Una identidad autenticada no implica que estén disponibles un retrato, una dirección ni el resto de los atributos solicitados.

Pruebas en sandbox

Una aplicación en modo sandbox de Didit simula la verificación con wallet sin contactar con un proveedor de wallets ni consumir créditos. La respuesta identifica estas solicitudes con wallet_verification.simulated: true. Una aprobación simulada contiene datos de ejemplo, no una identidad real verificada. En una wallet con redirección, sigue la URL devuelta para probar el callback y el regreso a tu aplicación. En Smart-ID o Mobile-ID, usa el endpoint de consulta periódica para completar la aprobación simulada; no se envía ninguna notificación a ningún teléfono. Para probar la gestión de errores, establece sandbox_scenario en wallet_cancelled, wallet_timeout o wallet_provider_error al iniciar una solicitud. Las aplicaciones en producción rechazan sandbox_scenario. La simulación en el sandbox de Didit es independiente de las pruebas en el entorno de pruebas del propio proveedor. Que la simulación funcione no garantiza el acceso al proveedor en producción ni la disponibilidad en producción.

Sandbox del proveedor ConnectID

El sandbox del proveedor ConnectID utiliza bancos de prueba y es independiente de la simulación en el sandbox de Didit. Cuando el acceso al sandbox del proveedor esté configurado para tu integración, pasa el authorisation_server_id del banco seleccionado al endpoint de inicio de ConnectID. Usa el ID devuelto por el selector de bancos de ConnectID; no envíes la URL de un banco ni un emisor arbitrario. Si omites el campo, se selecciona el banco de prueba predeterminado. El campo es exclusivo de ConnectID y no cambia los atributos de identidad solicitados. El conjunto inicial solicita el nombre, los apellidos y la fecha de nacimiento. Sigue el next_action devuelto para autenticarte y, después, obtén el resultado de la verificación o consúltalo periódicamente. Solo un resultado completado con estado aprobado confirma que la verificación se realizó correctamente; el regreso a tu aplicación no lo confirma. ConnectID sigue marcado como Coming soon en producción mientras se completan el onboarding y la certificación.

Disponibilidad y precios

La cobertura de endpoints y la activación de wallets en producción son cuestiones distintas. Una wallet puede tener una página de referencia de la API y seguir sin estar disponible para la autenticación en producción. Comprueba la cobertura de países de la wallet y su estado en producción antes de implementar un flujo en producción. Consulta los precios de las wallets de identidad digital para ver las tarifas publicadas y la disponibilidad. La verificación de wallets se factura por separado de la captura de documentos.

Cómo elegir una integración

Usa estas API cuando quieras controlar la interfaz y la lógica de aplicación que las rodean. Usa la API de sesiones cuando quieras el recorrido de verificación alojado de Didit, las reglas del flujo de verificación (workflow) y los pasos alternativos configurados. Ambos enfoques siguen requiriendo el proceso de autenticación y consentimiento de la wallet.
Última modificación el 1 de noviembre de 2026