El cobro es un proceso asíncrono
Para quien cobra una cuota, el flujo parece lineal: comparte un link, la persona paga y el dinero aparece. Del lado del sistema, en cambio, el proveedor puede avisar unos segundos después, volver a avisar si no recibió respuesta o mandar una notificación con menos datos de los que uno esperaba. Es una realidad conocida en pagos, pero se vuelve muy concreta cuando el negocio depende de saber con certeza quién pagó y quién no.
En MiCuota decidí tratar cada cobro como una máquina de estados. La operación nace, se envía, recibe novedades y cambia de estado con un origen y una fecha. El proveedor participa de esa historia, pero no la escribe por completo. La aplicación necesita su propia versión confiable de los hechos.
Idempotencia como control de negocio
El problema de un webhook repetido no es elegante ni académico. Puede ser una suscripción duplicada, una persona cobrada dos veces o un vendedor que pierde confianza en la herramienta. Por eso, procesar una notificación dos veces debe producir exactamente el mismo resultado que procesarla una sola.
Eso exige identificar la notificación, validar si la transición tiene sentido y volver a consultar al proveedor cuando el aviso llega incompleto. El external reference cumple una función humilde pero crucial: permite volver desde una señal parcial a la operación exacta que la originó.
Ledger de eventos para soporte y conciliación
Los logs son indispensables para entender qué hizo un servicio. Pero cuando alguien pregunta por qué un pago no impactó, necesita una respuesta de negocio, no una excursión por cinco paneles de observabilidad. Por eso guardé en un ledger la creación del cobro, el envío del link, cada webhook y cada transición.
La diferencia se siente en el primer incidente. En vez de reconstruir una versión probable de lo ocurrido, se puede leer la timeline de la operación. Y esa misma historia, que hoy sirve para soporte, mañana permite conciliación, recupero y reportes de mora.
Canales
- Backoffice del prestador
- Página de pago
Dominio MiCuota
- Operación de cobro
- Máquina de estados
Integración
- PaymentProviderGateway
- Webhooks validados
Trazabilidad
- payment_events
- Conciliación y soporte
El prestador inicia un cobro en MiCuota. La plataforma registra la operación y delega la ejecución a un proveedor. Los webhooks actualizan el ledger mediante transiciones validadas e idempotentes.
Principio operativo: un pago confiable exige transiciones válidas, procesamiento idempotente y una trazabilidad que permita explicar cada estado sin depender de logs dispersos.