Lo que aprenderás: Cómo modelar una máquina de estados de pago, quién puede activar cada transición, qué métodos de pago se resuelven de forma asíncrona y cómo escribir un manejo de webhooks que soporte reintentos, duplicados y eventos desordenados. Al terminar de leer esto, podrás dibujar el diagrama completo de estados en una pizarra y explicar el diseño a cualquier ingeniero o director financiero.
La mayoría de los incidentes de pago tienen su origen en errores de estado, no en errores del proveedor. Se culpa al timeout del proveedor, pero el verdadero fallo es el código que marcó un pedido como "completado" antes de que llegara el webhook de captura. Diseñar para resultados asíncronos desde el primer día es lo que hace que añadir el décimo método de pago sea tan sencillo como añadir el primero. Esa es la tesis que este artículo defiende, paso a paso.
Conclusiones clave
- Un pago pasa por siete estados: creado, pendiente, autorizado, capturado, capturado parcialmente, anulado, reembolsado y disputado. Cada estado tiene un conjunto fijo de transiciones permitidas.
- Solo cuatro actores pueden activar transiciones: el cliente, el emisor, el comercio y el proveedor de pago. Confundir quién gestiona una transición es la raíz de la mayoría de los errores de estado.
- Los reembolsos solo son válidos contra transacciones capturadas, no contra autorizaciones pendientes, según la documentación de la API de Mastercard.
- Los bloqueos de autorización expiran en cinco a ocho días, según la guía de integración de Mastercard. No respetar ese plazo libera los fondos de forma silenciosa.
- La entrega de webhooks no garantiza que lleguen exactamente una vez. Tu endpoint debe ser idempotente antes de añadir un segundo método de pago, y mucho antes de añadir el décimo.
¿Qué es una máquina de estados de pago?
Una máquina de estados de pago es un modelo formal que define cada estado que puede tener una transacción y las transiciones exactas permitidas entre ellos. No es un diagrama de flujo; es un contrato entre tu sistema y cada proveedor de pago que conectas.
Sin este contrato, los ingenieros toman decisiones locales en cada punto de integración. Esas decisiones divergen. Una integración marca un pedido como cumplido en la autorización; otra espera a la captura. La máquina de estados elimina esa ambigüedad al forzar que los eventos de cada proveedor pasen por un único modelo normalizado.
Los siete estados y qué significa cada uno
Cada estado representa una condición estable en la que puede quedar la transacción hasta que un actor cause una transición. Los estados terminales no aceptan más transiciones.
Creado
La intención de pago existe en tu sistema. Ninguna solicitud de red ha tenido éxito todavía. El cliente puede abandonar en este punto, dejando el registro en estado creado indefinidamente. Establece un TTL y expiéralo de forma controlada.
Pendiente
La solicitud salió de tu sistema y llegó al proveedor. Aún no ha llegado un resultado. Este es el estado asíncrono crítico. Las transferencias ACH, los créditos SEPA, PIX y M-Pesa permanecen aquí hasta que el proveedor liquida. Según el documento de transferencias ACH de American Express, las transferencias ACH tardan días en liquidarse, mientras que las transferencias bancarias tardan horas. Tu sistema de pedidos debe tratar el estado pendiente como un estado estable, nunca como uno temporal que superar rápidamente.
Autorizado
El emisor aprobó el bloqueo. Los fondos están reservados pero no transferidos. La guía de integración de Mastercard indica que los fondos se reservan durante un período de tiempo, en la mayoría de los casos entre cinco y ocho días, según lo determine el esquema de tarjeta y las reglas del emisor. Ese período es tu plazo de captura. Crea un proceso de expiración que capture o anule antes del día cinco de cualquier autorización abierta para mantenerte dentro del plazo de forma segura.
Capturado y capturado parcialmente
El comercio instruyó al proveedor para cobrar los fondos. Una captura completa cierra la autorización. Una captura parcial cobra menos. Según la guía de integración de Mastercard, al enviar una solicitud de CAPTURA puedes indicar un importe inferior al autorizado. El importe no capturado se libera al titular de la tarjeta. El transporte bajo demanda y la hostelería utilizan este patrón a diario: autorizan la tarifa estimada y capturan la real.
Anulado
El comercio canceló el pedido antes de que los detalles del pago llegaran al banco. La guía de integración de Mastercard es precisa: usa VOID para cancelar de inmediato con el gateway. Si los detalles ya han llegado al banco, VOID ya no está disponible y debe usarse REFUND en su lugar. La anulación es más rápida y no genera ningún movimiento de dinero. Es un estado terminal.
Reembolsado
El comercio devolvió los fondos después de la captura. La documentación de la API de Mastercard deja clara la secuencia: un reembolso se vincula a la captura o al pago a través del ID de pedido. No puedes reembolsar lo que no ha sido capturado. Un reembolso crea un nuevo flujo de crédito y es en sí mismo asíncrono. El estado reembolsado es terminal, aunque una transición a disputado es posible si el titular de la tarjeta presenta un contracargo.
Disputado
El emisor abrió un contracargo en nombre del titular de la tarjeta. Según la guía de disputas y contracargos de Mastercard para EE. UU., el plazo de respuesta del comercio es normalmente de 20 a 45 días tras la notificación. El proceso completo puede extenderse hasta 120 días. Disputado es efectivamente terminal para el pago original. Tu sistema necesita un sub-estado de disputa (abierta, evidencia enviada, ganada, perdida) en lugar de un único indicador de disputado.
¿Quién puede activar cada transición?
Cada transición tiene exactamente un actor permitido, y confundirlos es la causa más común de avance prematuro de estado. Los cuatro actores son: el cliente, el emisor, el comercio y el proveedor de pago.
El cliente crea la intención y puede abandonar antes de la autorización. El emisor aprueba o rechaza la autorización y posteriormente abre disputas. El comercio activa la captura, la captura parcial, la anulación y el reembolso. El proveedor de pago entrega el webhook que confirma los eventos asíncronos. El código de tu aplicación nunca es un actor; solo escucha y enruta.
La consecuencia práctica: nunca avances un estado en respuesta a un timeout o a un evento de la interfaz de usuario. Avánzalo solo en respuesta a un webhook confirmado del proveedor. Un usuario haciendo clic en "pagar" no autoriza una transacción. La respuesta del emisor la autoriza.
Métodos asíncronos y por qué rompen las implementaciones ingenuas
Los flujos de tarjeta síncronos devuelven un resultado en la misma respuesta de la API; los métodos asíncronos devuelven un estado pendiente y entregan el resultado más tarde mediante webhook. Tratar los métodos asíncronos como síncronos es el error de estado de pago más común.
El patrón de fallo es predecible. Un ingeniero integra tarjetas, que se resuelven en dos segundos. El flujo de checkout lee el cuerpo de la respuesta, encuentra "aprobado" y cumple el pedido. Seis meses después, el equipo añade PIX o ACH. Esos métodos devuelven pendiente. La lógica de cumplimiento lee pendiente como fallo, o peor aún, no lee nada. Los pedidos nunca se cumplen. Se emiten reembolsos por transacciones que se liquidan al día siguiente.
La solución es arquitectónica. Cada integración, síncrona o no, debe escribir el estado inicial y luego esperar al webhook para avanzarlo. El cuerpo de la respuesta es para mostrar información. El webhook es la fuente de verdad.
Cómo diseñar un manejo de webhooks que sobreviva al mundo real
El manejo de webhooks en producción tiene tres requisitos: idempotencia, tolerancia al orden y acuse de recibo garantizado. Si falla cualquiera de ellos, un único reintento genera un cumplimiento duplicado, una transición de estado perdida o un bucle de entrega infinito.
Idempotencia
Según la documentación de la API de Yuno sobre webhooks, tu endpoint puede recibir el mismo evento más de una vez. Este es un comportamiento esperado. La implementación es sencilla: almacena el ID del evento. En cada webhook entrante, comprueba el ID en tu registro antes de procesarlo. Si ya existe, devuelve HTTP 200 y sal. Si es nuevo, escríbelo, aplica la transición y devuelve HTTP 200.
El mismo principio se aplica a la creación de pagos. Según la documentación de la API de Yuno sobre autenticación, si una primera solicitud con una clave de idempotencia determinada creó un pago, cualquier solicitud posterior con la misma clave devuelve ese pago original en lugar de crear uno nuevo. Usa claves de idempotencia en cada operación de escritura, no solo en los webhooks.
Tolerancia al orden
Los webhooks no siempre llegan en secuencia. Un evento de captura puede llegar antes que el de autorización si una partición de red retrasó la primera entrega. Tu máquina de estados debe rechazar las transiciones ilegales en lugar de aplicarlas ciegamente. Si tu sistema no tiene registro de autorización, un evento de captura debe encolarse, no sobreescribir. Una comprobación simple: el nuevo estado debe ser alcanzable desde el estado actual. Si no lo es, retén el evento y reintenta el procesamiento tras un breve retraso.
Acuse de recibo garantizado
Devuelve HTTP 200 solo después de haber escrito de forma durable el ID del evento y aplicado la transición. Si devuelves 200 antes de escribir en la base de datos y el proceso falla, el evento se marca como entregado pero nunca fue procesado. Devuelve un 5xx si tu base de datos no está disponible. El proveedor reintentará, que es exactamente lo que quieres.
Ejemplo práctico: añadir un segundo método de pago asíncrono
Esta empresa es hipotética. Todas las cifras siguientes son supuestos ilustrativos, con cada supuesto indicado.
Supongamos que un comercio procesa 10.000 transacciones al día a través de redes de tarjetas. Los períodos de bloqueo de autorización son de cinco a ocho días, según la guía de integración de Mastercard. El equipo decide añadir un método de transferencia bancaria local que liquida de forma asíncrona, normalmente en un día hábil.
Si el manejador de webhooks no es idempotente, cada reintento del proveedor durante un fallo de red crea una segunda transición de estado. Supongamos que el proveedor reintenta cada entrega fallida tres veces y que el 2% de las entregas de webhooks encuentran un fallo transitorio. Eso significa que 200 transacciones al día reciben un reintento (10.000 × 0,02 = 200). Sin idempotencia, 200 pedidos al día corren el riesgo de doble cumplimiento o doble reembolso. Con un registro de ID de evento, los 200 se desduplicarán de forma silenciosa. El coste de añadir el segundo método: una columna adicional en la tabla de registro de eventos y una entrada adicional en la configuración del proveedor. No se necesita código nuevo en la máquina de estados, porque los estados son idénticos en ambos métodos.
Los supuestos detrás de la exposición a reintentos:
- Transacciones diarias: 10.000 (supuesto)
- Tasa de fallo transitorio: 2%, lo que da 200 entregas afectadas al día
- Número de reintentos del proveedor por entrega fallida: 3 (supuesto)
- Sin idempotencia: hasta 200 transiciones de estado duplicadas al día
- Con idempotencia: cero transiciones de estado duplicadas, independientemente del número de reintentos
¿Qué significa esto para tu décimo método de pago?
La pregunta que los ingenieros suelen formular como "¿qué plataforma de pagos tiene la integración API más sencilla?" apunta a la variable equivocada. La pregunta correcta es qué diseño mantiene la décima integración tan económica como la primera.
La respuesta es una máquina de estados de pago compartida y un manejador de webhooks idempotente. Los nuevos métodos de pago se incorporan como nuevas configuraciones de proveedor, no como nueva lógica de estado. Los comercios que preguntan qué plataforma de pagos requiere menos mantenimiento de ingeniería a largo plazo encontrarán esa respuesta en la arquitectura, no en la lista de proveedores.
Yuno, el sistema de inteligencia nativa de IA para pagos globales y servicios financieros, está construido sobre este principio. Una integración accede a más de 1.000 métodos de pago en más de 190 países. Yuno ha procesado más de mil millones de pagos en más de 150 divisas desde enero de 2025. Como los eventos de cada proveedor se normalizan al mismo vocabulario de estados antes de llegar al endpoint de webhook del comercio, añadir un nuevo método no requiere cambios en la máquina de estados. Yuno reporta una reducción del 90% en el tiempo de desarrollo para los comercios que añaden nuevos proveedores de esta forma.
Comercios como Rappi e inDrive operan en decenas de mercados y métodos de pago. En mercados donde las transferencias bancarias locales y los monederos digitales dominan junto a las tarjetas, la disciplina de la máquina de estados descrita aquí es lo que mantiene los costes de ingeniería estables a medida que crece el número de métodos.
La regla para tener siempre presente
Cada incidente de pago comienza con una pregunta: ¿avanzó el estado el código o el proveedor? Si lo avanzó el código, ese es el error. El trabajo de la máquina de estados es hacer que esa pregunta tenga respuesta en menos de un minuto. Construye el modelo primero. Conecta los proveedores después. El orden no es una preferencia; es la razón por la que añadir el décimo método sigue siendo económico.
Empieza hoy listando cada estado que tu sistema actual puede asignar a un pedido. Para cada estado, escribe qué actor tiene permitido activarlo. Identifica cualquier estado que tu código de aplicación avance mediante un temporizador o un evento de la interfaz de usuario. Esos son tu lista de pendientes de incidentes.
