Saltar al contenido principal
Migo Docs

Crear un link de pago

Un link de pago es una URL de webview hospedado que permite a un comercio Migo cobrar un pago a un cliente final sin escribir código de pagos en el front-end. Tu backend crea el link llamando a Migo, y tú entregas la URL resultante al cliente a través de cualquier canal que operes (WhatsApp, SMS, email, mensaje in-app, código QR, etc.).

Tu única llamada a la API es crear la transacción. Después, el cliente completa todo el pago dentro del webview hospedado de Migo — ingresando la tarjeta, eligiendo cuotas, pasando 3D Secure — y Migo reporta el resultado de vuelta a tu backend mediante un webhook. Nunca recolectas datos de tarjeta ni llamas tú mismo a un endpoint de "cobro".

¿Tienes certificación PCI?

Si cuentas con certificación PCI DSS y quieres controlar el checkout, puedes gestionar el flujo de pago por API (capturar la tarjeta y cobrar tú mismo) en lugar del webview hospedado — ver Flujo de pago por API (requiere PCI). Sin certificación PCI, usa el webview hospedado.

Tarjetas de prueba

Para probar en Sandbox sin cobros reales, usa las tarjetas de prueba de Migo.

Tu backend crea el link con POST /transactions, Migo responde { uid, reference, URL }, tú entregas la URL al cliente, el cliente paga dentro del webview hospedado y Migo alcanza un estado terminal, que llega a tu backend por webhook. Los pasos de creación y recepción son tuyos; el pago dentro del webview ocurre íntegramente dentro de Migo. El recorrido paso a paso está en Inicio rápido de links de pago.

Esta página detalla la creación del link; el resultado del pago se entrega después a tu backend mediante el Merchant Generic Callback.

POST /transactions​

Este es el endpoint recomendado para integraciones backend-a-backend.

Endpoint​

POST https://sb-mw.migopayments.com/transactions (Sandbox)
POST https://mw.migopayments.com/transactions (Producción)

Content type: application/json. Envía el merchant token que Migo emitió para tu aplicación como el valor del header Authorization. Se recomienda el token crudo (sin prefijo de esquema); un Bearer inicial se tolera y se elimina:

Authorization: b6a615d8...0ba65c1 recomendado (token crudo)
Authorization: Bearer b6a615d8... aceptado (el prefijo "Bearer " se elimina)

Cuerpo de la solicitud​

CampoTipoRequeridoDescripción
amountintegersíSubtotal de la transacción en la unidad mínima de la moneda permitida por tu configuración de cliente. Debe estar dentro del rango min/max configurado para tu cliente.
userIdstringsíIdentificador del cliente final en tu dominio (número de teléfono, email o tu id interno).
channelstringsíCanal de comunicación por el que pretendes entregar el link de pago al cliente final (por ejemplo wa, app, sms, email, web).
clientstringsíSlug de tu cliente como está registrado en la configuración de Migo.
adsarraynoArray reservado, envía [] si no se usa.

POST /transactions también acepta estos campos opcionales: currency, externalId, customKeys, processorAmount, customerId, subscriptionData y createdBy. Por lo tanto, los ejemplos de cURL y SDK que envían currency/externalId también son válidos contra este endpoint.

Valores permitidos para channel, userId, currency​

Estos tres campos se validan contra tu configuración de cliente. Los valores que puedes usar dependen de lo que esté habilitado para tu slug client específico:

CampoValores comunesCómo descubrir lo que acepta tu cliente
channelwa (WhatsApp), sms, email, web, appLos canales se controlan por cliente. Si tu llamada retorna el código de error 5000 para channel, el valor no está habilitado — pide a tu contacto de Migo que lo habilite.
userIdTeléfono E.164 (+50224865444), email o tu id internoEl formato es libre: Migo lo guarda tal cual. Elige el formato que puedas correlacionar con tus propios registros de usuario y mantente consistente. Para la entrega por SMS / WhatsApp, el campo debe ser un teléfono al que Migo pueda enviar.
currencyISO 4217 (GTQ, USD, MXN, CRC, HNL, DOP, COP, SVC)Si se omite, Migo usa la primera moneda configurada para tu cliente. Si el valor no está en la lista configurada, se coerciona silenciosamente al valor por defecto — pásalo explícitamente cuando necesites estar seguro.

Hoy no existe un endpoint público de "client config", por lo que los canales, monedas y procesadores habilitados no son auto-descubribles. Coordina con tu contacto de Migo para confirmar lo que acepta tu slug client, y trata una respuesta con código de error 5000/5004 como señal de que un valor no está habilitado.

Ejemplo cURL (Sandbox)​

Reemplaza el token y el slug del cliente de marcador de posición con los valores que se te emitieron para Sandbox.

curl --location 'https://sb-mw.migopayments.com/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: <your-sandbox-token>' \
--data '{
"amount": 1,
"userId": "50224865444",
"channel": "wa",
"client": "<your-client-slug>",
"ads": []
}'

