Saltar al contenido principal

Crear sesión de verificación KYC

Endpoint para generar una nueva sesión de verificación KYC (OCR + FACE + AML) para el usuario autenticado y devolver una URL para completar el proceso.

🧾 Inicio del flujo KYC

Este endpoint crea una sesión temporal de KYC y devuelve una URL que el usuario debe abrir para completar la verificación con el proveedor (OCR + selfie/face + chequeos AML).

POST/kyc/create-session

Crea una sesión de verificación KYC y devuelve la URL de verificación

📤 Respuesta

{
"code": 1000,
"message": "Sesión de KYC creada",
"data": {
  "url": "https://example.kycprovider.com/session/abc123"
}
}

Requiere autenticación​

JWT requerido

Debes enviar un token JWT válido en el header:

Authorization: Bearer <token>

Respuesta exitosa​

Sesión creada (1000)

{
  "code": 1000,
  "message": "Sesión de KYC creada",
  "data": {
    "url": "https://example.kycprovider.com/session/abc123"
  }
}

Campo principal:

  • url: enlace que el usuario debe abrir para completar la verificación.

Uso recomendado en frontend​

Recomendación: mantener al usuario en flujo

La URL devuelta debe abrirse en el contexto más conveniente según plataforma.

  • Web: iframe (si el proveedor lo permite)
  • Mobile: navegador embebido o ventana externa

Web (iframe)​

<iframe src="{url}" width="100%" height="600px" frameborder="0"></iframe>

App móvil (ejemplo Flutter)​

// Flutter (ejemplo)
launchUrl(Uri.parse(url), mode: LaunchMode.externalApplication);

Expiración y almacenamiento​

Sesión temporal

  • La sesión de KYC expira tras 10 minutos
  • El backend almacena la sesión en Redis: kyc:&lt;session_id&gt; → &lt;user_id&gt;
  • El frontend debe monitorear finalización (polling o callback según integración)

Errores​

Errores conocidos

CódigoMensajeDescripción
2001User not authenticatedToken JWT inválido o ausente
5001Error creating KYC sessionFallo interno al crear la sesión (Redis, proveedor, etc.)

Formato de error

{
  "code": 5001,
  "message": "Error creating KYC session",
  "id": "KYC-SESSION-XX98"
}

Notas​

Consideraciones

  • La URL debe abrirse lo antes posible por la expiración.
  • Si el usuario no completa el flujo, se debe crear una nueva sesión.
  • Idealmente, exponer un estado KYC en el perfil para reflejar avance (pendiente / en revisión / aprobado / rechazado).