Saltar al contenido principal
Migo Docs

Quickstart de Sandbox

Pon en marcha tu primer cobro con link de pago de extremo a extremo en Sandbox.

Dos sandboxes, dos superficies
  • Middleware Sandbox (https://sb-mw.migopayments.com) — links de pago, 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 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.

  1. Consigue tus credenciales — un slug client y un merchant token. → Checklist de credenciales
  2. Crea la transacción — un POST /transactions con el monto y el userId; te devuelve una URL. → Solicitud mínima
  3. Abre la URL — es el webview hospedado donde tu cliente paga con tarjeta. → Tarjetas de prueba
  4. Recibe el resultado — Migo hace un POST a tu backend con el estado final. → Recibir el resultado

URLs base (Middleware)​

SuperficieSandboxProducción
Host de la APIhttps://sb-mw.migopayments.comhttps://mw.migopayments.com
Webview hospedadohttps://sandbox.migopayments.comhttps://web.migopayments.com
Referencia OpenAPI/api-reference/migo-apila 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:

ElementoA qué se pareceCómo conseguirlo
Slug clientString corto, por ejemplo migoDeveloperSe crea cuando Migo da de alta tu aplicación
Merchant token64 caracteres hexadecimales, por ejemplo b6a615d8...0ba65c1Se 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​

EndpointValor 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​

SlugPaísRieles comúnmente habilitados en Sandbox
migoDeveloperGuatemalazigi, 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​

CampoValor amigable para SandboxNotas
amount1 para la prueba más económica, o cualquier valor dentro del rango configurado de tu clienteFuera del rango → code 2003
userIdTeléfono E.164, por ejemplo +50224865444 (Guatemala)El Sandbox no entrega realmente SMS / WhatsApp, pero el formato debe ser parseable
channelwa, sms, email, web, appDepende de lo que esté habilitado por cliente. Valores desconocidos → code 5000
clientTu slugSlug equivocado → code 5004
currencyGTQ, USD, MXN, CRC, HNL, DOP, COP, SVCSi se omite, Migo usa la primera moneda configurada de tu cliente
externalIdCualquier 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:

PANMarcaComportamiento
4111111111111111VisaVálida (aprueba)
4456530000001096VisaVálida con reto 3DS
4000000000000002VisaDeclina 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​

HTTPerror.codeCausa probableSolución rápida
401(ninguno)Credenciales del entorno equivocadoEl 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.
4095000Falta un campo requerido, tipo equivocado o channel desconocidoVerifica que el cuerpo coincida con el schema en Crear un link de pago
4095004Slug client equivocadoCopia el slug tal como Migo lo proporcionó (distingue mayúsculas/minúsculas)
4002003amount fuera del rango configuradoPrueba 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.

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.
Por qué se recomienda tu propio backend

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​

CasoInputEsperado
Camino felizamount = 125.50Aparece el botón "Open payment link", abre https://sandbox.migopayments.com/?orderId=...
Cero / vacíoamount = 0 o vacíoMensaje de validación local; sin llamada de red
Token equivocadorevoca / escribe mal MIGO_MERCHANT_TOKEN en el env de Express.jsEl 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 equivocadoescribe mal MIGO_CLIENT en el env de Express.jsError "Unknown Migo client slug" (code 5004)
Monto fuera de rangoamount = 99999999Error "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_TOKEN en 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_URL a https://mw.migopayments.com y rota a credenciales de producción. Los valores de Sandbox no funcionan en producción.
  • Valida amount dentro 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 orderId no debería generar una nueva URL de 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.