Cheat Sheet de Sandbox

Todo lo que necesitas para realizar tu primera transacción de Payment Link de extremo a extremo en Sandbox, en una sola página. Guárdala en favoritos cuando inicies una integración.

Dos sandboxes, dos superficies

Middleware Sandbox (https://sb-mw.migopayments.com) — Payment Links, webview hospedado, tokenización, cobros. Es lo que llamas para obtener una URL para tu cliente.
Wallet Gateway QA (https://ali-qa.ali.app/rest) — billetera, tarjetas, usuarios. Credenciales y flujo distintos; consulta Inicio rápido y Entornos.

Esta página se enfoca en el Middleware Sandbox porque ahí viven los Payment Links.

URLs base (Middleware)

Superficie	Sandbox	Producción
Host de la API	`https://sb-mw.migopayments.com`	`https://mw.migopayments.com`
Webview hospedado	`https://sandbox.migopayments.com`	`https://web.migopayments.com`
Referencia OpenAPI	`/api-reference/migo-api`	la misma — cambia el servidor en la UI de Scalar

Checklist de credenciales

Antes de poder llamar a POST /transactions (Payment Links) o POST /api/v1/integrations/transactions (Pagos Alternativos), necesitas:

Elemento	A qué se parece	Cómo conseguirlo
Slug `client`	String corto, por ejemplo `migoDeveloper`	Se crea cuando Migo da de alta tu aplicación
Merchant token	64 caracteres hexadecimales, por ejemplo `b6a615d8...0ba65c1`	Se entrega junto con el slug del cliente. El mismo token autentica tanto Payment Links como Pagos Alternativos — solo cambia el formato del header por endpoint.
(Alternativa) `privateKey` + `publicKey`	Par con forma de UUID	Se entrega para integraciones browser-side con `/transactions-hook`

El formato del header depende del endpoint

Endpoint	Valor del header
`POST /transactions` (Payment Link)	`Authorization: <token>` — sin prefijo `Bearer`
`POST /api/v1/integrations/transactions[…]` (Pagos Alternativos)	`Authorization: Bearer <token>` — Bearer requerido

Consulta Autenticación → Formato de header por endpoint para la matriz canónica.

Slugs de cliente conocidos en Sandbox

Slug	País	Rieles comúnmente habilitados en Sandbox
`migoDeveloper`	Guatemala	`zigi`, `akisiQR`, `bamPaymentButton`, `quickPayQR`, `bancoIndustrial`, `pronet`

Confirma los rieles habilitados para tu slug leyendo data.paymentMethods en la respuesta de POST /api/v1/integrations/transactions — ese array es la fuente de verdad.

Solicitud mínima

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

Respuesta esperada:

{
  "uid": "Ypo5z2zTpLqWoe3eVvZMH",
  "reference": "CLIENT020007SB",
  "URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}

El campo URL está en mayúsculas. Ábrelo en un navegador para renderizar el webview hospedado.

Solicitud mínima — Pagos Alternativos (akisiQR)

Para el flujo APM directo (renderizar el QR tú mismo en lugar de abrir el webview), reutiliza el mismo merchant token pero agrega el prefijo Bearer :

# 1) Crear transacción
curl -X POST 'https://sb-mw.migopayments.com/api/v1/integrations/transactions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-sandbox-merchant-token>' \
  -d '{
    "amount": 50,
    "channel": "web",
    "client": "migoDeveloper",
    "userId": "+50224865444",
    "customKeys": { "orderId": "demo-1" }
  }'
# → 201 { "data": { "uid": "...", "paymentMethods": ["akisiQR","zigi","quickPayQR","pronet"], "expireAt": 11999 } }

# 2) Procesar akisiQR — usa el uid del paso 1
curl -X POST 'https://sb-mw.migopayments.com/api/v1/integrations/transactions/<uid>/payments' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-sandbox-merchant-token>' \
  -d '{ "processor": "akisiQR", "data": {} }'
# → 200 { "data": { "type": "base64", "data": "data:image/png;base64,…" } }

El valor data.data es un URI completo data:image/png;base64,… — colócalo en <img src=...>. Consulta Recetas → Guatemala → Akisi QR para el recorrido completo por riel.

Recetario de campos

Campo	Valor amigable para Sandbox	Notas
`amount`	`1` para la prueba más económica, o cualquier valor dentro del rango configurado de tu cliente	Fuera del rango → `ownCode 2003`
`userId`	Teléfono E.164, por ejemplo `+50224865444` (Guatemala)	El Sandbox no entrega realmente SMS / WhatsApp, pero el formato debe ser parseable
`channel`	`wa`, `sms`, `email`, `web`, `app`	Depende de lo que esté habilitado por cliente. Valores desconocidos → `ownCode 5000`
`client`	Tu slug	Slug equivocado → `ownCode 5004`
`currency`	`GTQ`, `USD`, `MXN`, `CRC`, `HNL`, `DOP`, `COP`, `SVC`	Si se omite, Migo usa la primera moneda configurada de tu cliente
`externalId`	Cualquier string que controles, por ejemplo `WEB-${Date.now()}`	Se devuelve en el payload del Merchant Generic Callback
`ads`	`[]`	Reservado — siempre envía el array vacío si no se usa

Tarjetas de prueba dentro del webview

Una vez que el cliente abre la URL, el webview hospedado le solicita los datos de la tarjeta. Las tarjetas de prueba que funcionan dependen del procesador de tarjeta configurado para tu cliente (para Guatemala es Cybersource). Algunos ejemplos comunes de Cybersource:

PAN	Marca	Comportamiento
`4111111111111111`	Visa	Válida (aprueba)
`4456530000001096`	Visa	Válida con reto 3DS
`4000000000000002`	Visa	Declina la transacción

Usa cualquier vencimiento futuro y cualquier CVV válido (4 dígitos para Amex, 3 en los demás casos). El resultado de aprobación/rechazo (incluido el comportamiento de 3DS) lo determina la tarjeta de prueba que uses, no un campo de la solicitud.

La lista completa y autoritativa de tarjetas por procesador (Cybersource, FAC 2, Visa Epay, PusPayment, …) vive en Prueba tu integración → Tarjetas de prueba. Confirma qué procesador aplica a tu cliente antes de elegir una tarjeta.

Recibir el resultado

El estado terminal llega a tu backend mediante el Merchant Generic Callback — un POST desde Migo a una URL que registraste con soporte. Payload estándar:

{
  "reference": "CLIENT020007SB",
  "uid": "Ypo5z2zTpLqWoe3eVvZMH",
  "country": "GT",
  "currency": "GTQ",
  "channel": "WhatsApp",
  "status": "approved",
  "amount": 1,
  "externalId": "ext_auth_123",
  "createdAt": "06/05/2026 09:31:00",
  "transactionId": "txn_1029384756",
  "paymentMethodType": "credit_card"
}

Autentica la solicitud con el header estático que registraste con Migo (sin HMAC). Detalles completos en Merchant Generic Callback.

Errores comunes en Sandbox

HTTP	`ownCode`	Causa probable	Solución rápida
401	`2007`	Token enviado con prefijo `Bearer`, o credenciales del entorno equivocado	Envía el token crudo; verifica Sandbox vs. Producción
409	`5000`	Falta un campo requerido, tipo equivocado o `channel` desconocido	Verifica que el cuerpo coincida con el schema en Crear un Payment Link
409	`5004`	Slug `client` equivocado	Copia el slug tal como Migo lo proporcionó (distingue mayúsculas/minúsculas)
400	`2003`	`amount` fuera del rango configurado	Prueba con `amount: 1`; solicita a Migo el `min`/`max` configurado

Catálogo completo: Catálogo de errores → Payment Link / Middleware ownCodes.

Qué copiar a tu `.env`

MIGO_BASE_URL=https://sb-mw.migopayments.com
MIGO_CLIENT=<your-client-slug>
MIGO_MERCHANT_TOKEN=<your-sandbox-merchant-token>
MIGO_DEFAULT_CHANNEL=web
MIGO_DEFAULT_CURRENCY=GTQ

Nunca los subas al control de versiones. Para integraciones en el navegador usa el flujo alternativo de par de llaves descrito en Crear un Payment Link → endpoint alternativo, y restringe las llaves al rango de monto más pequeño que puedas.

Salir a producción

Cuando Sandbox esté en verde, recorre la Lista de verificación para salir a producción. Las credenciales de producción, las URLs base y los receptores de webhooks son distintos — ninguno de los valores de Sandbox anteriores se transfiere.

URLs base (Middleware)​

Checklist de credenciales​

El formato del header depende del endpoint​

Slugs de cliente conocidos en Sandbox​

Solicitud mínima​

Solicitud mínima — Pagos Alternativos (akisiQR)​

Recetario de campos​

Tarjetas de prueba dentro del webview​

Recibir el resultado​

Errores comunes en Sandbox​

Qué copiar a tu .env​

Salir a producción​