Integraciones de API iGaming

Integración de API KYC para el registro de jugadores

El registro de un jugador combina la creación de su cuenta, la verificación de identidad y las decisiones del operador sobre las funciones que puede utilizar. Una integración KYC suele iniciar un flujo alojado, asociar un solicitante o una sesión del proveedor con la cuenta interna y recibir resultados asíncronos mediante webhooks o consultas de estado. Sin embargo, un resultado técnico de identidad no determina por sí solo las obligaciones legales ni autoriza el juego. Los requisitos de edad, prevención de lavado de dinero, evaluación de riesgo y conservación documental dependen del mercado, la licencia y el producto. Aquí distinguimos la evidencia del proveedor de las decisiones del operador y detallamos cómo controlar errores, datos sensibles y auditorías.

Tarjeta de identidad abstracta con escudo de verificación, escáner de documentos y servidores de API seguros
La verificación aporta evidencia; las autorizaciones de la cuenta permanecen bajo control del operador.
Contenido

¿En qué se diferencia KYC del registro de una cuenta?

El registro crea una cuenta reconocible dentro de los sistemas del operador. Conoce a tu cliente (KYC) reúne y evalúa evidencia para comprobar una identidad declarada, la edad u otros atributos necesarios. Que un proveedor apruebe una comprobación no concede automáticamente permiso para depositar, jugar o retirar fondos. Las obligaciones y los controles aplicables cambian según la jurisdicción. [4] [5]

Una arquitectura sólida separa el alta, la comprobación documental, la valoración de riesgo o AML y las autorizaciones del producto. Un jugador puede editar información básica mientras la revisión sigue pendiente, pero continuar sin acceso a operaciones reguladas. El rechazo o vencimiento de la verificación tampoco debe borrar movimientos financieros ni la historia de la cuenta. [1] [3]

¿Qué sistemas e identificadores deben relacionarse?

En el flujo participan el servicio de cuentas, las reglas de mercado y riesgo, un backend que coordina el registro, la API y el SDK del proveedor, un receptor de webhooks firmados, el motor de permisos y el registro de auditoría. Vincula de forma estable cada cuenta interna con su solicitante o sesión de verificación, sin enviar credenciales secretas al navegador. [1] [3]

Actor o registroPara qué sirveRegla de control
ID de cuentaReconocer al jugadorNo aceptar un ID libre del cliente
ID de solicitanteAgrupar evidencia externaAsociar a la cuenta autorizada
ID de sesiónIdentificar una revisiónSepararlo del ID de cuenta
Versión de políticaExplicar controles exigidosAdministración del operador
ID de eventoReconocer notificacionesDeduplicar antes de cambios
ID de decisiónRastrear permisosHistorial protegido y durable

Los nombres de los identificadores no son universales: algunos proveedores distinguen solicitantes y niveles, otros sesiones y decisiones. Conserva el ID original y la versión de cada adaptador. No incluyas datos de identidad en las URL de seguimiento ni en analítica general. [1] [3] [6]

¿Qué requisitos se resuelven antes de recolectar documentos?

Antes de abrir una sesión de verificación, determina qué normas del mercado, producto y riesgo aplican a la cuenta. Hay operaciones que requieren controles distintos durante el alta, el depósito o revisiones posteriores. La orientación de FATF describe diligencia debida basada en riesgo dentro de su alcance; no impone un procedimiento idéntico a todos los casinos. Confirma las obligaciones locales del operador. [4] [5]

  • Determina el mercado y la entidad operadora desde datos confiables, no únicamente desde un país editable.
  • Aplica los controles documentados de mayoría de edad, identidad, AML y escalamiento para ese producto.
  • Selecciona el flujo del proveedor y los documentos aceptables antes de solicitar evidencia.
  • Comunica el tratamiento de datos, su fundamento correspondiente y los pasos ante una revisión fallida o aplazada.

