Buenas prácticas
Recomendaciones de producción para operar integraciones de Banking.
Esta página reúne las prácticas operativas que separan una integración de Banking que funciona en sandbox de una que sobrevive en producción. Son la forma de evitar transferencias duplicadas, recuperarte cuando un rail tiene timeout, y conciliar los libros al final de cada día.
Si estás desplegando Banking para mover dinero real, trata esta página como un checklist de lanzamiento y como referencia durante incidentes.
Esta página es un esqueleto de buenas prácticas. La versión completa incluirá ejemplos concretos, antipatrones a evitar y runbooks para los modos de falla más comunes en producción.
Idempotencia en cada transferencia
Cada solicitud de creación de transferencia debe incluir una clave de idempotencia. Sin ella, un timeout de red duplicará silenciosamente el envío.
Trata las respuestas síncronas como "aceptadas", no como "settled"
Un 200 al crear una transferencia bancaria significa que Mono aceptó la solicitud — no que el rail confirmó el crédito. Espera el webhook antes de marcar la operación como settled en tus libros.
Planifica los fallbacks
Mono Turbo puede caer a ACH automáticamente. Tu conciliación debe manejar una transferencia solicitada como Mono Turbo que terminó settled como ACH — las tarifas y los tiempos a nivel de rail difieren. Lee el campo del rail en el webhook de confirmación.
Concilia diariamente
Corre una conciliación diaria que compare tu vista de cada transferencia (y su estado terminal) contra la de Mono. Saca a la luz cualquier discrepancia el mismo día que aparezca, no a la semana siguiente.
Verifica las firmas de los webhooks
Cada webhook de Banking viene firmado. Verifica la firma antes de confiar en el payload — revisa la documentación de webhooks.
Rota las API keys
Rota las API keys al menos cada 90 días e inmediatamente después de cualquier exposición sospechada. Las claves no expiran por sí solas.
Antipatrones a evitar
- Enviar una clave de idempotencia nueva en cada reintento.
- Tratar la creación de un enlace de recaudo PSE como confirmación de que el cliente pagó.
- Hardcodear elecciones de rail que bloquean el fallback.
- Loguear API keys, payloads firmados o PII.