Cómo funcionan los pagos alternativos

Los pagos alternativos están construidos alrededor de un checkout asíncrono. El comercio inicia la transacción, el cliente completa el pago en un rail externo, y Migo recibe el resultado del procesador antes de que el comercio considere la orden como pagada.

Esta página explica el flujo a nivel de producto. Para esquemas y payloads exactos, usa la referencia de la API de Migo. La autenticación es la misma en todas las llamadas — ve Autenticación.

Actores

Actor	Responsabilidad
Backend del comercio	Crea la orden, llama a Migo, almacena el id de transacción Migo y espera el estado final.
Frontend del comercio	Muestra los rails disponibles del cliente y renderiza la URL, QR, HTML, payload JSON o botón de pago retornado por Migo.
API de Migo	Crea la transacción, valida el procesador seleccionado, enruta la solicitud de pago y normaliza la respuesta.
Procesador	Es dueño de la experiencia de autorización específica del rail y de la aprobación o denegación final.
Cliente	Confirma el pago en la app externa, billetera, página del banco, flujo QR o red de efectivo.

Ciclo de vida de extremo a extremo

Orden del comercio
   │
   ▼
Crear transacción Migo
   │
   ▼
Mostrar métodos de pago habilitados
   │
   ▼
El cliente selecciona un rail
   │
   ├─► Opcional: obtener metadatos del payment intent
   │
   ▼
Procesar pago
   │
   ▼
Renderizar instrucción del rail
   │
   ▼
El cliente completa el pago
   │
   ▼
El procesador confirma el estado final
   │
   ▼
El comercio cumple o libera la orden

Paso 1 — Crear la transacción

El backend del comercio crea la transacción de pago alternativo con el monto, canal, cliente, identificador del cliente final y metadatos opcionales. Migo valida la configuración del comercio y retorna:

• un id de transacción Migo;
• los métodos de pago alternativos habilitados para ese cliente del comercio;
• la ventana de expiración de la transacción.

Ve a Crear transacción para los detalles de la petición.

Paso 2 — Deja que el cliente elija un rail

El frontend del comercio debería renderizar solo los métodos retornados por Migo. Esa lista ya viene filtrada por la configuración del cliente del comercio y el catálogo global de procesadores de pago alternativo.

Por ejemplo, un comercio de Guatemala puede recibir rails de QR (akisiQR, bancoIndustrial, quickPayQR) mientras que otro recibe opciones de billetera o de botón hosteado (zigi, pronet, bamPaymentButton). El frontend no debe hardcodear la disponibilidad.

Ve a Métodos de pago disponibles para ver los rieles disponibles para el país seleccionado.

Paso 3 — Obtén metadatos del payment intent cuando sea necesario

Algunos rails necesitan un paso previo antes de que el pago pueda iniciar. En Guatemala, la mayoría de los rails (zigi, akisiQR, bancoIndustrial, quickPayQR, pronet, bamPaymentButton) no lo requieren; el método de sandbox fri puede retornar un fixture que usas para simular una autorización.

Usa payment intents solo para procesadores que necesitan esos metadatos. Los rails que retornan un redirect estático, QR o referencia de efectivo usualmente pueden ir directo al procesamiento del pago.

Ve a Payment intents para procesadores soportados y ejemplos de respuesta.

Paso 4 — Procesar el pago seleccionado

El backend del comercio llama al endpoint de pago con el procesador seleccionado y los datos específicos del rail. Migo retorna una respuesta normalizada que le indica al frontend del comercio qué renderizar:

Tipo de respuesta	Experiencia del cliente
url	Redireccionar al cliente a una página de pago hosteada.
base64	Inserta el valor data:image/png;base64,… directamente en un <img> para mostrar un QR.
html	Renderizar o enviar un formulario HTML.
json	Renderizar una instrucción o referencia estructurada.
payButton	Mostrar una acción de push payment estilo billetera.

Consulta el mapeo autoritativo por rail y la advertencia del campo data.data en Procesar pago — Forma de respuesta por data.type.

Ve a Procesar pago para ejemplos específicos por procesador.

Paso 5 — Esperar la confirmación final

La mayoría de los pagos alternativos no son finales en el momento en que el cliente ve la instrucción. El comercio puede mantener la UI responsiva con polling corto, pero el resultado autoritativo debe venir de la confirmación final del procesador manejada por Migo.

Cumple la orden solo después de que la transacción alcance un estado final exitoso. Si el cliente se va, el rail expira o la orden se cancela, libera el checkout con Descartar transacción.

Checklist de integración

• Almacena el id de transacción Migo junto con la orden del comercio.
• Renderiza solo los métodos de pago retornados por la respuesta de creación de la transacción.
• Usa payment intents solo cuando el procesador elegido requiera metadatos.
• Trata redirects, códigos QR, referencias de efectivo y wallet pushes como flujos asíncronos.
• Cumple la orden tras la confirmación final, no tras renderizar la instrucción de pago.
• Descarta transacciones abandonadas o expiradas cuando la orden del comercio ya no se pueda pagar.