Guía: cómo integrar una API KYC en 1 día (paso a paso técnico)

Key takeaways (TL; DR)
 

Con Didit es posible integrar verificación de identidad completa en cuestión de horas y lanzar hoy mismo.

La solución puede empezar con un flujo rápido sin código y, cuando crezca el proyecto, ampliarse con la API para tener más flexibilidad.

El plan principal de KYC es gratuito e ilimitado, lo que permite escalar sin añadir costes desde el primer día.

La plataforma está pensada para no romper la experiencia del usuario y, al mismo tiempo, cumplir con las exigencias de cumplimiento.

Integrar una API de KYC suele ser mucho más complicado de lo que debería. En muchas ocasiones, la documentación técnica deja huecos importantes en puntos críticos, los entornos sandbox no son los mismos que en producción o los webhooks fallan sin explicación. Si sabes de qué hablamos, esta guía es para ti.

Con la API de KYC de Didit pasarás de cero a verificación de identidad completa en apenas unas horas. Hablamos de un flujo totalmente real de verificación de documentos y biometría, con Face Match 1:1 y Liveness Pasivo, además de todo lo necesario para controlar en tiempo real en qué estado se encuentran las verificaciones, con webhooks firmados y un entorno sandbox que se comporta como en producción. Aunque si incluso prefieres lanzar todavía más rápido, puedes orquestar todo con un flujo de verificación No-Code y salir a producción en pocos minutos.

Pero, ¿sabes qué es lo mejor de la API de KYC de Didit? Que es totalmente gratis. Podrás verificar las identidades de forma gratuita e ilimitada, para comenzar a escalar tu plataforma.

Ten en cuenta que esta guía está escrita por y para desarrolladores: el objetivo es que tu flujo de verificación funcione bien, con sesiones que se aprueben en pocos segundos y estados comprensibles. Así que si buscabas “cómo integrar una API de KYC en un día”, estás en el sitio correcto.

¿Qué es una integración de KYC y por qué es esencial para las empresas?

Integrar una solución de KYC permite a las empresas cumplir con los requisitos de verificación de identidad mediante un proveedor de verificación de identidad. Estas integraciones permiten automatizar la validación de usuarios, clave para cumplir con las normativas de prevención de blanqueo de capitales.

Habitualmente, las integraciones de KYC se llevan a cabo mediante API (que permite más flexibilidad) o con una URL de verificación (más velocidad). Decidir la forma en la que incorporas estas herramientas a tu flujo depende de las necesidades únicas de tu negocio.

¿Por qué es importante el KYC para las empresas?

1. Automatiza un proceso que era meramente manual. Los equipos de cumplimiento podían pasar horas verificando la información provista por un usuario durante el onboarding; ahora esta tarea puede realizarse de forma segura en pocos segundos.
2. Cumple con las normativas de KYC. Las regulaciones evolucionan para combatir fraudes cada vez más sofisticados. Una API de KYC ayuda a garantizar el cumplimiento normativo, asegurando que todas las verificaciones están actualizadas y en regla.
3. Mejor protección contra el fraude. Utilizar una API de KYC permite decir adiós a procesos manuales y a posibles errores humanos. Además, una capa de detección de fraude ayuda a bloquear identidades sintéticas, deepfakes o documentos alterados o generados por IA.
4. Optimización de los procesos. Al reducir el trabajo manual, los equipos de compliance pueden centrarse en lo que realmente importa: revisar en tiempo real perfiles de riesgo y detectar patrones o indicios de fraude.
5. Escalabilidad sin límites. Los procesos manuales de verificación generaban cuellos de botella. Automatizar el onboarding elimina ese problema, permitiendo que los usuarios accedan en segundos sin renunciar a seguridad ni precisión.
6. Ahorros significativos. Integrar KYC reduce tiempo, recursos y costes. Con Didit, los ahorros pueden llegar hasta un 70% respecto a proveedores legacy.

Cómo integrar la API de KYC de Didit (y salir a producción hoy mismo)

La integración estándar con Didit se apoya en un workflow alojado por Didit, una sesión de verificación por usuario, una URL de verificación para ejecutar el flujo y webhooks firmados para sincronizar estados en tiempo real. El circuito mínimo consiste en crear la sesión con tu workflow_id, enviar al usuario a la url de verificación, recibir el webhook con la decisión y, si fuera necesario, consultar el resultado por API. Gracias a la modularidad de Didit, además, puedes añadir capas como AML Screening, Prueba de Domicilio o Estimación de Edad sin reescribir la base.

Consulta la documentación completa (API Full Flow) si tienes alguna duda al respecto.

Antes de comenzar: API Key, Webhook Secret y configuración del Webhook

Accede a la Business Console (registro gratuito) y ve a API & Webhooks, que lo encuentras en la columna de la izquierda. Allí obtendrás tu API Key (para autenticarte con la cabecera X-Api-Key) y el Webhook Secret Key (para verificar la firma de los webhooks).

En el mismo panel configura el Webhook URL que Didit usará para notificar cambios de estado.

Guarda estos valores en variables de entorno (.env); deben tener esta forma:

API_KEY=<YourApiKey>
WEBHOOK_SECRET_KEY=<YourWebhookSecretKey>
WEBHOOK_URL=https://tuapp.com/api/webhooks/didit