Solicitar por defecto todos los atributos disponibles eleva el riesgo sin aportar necesariamente valor. Las comprobaciones deben ser pertinentes y proporcionadas; el análisis adicional y la biometría requieren evaluación jurídica, de seguridad y del proveedor. Documenta quién puede cuestionar el resultado y cómo se realiza una revisión humana. [5] [6]

¿Cómo funciona el flujo completo de una API KYC?

El backend del operador crea un solicitante o una sesión con la configuración aprobada, obtiene una referencia temporal para un SDK o flujo alojado y permite al jugador entregar evidencia en el entorno previsto. El proveedor procesa la solicitud y envía un webhook. El backend verifica la autenticidad, reconcilia el estado vigente y evalúa la política de acceso antes de cambiar permisos. [1] [2] [3]

  1. Crea o reutiliza el solicitante correcto para el jugador autenticado.
  2. Inicia una sesión con controles definidos y abre el SDK o enlace alojado autorizado.
  3. Guarda los identificadores externos y el intento de alta; nunca publiques las claves permanentes de API.
  4. Valida la notificación firmada, confirma el estado real y aplica las reglas de permisos del operador.
Diagrama de tres columnas: cuenta y sesión del operador, captura de identidad y webhook firmado, decisión final de acceso y auditoría
El proveedor evalúa evidencia de identidad; el operador decide los servicios habilitados.

Una pantalla de finalización del SDK o una respuesta HTTP correcta al crear la sesión no significa que la identidad ya se aprobó. El usuario puede cerrar la ventana, la revisión puede continuar de forma asíncrona y quizá se solicite evidencia adicional. Mantén un estado pendiente real hasta contar con una respuesta confiable del servidor. [2] [3]

¿Cómo autenticar y reconciliar webhooks de KYC?

Los resultados suelen llegar después de la sesión inicial. Verifica la firma de autenticación sobre el cuerpo original de la solicitud con el mecanismo exigido por el proveedor. Comprueba que el solicitante y la sesión correspondan al jugador esperado; rechaza referencias de cuentas ajenas. Sumsub documenta comprobación mediante HMAC, pero otros proveedores usan esquemas distintos. Una conexión cifrada no sustituye la autorización. [2] [7]

  1. Lee el cuerpo sin modificar y verifica firma o prueba de autenticidad antes de aceptar el aviso.
  2. Comprueba la relación entre los ID externos, el jugador, el mercado y el intento de verificación vigente.
  3. Detecta eventos repetidos por su ID o por una identidad estable equivalente; guarda una transición controlada.
  4. Ante mensajes perdidos, antiguos o contradictorios, consulta el estado oficial del proveedor y reconcilia.

No habilites depósitos o juego por una devolución de éxito del navegador que no fue validada por el servidor. El receptor debe tolerar reenvíos, registrar únicamente metadatos seguros y contar con consultas o reprocesamiento ante interrupciones. Guarda y rota los secretos del webhook desde configuración protegida. [1] [2]

¿Cómo afectan los resultados a los permisos del jugador?

Las plataformas de identidad pueden indicar pendiente, en revisión, aprobado, rechazado o necesidad de volver a presentar documentos. Los valores y significados específicos cambian según la API. El operador debe traducirlos a una política documentada. Una revisión documental favorable no resuelve por sí sola controles de edad, sanciones, juego responsable o requisitos locales adicionales. [1] [3] [5]

Estado normalizadoAcción del operadorProtección clave
Sin iniciarOfrecer el flujo obligatorioNo asumir aprobación
Pendiente / revisiónRestringir acciones sujetas a controlConservar opción de continuar
Reenvío requeridoSolicitar evidencia concretaNo duplicar solicitante
Proveedor aprobóEvaluar políticas restantesSin habilitación global automática
Rechazo / escalamientoRestringir y revisarGuardar motivo y proceso de revisión

