API de Verificación y riesgo de transacciones

Usa una clave API de la plataforma para iniciar desde tus propios sistemas verificaciones de persona (KYC), verificaciones de empresa (KYB), monitoreo de transacciones y análisis de direcciones de billetera, y para consultar los registros de verificación. La API abierta y la consola siguen el mismo proceso de verificación: los mismos precios y las mismas reglas de resultados, reembolsos y conciliación.

Primero haz clic en «Habilitar» en «Verificación y riesgo de transacciones» de la consola; luego crea una clave en «Gestión de API» y otórgale los permisos de «Verificación y riesgo»: verification.read para consultar precios y registros, y verification.write para iniciar verificaciones. Cada verificación se cobra del saldo de tu cuenta.

Endpoints de la API

• GET /api/v1/verification/info: Devuelve si tu cuenta tiene el servicio habilitado, si cada uno de los cuatro tipos de verificación está disponible y su precio (USD), y las redes y activos disponibles para el monitoreo de transacciones y el análisis de billeteras. Los tipos no disponibles no tienen precio.
• POST /api/v1/verification/checks: Inicia una verificación; el cobro y la creación del registro ocurren en la misma solicitud. Las verificaciones de identidad devuelven un handoff_url (enlace de traspaso) que envías a la persona verificada; el monitoreo de transacciones y el análisis de billeteras suelen devolver el resultado directamente.
• GET /api/v1/verification/checks: La lista se ordena por fecha de inicio, de la más reciente a la más antigua, y se puede filtrar por kind, status, verdict y keyword (referencia, dirección o n.º de cobro), con page y page_size para paginar (hasta 100 por página). La consulta de un solo registro incluye handoff_url mientras la sesión siga en manos de la persona verificada. Actualizar vuelve a leer el resultado desde el proveedor (el análisis de billetera no se puede actualizar, porque analizar de nuevo se cobra de nuevo).

Reintentar con el mismo idempotency_key y el mismo contenido devuelve el registro original sin volver a cobrar; reutilizar una clave con otro contenido se rechaza (400). Si vuelves a iniciar una verificación de identidad para una referencia de sujeto cuya sesión aún no termina, se devuelve esa sesión (reused es true), también sin cobro.

Callbacks de resultados

En «Configuración de integración» de la consola, ingresa una URL de callback https y actívala. Cuando el estado o el resultado de un registro de verificación cambia de forma asíncrona (verificación de identidad terminada, resultado cambiado por una revisión manual, resultado de transacción actualizado, fallida y reembolsada), la plataforma envía un evento por POST. La llamada con la que tú mismo inicias la verificación no se notifica, porque su respuesta síncrona ya trae el resultado.

El encabezado X-Tovanix-Event es el tipo de evento (check.updated, o ping para pruebas), X-Tovanix-Delivery es el event_id, X-Tovanix-Timestamp son segundos Unix y X-Tovanix-Signature es sha256= seguido del HMAC-SHA256(secreto de firma, marca de tiempo + "." + cuerpo original de la solicitud) en hexadecimal.

Una respuesta 2xx cuenta como entregada. Cualquier otra, incluidos los tiempos de espera agotados, se reintenta con retroceso de 1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas y 12 horas, hasta 8 intentos en total; después ya no se envía. Los reintentos envían el mismo event_id y el mismo cuerpo, así que deduplica por event_id. Los eventos pueden llegar desordenados: quédate con el que tenga el data.updated_at más reciente, o llama al endpoint de consulta para obtener el estado más actual. Si desactivas el callback, los eventos aún no entregados ya no se envían.

Páginas relacionadas: Verificación y riesgo de transacciones · Verificación de identidad: personas y empresas · Control de riesgo de transacciones: monitoreo y análisis de billeteras · Documentación de la API