Crea la sesión de verificación

El siguiente paso es llamar al servicio de verificación. Este es un ejemplo de código, deberás sustituir los datos que se muestran (workflow_id; callback o API_KEY) por tu información real.

POST /v2/session/
Host: verification.didit.me
Content-Type: application/json
X-Api-Key: {YourApiKey}

{
  "workflow_id": "11111111-2222-3333-4444-555555555555",  // Replace with your chosen workflow
  "callback": "<https://example.com/verification/callback>",
  "vendor_data": "user-123",  // Your user identifier
  "metadata": {
  	"user_type": "premium",
  	"account_id": "ABC123"
  },
  "contact_details": {
  	"email": "john.doe@example.com",
  	"email_lang": "en",
  	"phone": "+14155552671"
  }
}

La respuesta incluye, entre otros, session_id, status inicial y url para dirigir a los usuarios al flujo alojado por Didit:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "user-123",
  "metadata": { "user_type": "premium", "account_id": "ABC123" },
  "status": "Not Started",
  "workflow_id": "example_workflow_id",
  "callback": "<https://example.com/verification/callback>",
  "url": "<https://verify.didit.me/session/abcdef123456>"
}

Encontrarás más información detallada y otros ejemplos de código en la sección Crear Sesión, dentro de nuestra documentación técnica.

Ejecuta la UI de verificación (redirige o embeber)

Con la url de verificación, puedes redirigir al usuario (opción más simple) o embeber el flujo en un <iframe> si quieres mantener tu layout. Didit orquesta la captura de documento, selfie y liveness según tu workflow.

Al finalizar cada paso, la sesión avanza de estado y se notificará por webhook.

Resultados de la sesión de verificación

Los resultados de cada verificación llegan de dos formas: Webhooks (opción recomendada) o consulta por API. Con Webhooks, tu backend recibe notificaciones en tiempo real cada vez que cambie el estado de la sesión; así evitas polling y mantienes una única fuente de verdad.

Para garantizar la legitimidad del Webhook, valida siempre la firma enviada en la cabecera X-Signature usando tu WEBHOOK_SECRET_KEY. Además, comprueba la cabecera X-Timestamp y rechaza peticiones fuera de una ventana corta (por ejemplo, 5 minutos) para prevenir fraudes.

En la sección de Webhooks dentro de la documentación técnica encontrarás toda la información sobre estas alertas, así como otros ejemplos de código.

Si en algún momento necesitas reconciliar estados (por ejemplo, si un Webhook no llegó), puedes consultar la decisión bajo demanda:

GET <https://verification.didit.me/v2/session/{sessionId}/decision/>
X-Api-Key: <YourApiKey>

De forma consistente, mapea los estados en tu sistema (por ejemplo: Not Started → In Progress → In Review → Approved / Declined / Abandoned) y refleja cada transición en la UI y en tus métricas. Esto evita ambigüedades entre producto, soporte y analítica.

Para más control y flexibilidad, las APIs independientes de verificación

¿Buscas más flexibilidad y control sobre tu flujo de verificación? Las APIs independientes de Didit te ayudan a conseguirlo. Además de la API de KYC, que te permite verificar la identidad de los usuarios de forma integral (con ID Verification, Face Match 1:1 y Liveness Pasivo), podrás construir tus procesos de verificación y validación a medida o con enfoques muy específicos, añadiendo aquellas funcionalidades que necesites para personalizar tu flujo al detalle.

¿Qué puedes hacer con las APIs independientes de Didit?

• ID Verification, que te permite verificar un documento de identidad, y extraer la información más relevante.
• Face Match 1:1, que te permite cotejar la imagen del documento con un selfie tomado en tiempo real.
• Age Estimation, que te permite estimar la edad para ofrecer un onboarding sin fricciones en productos o servicios limitados a ciertos rangos de edad.
• Proof of Address, que te permite verificar el domicilio de un usuario en base a documentación oficial y facturas de servicios.
• AML Screening, que te permite cotejar la identidad de los usuarios contra distintas listas de vigilancia, sanciones, PEPs y medios adversos.
• Face Search 1:N, que te permite comprobar un rostro en una base de datos, para impedir duplicados.
• Liveness Pasivo, que te permite garantizar la presencia real del usuario durante la verificación.
• Database Validation, que te permite validar una identidad contra bases de datos nacionales y globales (verificación 1x1 y 2x2).
• Phone Verification, que te permite verificar los números de teléfono de tus usuarios mediante códigos OTP.
• Email Verification, que te permite verificar los correos electrónicos de tus usuarios mediante códigos OTP.

¿Cuánto cuesta utilizar una API de KYC?

Didit ofrece el único plan gratuito e ilimitado de verificación de identidad. Eso quiere decir que el coste de utilizar la API de KYC es cero, independientemente de que la utilices una única vez o cientos de veces.

Sin letra pequeña, contratos o packs cerrados. Didit es una alternativa sencilla, abierta, flexible y económica, que ofrece ahorros de hasta el 70% con respecto a alternativas consolidadas. El modelo se basa en funcionalidades opcionales (AML Screening, Proof of Address, Phone/Email Verification, etc.) y en el uso de APIs independientes.

Consulta precios de APIs independientes.