Saltar al contenido principal
Migo Docs

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 — cada solicitud envía Authorization: Bearer <token>.

Actores​

ActorResponsabilidad
Backend del comercioCrea la orden, llama a Migo, almacena el id de transacción Migo y espera el estado final.
Frontend del comercioMuestra los rails disponibles del cliente y renderiza la URL, QR, HTML, payload JSON o botón de pago retornado por Migo.
API de MigoCrea la transacción, valida el procesador seleccionado, enruta la solicitud de pago y normaliza la respuesta.
ProcesadorEs dueño de la experiencia de autorización específica del rail y de la aprobación o denegación final.
ClienteConfirma 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 respuestaExperiencia del cliente
urlRedireccionar al cliente a una página de pago hosteada.
base64Inserta el valor data:image/png;base64,… directamente en un <img> para mostrar un QR.
htmlRenderizar o enviar un formulario HTML.
jsonRenderizar una instrucción o referencia estructurada.
payButtonMostrar 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.

Idioma de comprobantes​

Los comprobantes y los recibos por correo se envían en español o inglés, según el idioma que el cliente use en la página de pago (idioma del navegador o selector de idioma). Cambiarlo antes de pagar actualiza el comprobante; un idioma no soportado usa español. No hay un parámetro de API para elegirlo. Más detalle en Webview hospedado.

Verificació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.