Respuesta exitosa​

{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "CAMPGT020007SB",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
CampoDescripción
uidIdentificador único de la transacción en Migo. Úsalo para correlacionar la transacción con el Merchant Generic Callback y con cualquier consulta a soporte.
referenceReferencia legible que Migo deriva de tu configuración de cliente. Aparece en payloads de webhook, dashboards y operaciones de reembolso.
URLURL del webview hospedado que entregas al cliente final. El nombre del campo está en mayúsculas (URL, no url), exactamente como lo emite el handler — preserva ese casing al parsear la respuesta.
Error común — desestructurar URL

Los snippets de TypeScript / JavaScript que usan const { url } = response obtendrán undefined silenciosamente. Siempre desestructura como const { URL: paymentLink } = response o lee el campo con notación de corchetes response.URL.

Qué hace el cliente a continuación​

Una vez que entregas la URL, todo lo demás ocurre dentro del webview hospedado de Migo — no hay ninguna otra llamada a la API que debas hacer. Consulta Webview hospedado para ver cómo se comporta el checkout, y el Inicio rápido de links de pago para lo que hace el cliente paso a paso.

Recibir el resultado​

Migo notifica a tu backend una vez que la transacción alcanza un estado terminal (approved, denied, refunded, reversed). El producto link de pago entrega esto mediante el Merchant Generic Callback — un POST saliente de Migo hacia una URL que registras con soporte, que lleva { uid, reference, status, amount, currency, ... }.

MecanismoDirecciónCuándo
Merchant Generic CallbackMigo → tu backendLa transacción alcanza un estado terminal

Usa el uid que recibiste al crear la transacción para correlacionar el callback con ella. El callback no se firma con HMAC — la autenticidad se delega a una API key/header estático que registras con Migo. Consulta Merchant Generic Callback → Autenticando la solicitud.

Si además de recibir el callback necesitas consultar la transacción (soporte, conciliación), GET /transactions?uid= devuelve el registro completo, incluido paymentInfo — el resumen normalizado del pago (marca de tarjeta, últimos 4 dígitos, resultado 3D Secure, eventos de autorización/captura). Ver Detalles de pago normalizados (paymentInfo).

Errores​

POST /transactions retorna un envelope de error de Migo. El campo más accionable es error.code (no error.ownCode — ese campo no existe en la respuesta real), que mapea a una entrada del catálogo de errores de Migo.

Dos espacios de códigos de error

Los errores de link de pago usan el espacio de code del Middleware (enteros bajos como 2002, 2007, 5000, 5004, anidados en error.code). Son distintos de los códigos de error del Gateway (7000–8099) documentados en el Catálogo de errores. La lista completa de errores de link de pago está reflejada al final de esa página para que puedas mapear cada código en un solo lugar.

HTTPcodeCausaQué hacer
4095000Faltan campos requeridos o el cuerpo es inválidoVerifica que amount, userId, channel, client estén presentes con los tipos correctos.
401(ninguno)Token inválido en POST /transactionsEl token lo valida el authorizer personalizado del API Gateway, no el handler. En caso de fallo, el gateway retorna un 401 genérico con cuerpo { "message": "Unauthorized" } — no hay un envelope de error de Migo ni un code. Verifica que el merchant token y el entorno Sandbox/Producción coincidan.
4095004Slug client no encontrado en la configuración de MigoConfirma el slug; crea o activa la configuración de cliente en coordinación con Migo.
4092003amount fuera del rango min/max configurado para tu cuenta de comercio, o algún valor en processorAmount excede amountAjusta el monto, o actualiza los overrides por procesador para que cada uno sea <= amount.
4002006El cliente final está excluido para este comercioLos usuarios excluidos no pueden transaccionar para este comercio.
4002004El cliente final está bloqueado para este comercioLos usuarios bloqueados no pueden transaccionar para este comercio.
4002005El cliente final está suspendido para este comercioLos usuarios suspendidos no pueden transaccionar mientras la suspensión esté activa.
4002002Error genérico de creaciónReintenta; si el error persiste, contacta a soporte de Migo con el uid (cuando esté disponible) y el payload de la solicitud.

Siguientes pasos​

  1. Entrega la URL al cliente final a través del canal que elijas.
  2. Implementa el Merchant Generic Callback para que tu backend reciba el resultado de la transacción (approved / denied / refunded / reversed) una vez que el cliente complete el webview.
  3. Para una integración en el navegador lista para copiar y pegar, sigue la receta de link de pago en React. Para una lista de verificación de cada valor que necesitas en Sandbox, consulta el Quickstart de Sandbox.
  4. Para el resto del ciclo de vida del pago (reembolsos, capturas, comportamiento específico del procesador, 3DS), explora la referencia del Migo Middleware API y las secciones adicionales de este portal.