Quickstart de Sandbox
Pon en marcha tu primer cobro con link de pago de extremo a extremo en Sandbox.
- Middleware Sandbox (
https://sb-mw.migopayments.com) — links de pago, webview hospedado, tokenización, cobros. Es lo que llamas para obtener unaURLpara tu cliente. - Wallet Gateway QA (
https://ali-qa.ali.app/rest) — billetera, tarjetas, usuarios. Credenciales y flujo distintos; consulta Entornos y URLs base.
Esta página se enfoca en el Middleware Sandbox porque ahí viven los links de pago.
El camino rápido
Cuatro pasos para tu primer cobro en Sandbox.
- Consigue tus credenciales — un slug
clienty un merchant token. → Checklist de credenciales - Crea la transacción — un
POST /transactionscon el monto y eluserId; te devuelve unaURL. → Solicitud mínima - Abre la
URL— es el webview hospedado donde tu cliente paga con tarjeta. → Tarjetas de prueba - Recibe el resultado — Migo hace un
POSTa tu backend con el estado final. → Recibir el resultado
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 (links de pago) 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 links de pago como Pagos Alternativos — solo cambia el formato del header por endpoint. |
El formato del header depende del endpoint
| Endpoint | Valor del header |
|---|---|
POST /transactions (link de pago) | Authorization: <token> — sin prefijo Bearer |
POST /api/v1/integrations/transactions[…] (Pagos Alternativos) | Authorization: Bearer <token> — Bearer requerido |
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 — ver Crear un link de pago → Respuesta exitosa. Á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 → code 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 → code 5000 |
client | Tu slug | Slug equivocado → code 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 | error.code | Causa probable | Solución rápida |
|---|---|---|---|
| 401 | (ninguno) | Credenciales del entorno equivocado | El authorizer del API Gateway responde { "message": "Unauthorized" } sin envelope de Migo ni código. Verifica que el token y el entorno (Sandbox / Producción) coincidan. |
| 409 | 5000 | Falta un campo requerido, tipo equivocado o channel desconocido | Verifica que el cuerpo coincida con el schema en Crear un link de pago |
| 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 → Códigos de error de link de pago / Middleware.
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.
Quickstart de React (link de pago)
Receta de extremo a extremo para agregar un formulario "generar link de pago" a una app de React. El usuario escribe un monto, la app llama a Migo, y un botón muestra la URL resultante. Todo lo que sigue funciona contra el Middleware Sandbox descrito arriba.
[ Amount input ] → POST /transactions → { uid, reference, URL }
[ Generate ] │
▼
[ Open payment link → URL ]
Cuándo usar esta receta
- Estás construyendo una single-page app y quieres emitir un link de pago desde un formulario.
- Puedes hospedar un backend pequeño en Express.js (o cualquier equivalente: Next.js Route Handlers, tu servicio de API existente). Enrutar la llamada a través de tu propio backend es altamente recomendado para esta receta — consulta el recuadro a continuación.
La razón principal es la higiene de secretos: POST /transactions se autentica con tu merchant token de larga vida, que nunca debe viajar en código del navegador. Un backend mantiene ese token del lado servidor. Ambos endpoints de /transactions están configurados con CORS habilitado del lado del servicio, así que el endpoint en sí no bloquea las llamadas del navegador — pero si tu despliegue de producción está detrás del reverse proxy mw.migopayments.com y ese proxy elimina los headers CORS, un fetch desde el navegador también fallaría el preflight. El servicio de Express.js del paso 3 es ese backend — es dueño del merchant token, valida el input, y es donde después agregarías persistencia de órdenes, observabilidad e idempotencia.
1. Estructura del proyecto (Vite + React + TypeScript)
migo-paylink-demo/
├── .env.local # MIGO_BASE_URL, MIGO_CLIENT, MIGO_MERCHANT_TOKEN
├── server/
│ └── proxy.ts # Tiny Express proxy that forwards to Migo
├── src/
│ ├── App.tsx
│ ├── components/
│ │ └── PaymentLinkForm.tsx
│ ├── lib/
│ │ └── migo.ts # createPaymentLink(amount)
│ └── types/
│ └── migo.ts # CreatePaymentLinkRequest, PaymentLinkResponse
└── vite.config.ts
2. Variables de entorno
# .env.local
# --- Express.js backend only (NEVER prefixed with VITE_) ---
MIGO_BASE_URL=https://sb-mw.migopayments.com
MIGO_CLIENT=<your-client-slug>
MIGO_MERCHANT_TOKEN=<your-sandbox-token>
# --- Browser-safe values ---
VITE_API_BASE=/api
El token vive solo dentro del backend de Express.js. El navegador solo ve /api (las rutas propias de tu backend).
3. Backend de Express.js obligatorio
Mantén el merchant token fuera del navegador — llama a POST /transactions desde tu propio backend. El servicio de Express.js a continuación es tu propio backend — es dueño del merchant token, expone una ruta con sabor a dominio al navegador (POST /api/orders/payment-link), valida el monto, y es la pieza de la arquitectura que habla con Migo. Trátalo como un backend real, no un proxy passthrough: aquí es donde van la persistencia de órdenes, la idempotencia y la observabilidad en una configuración de producción.
// server/index.ts — Express.js backend
import express from 'express';
import { randomUUID } from 'node:crypto';
const app = express();
app.use(express.json({ limit: '64kb' }));
const { MIGO_BASE_URL, MIGO_CLIENT, MIGO_MERCHANT_TOKEN } = process.env;
if (!MIGO_BASE_URL || !MIGO_CLIENT || !MIGO_MERCHANT_TOKEN) {
throw new Error('Missing Migo backend env vars');
}
app.post('/api/orders/payment-link', async (req, res) => {
const amount = Number(req.body?.amount);
if (!Number.isFinite(amount) || amount <= 0) {
return res.status(400).json({ message: 'Amount must be > 0', code: 'INVALID_AMOUNT' });
}
const orderId = randomUUID();
const upstream = await fetch(`${MIGO_BASE_URL}/transactions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
// Raw token — no `Bearer` prefix.
Authorization: MIGO_MERCHANT_TOKEN,
},
body: JSON.stringify({
amount,
userId: '+50224865444', // pull from your session in real code
channel: 'web',
client: MIGO_CLIENT,
currency: 'GTQ',
externalId: orderId,
ads: [],
}),
});
const body = await upstream.json().catch(() => ({}));
if (!upstream.ok || !body.URL) {
return res.status(502).json({ message: body.message ?? 'Migo error', code: body.error?.code });
}
// In production: persist { orderId, amount, migoUid: body.uid, status: 'PENDING' }
return res.status(201).json({
orderId,
paymentLink: body.URL, // normalize Migo's uppercase `URL` here
reference: body.reference,
});
});
app.listen(8787, () => console.log('Express backend listening on :8787'));
Configura vite.config.ts para reenviar /api/* a http://localhost:8787 durante el desarrollo:
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
server: {
proxy: { '/api': 'http://localhost:8787' },
},
});
4. Tipos (navegador ↔ tu backend)
El navegador habla con tu backend de Express.js, no con Migo. Tipa el contrato en consecuencia:
// src/types/api.ts
export interface CreatePaymentLinkOrderRequest {
amount: number;
}
export interface PaymentLinkOrderResponse {
orderId: string;
paymentLink: string; // your backend already normalized Migo's uppercase URL
reference: string;
}
export interface ApiErrorResponse {
message: string;
code?: string | number;
}
5. Wrapper del cliente
// src/lib/api.ts
import type {
CreatePaymentLinkOrderRequest,
PaymentLinkOrderResponse,
ApiErrorResponse,
} from '../types/api';
const apiBase = import.meta.env.VITE_API_BASE; // "/api"
export async function createPaymentLinkOrder(amount: number): Promise<PaymentLinkOrderResponse> {
const res = await fetch(`${apiBase}/orders/payment-link`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount } satisfies CreatePaymentLinkOrderRequest),
});
if (!res.ok) {
const err = (await res.json().catch(() => ({}))) as ApiErrorResponse;
throw new Error(humanize(err) ?? `API error ${res.status}`);
}
return (await res.json()) as PaymentLinkOrderResponse;
}
function humanize(err: ApiErrorResponse): string | null {
// Your backend translated Migo error codes into domain codes already.
switch (err.code) {
case 'INVALID_AMOUNT': return 'Enter a positive amount';
case 2003: return 'Amount is outside the configured range';
case 2007: return 'Invalid Migo credentials — check the backend environment';
case 5000: return 'Missing or invalid request field';
case 5004: return 'Unknown Migo client slug';
default: return err.message ?? null;
}
}
6. Componente del formulario
// src/components/PaymentLinkForm.tsx
import { useState, type FormEvent } from 'react';
import { createPaymentLinkOrder } from '../lib/api';
export function PaymentLinkForm() {
const [amount, setAmount] = useState('');
const [link, setLink] = useState<string | null>(null);
const [error, setError] = useState<string | null>(null);
const [loading, setLoading] = useState(false);
async function handleSubmit(e: FormEvent) {
e.preventDefault();
setError(null);
setLink(null);
const numericAmount = Number(amount);
if (!Number.isFinite(numericAmount) || numericAmount <= 0) {
setError('Enter an amount greater than 0');
return;
}
setLoading(true);
try {
const order = await createPaymentLinkOrder(numericAmount);
setLink(order.paymentLink);
} catch (err) {
setError(err instanceof Error ? err.message : 'Unknown error');
} finally {
setLoading(false);
}
}
return (
<section>
<h1>Generate payment link</h1>
<form onSubmit={handleSubmit}>
<label>
Amount
<input
type="number"
step="0.01"
min="0.01"
value={amount}
onChange={(e) => setAmount(e.target.value)}
disabled={loading}
required
/>
</label>
<button type="submit" disabled={loading}>
{loading ? 'Generating…' : 'Generate payment link'}
</button>
</form>
{error && <p role="alert">{error}</p>}
{link && (
<a href={link} target="_blank" rel="noopener noreferrer">
<button type="button">Open payment link</button>
</a>
)}
</section>
);
}
7. Smoke test
| Caso | Input | Esperado |
|---|---|---|
| Camino feliz | amount = 125.50 | Aparece el botón "Open payment link", abre https://sandbox.migopayments.com/?orderId=... |
| Cero / vacío | amount = 0 o vacío | Mensaje de validación local; sin llamada de red |
| Token equivocado | revoca / escribe mal MIGO_MERCHANT_TOKEN en el env de Express.js | El authorizer del API Gateway de Migo rechaza el token con un 401 genérico { "message": "Unauthorized" } (sin código de negocio). Tu backend mapea el 401 upstream a un error de credenciales de cara al usuario. |
| Cliente equivocado | escribe mal MIGO_CLIENT en el env de Express.js | Error "Unknown Migo client slug" (code 5004) |
| Monto fuera de rango | amount = 99999999 | Error "Amount is outside the configured range" (code 2003) |
Cuando el cliente completa el webview, tu backend recibe un Merchant Generic Callback — conéctalo a tu sistema de órdenes para cerrar el ciclo.
8. Endurecimiento para producción
- Nunca envíes
MIGO_MERCHANT_TOKENen código del navegador. Mantenlo dentro del proceso de Express.js. - Promueve el servicio de Express.js solo-de-desarrollo a tu backend real (o una función serverless) con los secretos cargados desde tu secret store.
- Cambia
MIGO_BASE_URLahttps://mw.migopayments.comy rota a credenciales de producción. Los valores de Sandbox no funcionan en producción. - Valida
amountdentro del handler de Express.js — nunca confíes en el número del navegador. - Persiste la orden a la salida (
orderId,amount,migoUid,status: 'PENDING') para poder emparejar el eventual Merchant Generic Callback con la orden que produjo el link. - Agrega idempotencia: el mismo
orderIdno debería generar una nuevaURLde Migo si ya existe.
Salir a producción
Antes de pasar a producción, recuerda que las credenciales de producción, las URLs base y los receptores de webhooks son distintos — ninguno de los valores de Sandbox anteriores se transfiere.