Saltar al contenido principal
En esta guía describimos los controles de seguridad y protección que se aplican al crear payouts con la API de Transferencias de Fintoc. Estos controles ayudan a asegurar que solo las partes autorizadas puedan iniciar movimientos de dinero, que las solicitudes no se puedan alterar en tránsito y que la actividad de payouts pueda ser revisada y auditada.

​
1. Autenticar todas las solicitudes a la API con API keys

Cada solicitud a la API de Fintoc debe incluir una API key.
  • Las API keys son únicas por organización.
  • La key se muestra solo una vez al momento de su creación en el Dashboard de Fintoc.
  • Debes almacenar la key de forma segura.
  • Si una key se pierde o es comprometida, rótala o revócala de inmediato desde el Dashboard.
Las API keys identifican a la organización que llama y previenen el acceso no autorizado a la API. 📚 Administrar API keys

​
2. Firmar todas las solicitudes de movimiento de dinero con JWS

Las solicitudes que mueven dinero, como crear transferencias salientes, requieren una capa adicional de seguridad usando JSON Web Signatures (JWS). Cada solicitud de payout se firma utilizando:
  • Una llave privada JWS, almacenada de forma segura en tu lado
  • Una llave pública JWS, registrada en el Dashboard de Fintoc
Las llaves JWS son estáticas, pero cada firma es única y limitada en el tiempo. Esto se logra incluyendo:
  • Un nonce, que hace que cada firma sea de un solo uso.
  • Un timestamp ts, que limita por cuánto tiempo es válida la solicitud.
La firma JWS:
  • Protege la integridad del payload de la solicitud
  • Confirma la autenticidad del remitente
  • Previene ataques de replay
Fintoc rechaza automáticamente las solicitudes que no estén firmadas, hayan expirado, estén duplicadas o hayan sido modificadas. 📚 Configurar llaves JWS

​
3. Restringir el acceso a la API con allowlist de IP (opcional)

Puedes configurar una allowlist de IP en el Dashboard de Fintoc para controlar desde dónde pueden originarse las solicitudes a la API. Cuando la allowlist de IP está habilitada:
  • Las solicitudes se aceptan solo desde direcciones IP aprobadas
  • Las solicitudes desde otras ubicaciones se bloquean, incluso si la API key es válida
Este control reduce el riesgo en caso de fuga de credenciales y aplica restricciones de acceso a nivel de infraestructura. 📚 Configurar la allowlist de IP

​
4. Verificar las firmas de los webhooks

Fintoc firma todos los eventos de webhook antes de enviarlos a tus sistemas. Siempre debes verificar las firmas de los webhooks antes de procesar un evento. Esto te permite:
  • Confirmar que el evento fue enviado por Fintoc
  • Detectar manipulaciones del payload
  • Descartar solicitudes de webhook falsificadas o reenviadas
Verificar las firmas de los webhooks asegura que los sistemas downstream reaccionen solo a eventos confiables. 📚 Validar firmas de webhooks

​
5. Prevenir payouts duplicados con idempotencia

Para evitar payouts duplicados accidentales, Fintoc admite mecanismos de idempotencia al crear payouts. Cuando se usa idempotencia:
  • Las solicitudes reintentadas no crean transferencias duplicadas
  • Los timeouts de red y los reintentos del cliente pueden manejarse de forma segura
La idempotencia mejora la seguridad y confiabilidad operativa, especialmente en escenarios de fallos o reintentos. 📚 Usar una idempotency key

​
6. Auditar el uso de la API

Todas las interacciones con la API de Fintoc son rastreables y auditables. Esto incluye:
  • Identificación basada en API key de la organización que llama
  • Solicitudes con marca de tiempo para operaciones sensibles
  • Registro de la creación de transferencias y cambios de estado
Estos registros te ayudan a:
  • Monitorear y revisar la actividad de payouts
  • Apoyar auditorías internas y procesos de cumplimiento
  • Investigar incidentes o comportamientos inesperados

​
Resumen de controles

La siguiente tabla asocia cada control con el riesgo que mitiga: En conjunto, estos controles cubren la autenticación, la integridad de las solicitudes, la seguridad ante reintentos y la auditabilidad de los payouts creados a través de la API de Fintoc.