Ciclo de vida del pago

Cada movimiento de dinero en Migo pasa por una máquina de estados. Los valores de estado reales difieren por superficie, así que esta página describe los dos conjuntos de estados reales por separado. Para conciliación, siempre lee el valor de estado concreto devuelto por la API que llamas — nunca asumas que los valores de una superficie aparecen en la otra.

Dos conjuntos de estados distintos — no los mezcles

La superficie del programa de tarjetas (wallet) usa el conjunto CardTransfersStatus (incluyendo liquidated, reversed). La superficie de aceptación de tarjetas usa un conjunto TransactionStatus diferente (incluyendo used, authorized, refunded, expired). Un cobro con tarjeta nunca devolverá liquidated, y una transferencia del programa de tarjetas nunca devolverá used. Confirma contra qué superficie integras antes de escribir lógica de conciliación.

Estados del programa de tarjetas (wallet)

La superficie del programa de tarjetas (wallet) usa el conjunto CardTransfersStatus. Los estados conceptuales de abajo se mapean a sus valores reales como se muestra.

Estado conceptual	Valor real de CardTransfersStatus	Significado	¿Terminal?
initiated	created	Solicitud aceptada, procesamiento iniciado	No
in progress	in_progress	Siendo procesada	No
authorized	approved	Aprobada	No
declined	denied	Rechazada	Sí
settled	liquidated	Fondos movidos — el comercio recibió el pago	No (aún puede revertirse)
reversed	reversed	Revertida después de la liquidación	Sí

nota

created, approved, denied, in_progress, liquidated y reversed son los valores que el flujo del programa de tarjetas (card transfers) realmente asigna. processed, refunded y cancelled están definidos en el conjunto CardTransfersStatus pero el flujo actual no los produce, así que no construyas lógica de conciliación que espere por ellos.

No existen estados pending_3ds, partial_refunded, chargeback, chargeback_won ni chargeback_lost en esta superficie.

Diagrama de estados del programa de tarjetas

Usando los valores reales de CardTransfersStatus. Solo se imponen dos reglas de transición; todo lo demás es permisivo:

• Una transferencia puede pasar a approved solo desde created o approved.
• Una transferencia puede pasar a reversed solo desde liquidated.

                ┌───────────┐
                │  created  │
                └─────┬─────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
     ┌────────┐  ┌───────────┐  ┌──────────┐
     │ denied │  │in_progress│─►│ approved │
     └────────┘  └───────────┘  └────┬─────┘
                                     │ fondos liquidan
                                     ▼
                                ┌────────────┐
                                │ liquidated │──► reversed
                                └────────────┘

Tiempo hasta la liquidación

Una transferencia aprobada típicamente alcanza liquidated el siguiente día hábil; los días no hábiles y los días de alto volumen pueden retrasarla hasta 48 h. El tiempo de liquidación sigue los días hábiles de Guatemala. Confirma el horario exacto de corte diario que aplica a tu cuenta con tu contacto en Migo, y concilia leyendo el valor de estado concreto en lugar de asumir un retraso fijo.

Estados de transacción de aceptación de tarjetas

La superficie de aceptación de tarjetas usa un conjunto TransactionStatus separado. Es más amplio que el del programa de tarjetas y usa diferentes grafías y valores:

created, used, in progress, approved, denied, authorized, reversed, refunded, cancelled, expired, pending, challenge y blocked.

Otra superficie, otros valores

Un cobro con tarjeta en esta superficie nunca devuelve liquidated — ese valor pertenece solo a los estados del programa de tarjetas (wallet) de arriba. Del mismo modo, valores como used, authorized, refunded y expired no aparecen en la superficie del programa de tarjetas. Lee siempre el valor de estado concreto devuelto por el endpoint que llamaste.

Eventos de webhook por transición

precaución

La plataforma no emite un catálogo de eventos de pago por transición. El único nombre de evento relacionado con el ciclo de vida definido en código es transfer.status.updated; la entrega saliente la determina la plantilla de suscripción del propio comercio, y no hay un envoltorio eventType agregado por la plataforma. No existen nombres de evento payment.*, settlement.* ni refund.*. No construyas flujos que dependan de nombres de evento inventados — lee el valor de estado concreto en su lugar.

Hoy no existen estados de chargeback ni eventos de chargeback en la plataforma; no construyas flujos que dependan de ellos.

Un paso vs dos pasos

Las transacciones de un paso autorizan y completan el cobro en una sola llamada (el default para retail).

Las transacciones de dos pasos se detienen en el estado approved, y luego capturan o liberan en una llamada separada. Estos flujos de captura y liberación viven en el Middleware (migo-api), no en el Wallet Gateway:

• Captura: POST {mw base}/capture/{trxUid}
• Liberación (cancelar): POST {mw base}/cancel/{trxUid} (se llama cancel, no void)

Ambos reciben el trxUid de la transacción. Consulta la referencia del Middleware.