Saltar al contenido principal
Migo Docs

Payment Link vs. Pagos Alternativos — ¿qué flujo debo usar?

Migo expone dos integraciones de backend que se traslapan en alcance pero producen responsabilidades de renderizado distintas y atienden necesidades de UX diferentes. Ambas se autentican con el mismo merchant token de larga vida; la diferencia está en qué tiene que renderizar el comercio y dónde interactúa el cliente con el riel.

Árbol de decisión (empieza aquí)​

  1. ¿Quieres que Migo aloje todo el UI de checkout por ti?

    • Sí → usa Payment Link (POST /transactions). Tú entregas una URL; Migo renderiza el webview completo, incluido el selector de rieles (akisiQR, BAM, Zigi, tarjetas, …). Sin código de frontend de tu lado.
    • No, quiero renderizar los rieles dentro de mi propio UI → usa Pagos Alternativos (POST /api/v1/integrations/transactions[…]). Migo retorna payloads específicos por riel (URL, string de QR, imagen base64, botón push); tu frontend decide cómo mostrarlos.

  2. ¿Tienes un backend que pueda guardar un secreto de 64 caracteres?

    • Sí → cualquiera de los dos flujos es seguro.
    • No (SPA estática, sin servidor) → usa POST /transactions-hook. Acepta credenciales en el cuerpo con un flujo amigable a CORS desde el navegador.

  3. ¿Necesitas el código reference legible (estilo ALI001189SB)?

    • Sí → Payment Link es el único flujo que lo retorna en la respuesta de creación.
    • No → Pagos Alternativos es suficiente; aún puedes correlacionar con customKeys.orderId y el Merchant Generic Callback.

Lado a lado​

AspectoPayment Link (POST /transactions)Pagos Alternativos (POST /api/v1/integrations/transactions[…])
Qué recibesUna URL de webview hospedadoPayloads específicos por riel (url, qr, base64, json, payButton)
Selector de rielesAlojado por MigoTuyo — lee paymentMethods desde la respuesta de creación de la transacción
Formato del headerAuthorization: <token> (se recomienda el token crudo)Authorization: Bearer <token> (recomendado)
CORS en el endpoint de creaciónHabilitado a nivel del servicio (cors: true); aun así se recomienda un backend para mantener el merchant token del lado servidorHabilitado a nivel del servicio (cors: true); aun así se recomienda un backend para mantener el merchant token del lado servidor
¿La respuesta incluye reference?Sí (por ejemplo ALI001189SB)No
Generación de QR para akisiQREl cliente escanea el QR renderizado dentro del webviewRecibes data:image/png;base64,… para renderizar en tu UI
ReembolsosSoportados por flujos por riel detrás de escenaMismo soporte por riel, llamado explícitamente vía /refund y /revert
Fuente de verdad del resultadoMerchant Generic CallbackMerchant Generic Callback

Ambas superficies emiten el mismo webhook final, así que tu pipeline de conciliación es el mismo sin importar cuál creó la transacción.

El formato del header es una convención, no un requisito exclusivo

Payment Link y Pagos Alternativos están protegidos por el mismo authorizer personalizado, que quita un prefijo Bearer inicial antes de validar el token. Los dos formatos anteriores son convenciones recomendadas por familia — el authorizer acepta el merchant token con o sin el prefijo Bearer en ambos. Elige la convención mostrada para la familia que uses y mantente consistente.

¿Puedo combinar ambos?​

Sí — y es un patrón común cuando quieres renderizar un APM en tu UI pero también tener un fallback al webview hospedado para los usuarios que no tengan instalada la app de billetera.

  • Una opción: crear la transacción vía Pagos Alternativos, renderizar el payload del APM inline (por ejemplo, la imagen base64 de akisiQR) y además ofrecer "abrir checkout hospedado" emitiendo una segunda transacción vía Payment Link para el mismo userId/amount.
  • Migo las trata como transacciones independientes (distintos uid y reference). Usa tu propio customKeys.orderId para correlacionarlas.
  • No intentes mezclar los dos endpoints sobre el mismo uid: una transacción tiene un solo carril de cumplimiento.

Si necesitas que el mismo uid alimente tanto un webview hospedado como un APM inline, pide a Operaciones de Migo que habilite ese escenario para tu cuenta de comercio — está soportado, pero es opt-in por cuenta.

Cuando tengas dudas​

  • Integración nueva, controlas un backend, quieres el camino más simple → Payment Link.
  • Estás construyendo un checkout embebido, un UI de comercio con marca propia, o necesitas específicamente el base64 de akisiQR en tu propio componente → Pagos Alternativos.
  • Estás migrando desde una integración legacy apiKey/apiSecret → conserva el login de JWT si tu runtime depende de él; de lo contrario, cámbiate al merchant token para eliminar la complejidad del refresh.

¿Qué sigue?​