Define por separado qué decisiones afectan al registro, depósitos, apuestas, retiros y mantenimiento de la cuenta. Conserva quién aprobó, el momento, la versión de política y el fundamento en un registro auditable, sin duplicar todos los documentos entre servicios. [5] [6]

¿Qué controles de privacidad y conservación se necesitan?

Los documentos de identidad, atributos extraídos y datos biométricos merecen protección reforzada. Diseña el flujo para que el casino reciba solo los atributos necesarios para sus fines legítimos y limita el acceso a equipos y servicios autorizados. El artículo 5 del RGPD establece principios de finalidad, minimización, conservación y seguridad cuando ese régimen resulta aplicable; otras obligaciones pueden modificar plazos. [4] [6]

  • Documenta responsable y encargado, destinos de transferencia, base jurídica y contratos con cada proveedor.
  • Prefiere estados de verificación y atributos mínimos frente a copias innecesarias de documentos.
  • Cifra datos sensibles, restringe el acceso y elimina información personal de logs y herramientas analíticas.
  • Define calendarios de retención, atención a solicitudes, bloqueos legales y controles de auditoría.

El uso de biometría y determinadas decisiones automatizadas puede exigir garantías adicionales. Que un SDK incluya una función no demuestra que su uso esté permitido en el mercado. Trata las investigaciones y reverificaciones como finalidades controladas, con justificación y trazabilidad propias. [4] [6]

¿Cómo manejar fallas, repeticiones y reverificación?

Puede fallar la conexión entre la creación de sesión, la entrega de documentos, la revisión y la llegada del webhook. Repetir una petición no debe crear solicitantes sin relación ni provocar cambios incorrectos de acceso. Emplea identificadores de correlación duraderos, mecanismos de idempotencia compatibles con el proveedor, consultas de estado cuando existan y transiciones controladas por el operador. [1] [2]

  • Recupera sesiones abandonadas y reconexiones sin mezclar identidades de jugadores.
  • Deduplica avisos tardíos o reiterados y escala resultados finales contradictorios.
  • Concilia los casos inciertos en segundo plano y muestra un estado pendiente comprensible.
  • Inicia una nueva comprobación cuando lo exijan la política o evidencia confiable, conservando la decisión anterior.
  • Vigila firmas inválidas, tiempos de revisión, captura incompleta y acumulación de revisiones humanas.

Prevé interrupciones del proveedor, migración de solicitantes y actualizaciones de contrato. La atención al cliente y cumplimiento deben diferenciar errores técnicos, documentos pendientes, revisión de riesgo y rechazos confirmados para no comunicar conclusiones falsas. [3] [5]

¿Qué debe cubrir una prueba de aceptación de KYC?

La aceptación debe demostrar que la identidad se vincula a la cuenta correcta y que los permisos reales cambian de forma segura, no solo que el SDK se abre. Comprueba la entrega de evidencia, recepción de decisiones y bloqueo de acciones restringidas hasta completar los requisitos. Repite las pruebas según el mercado y configuración de cada flujo.

  1. Registra una cuenta de prueba, inicia la sesión correcta y comprueba los identificadores y el resultado válido.
  2. Intenta usar el ID o token de otra cuenta y verifica que la solicitud se rechace.
  3. Prueba espera, documentos adicionales, rechazo, vencimiento y revisión manual sin habilitar operaciones.
  4. Interrumpe y repite un webhook legítimo; envía una firma inválida y verifica reconciliación idempotente.
  5. Audita minimización de datos, autorizaciones, retención, alertas y derivación a revisión humana.

Antes del lanzamiento, exige conformidad de integración, seguridad, privacidad y cumplimiento donde corresponda, conserva resultados de pruebas y ensaya cómo desactivar el flujo. El objetivo principal es transformar evidencia validada en decisiones explicables sin filtrar información sensible ni permitir apuestas o pagos indebidamente. [2] [4] [6]

Fuentes y recursos adicionales

Visor de diagramas