> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de verificación con wallets de identidad digital

> Didit verifica la identidad mediante una wallet de identidad digital desde tu propia aplicación, sin crear un flujo de verificación.

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.

> [!NOTE]
>
> 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](https://docs.didit.me/es/standalone-apis/digital-id-wallet-catalog.md) 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](https://docs.didit.me/es/standalone-apis/digital-id-wallet-catalog.md) 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.

| Operación | Endpoint |
| - | - |
| Consultar estado y resultado | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Sondear una aprobación en el teléfono | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Enviar una respuesta de wallet de Digital Credentials | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Cancelar una verificación pendiente | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

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:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

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](https://docs.didit.me/es/sessions-api/management-api.md#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:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

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:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Comprueba `wallet_verification.outcome`:

| Resultado | Significado |
| - | - |
| `pending` | La autenticación sigue en curso. |
| `verified` | La autenticación se completó y la identidad devuelta está verificada. |
| `cancelled` | La persona o tu aplicación canceló el intento. |
| `timeout` | El plazo de autenticación expiró. |
| `failed` | La autenticación o la validación de la identidad falló. |

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)](#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](https://docs.didit.me/es/standalone-apis/digital-id-wallet-catalog.md) 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](#registra-tu-destino-de-retorno) 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`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**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:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

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:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Errores que debes gestionar:

| Error | Dónde | Significado |
| - | - | - |
| `origin_invalid` | Inicio, `400` | `origin` no es un origen HTTPS ni un origen de aplicación Android. |
| `origin_not_allowed` | Inicio, `400` | El host del origen no está registrado para tu aplicación. Regístralo en `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Envío, `409` | Esta verificación no acepta una respuesta de wallet. |

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](https://docs.didit.me/es/integration/webhooks.md).
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](https://docs.didit.me/es/api-reference/digital-id-wallets/connectid.md).
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](https://docs.didit.me/es/getting-started/pricing.md#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](https://docs.didit.me/es/sessions-api/create-session.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.