Sandbox Quickstart
Get your first end-to-end Payment Link charge running in Sandbox.
- Middleware Sandbox (
https://sb-mw.migopayments.com) β Payment Links, hosted webview, tokenization, charges. This is what you call to get aURLfor your customer. - Wallet Gateway QA (
https://ali-qa.ali.app/rest) β wallet, cards, users. Different credentials and flow; see Environments & Base URLs.
This page focuses on the Middleware Sandbox because that is where Payment Links live.
The fast pathβ
Four steps to your first charge in Sandbox.
- Get your credentials β a
clientslug and a merchant token. β Credentials checklist - Create the transaction β a
POST /transactionswith the amount anduserId; it returns aURL. β Minimal request - Open the
URLβ it's the hosted webview where your customer pays by card. β Test cards - Receive the result β Migo
POSTs the final status to your backend. β Receiving the result
Base URLs (Middleware)β
| Surface | Sandbox | Production |
|---|---|---|
| API host | https://sb-mw.migopayments.com | https://mw.migopayments.com |
| Hosted webview | https://sandbox.migopayments.com | https://web.migopayments.com |
| OpenAPI reference | /api-reference/migo-api | same β toggle the server in the Scalar UI |
Credentials checklistβ
Before you can call POST /transactions (Payment Links) or POST /api/v1/integrations/transactions (Alternative Payments), you need:
| Item | What it looks like | How to get it |
|---|---|---|
client slug | Short string, e.g. migoDeveloper | Created when Migo onboards your application |
| Merchant token | 64-char hex, e.g. b6a615d8...0ba65c1 | Issued together with the client slug. The same token authenticates both Payment Links and Alternative Payments β only the header format changes per endpoint. |
Header format depends on the endpointβ
| Endpoint | Header value |
|---|---|
POST /transactions (Payment Link) | Authorization: <token> β no Bearer prefix |
POST /api/v1/integrations/transactions[β¦] (Alternative Payments) | Authorization: Bearer <token> β Bearer required |
Known sandbox client slugsβ
| Slug | Country | Rails commonly enabled in Sandbox |
|---|---|---|
migoDeveloper | Guatemala | zigi, akisiQR, bamPaymentButton, quickPayQR, bancoIndustrial, pronet |
Confirm the rails enabled for your slug by reading data.paymentMethods in the response of POST /api/v1/integrations/transactions β that array is the source of truth.
Minimal requestβ
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": []
}'
Expected response:
{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "CLIENT020007SB",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
Field URL is uppercase β see Create a Payment Link β Successful response. Open it in a browser to render the hosted webview.
Minimal request β Alternative Payments (akisiQR)β
For the direct APM flow (render the QR yourself instead of opening the webview), reuse the same merchant token but add the Bearer prefix:
# 1) Create transaction
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) Process akisiQR β uses the uid from step 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,β¦" } }
The data.data value is a complete data:image/png;base64,β¦ URI β drop it into <img src=...>. See Recipes β Guatemala β Akisi QR for the full per-rail walkthrough.
Field cookbookβ
| Field | Sandbox-friendly value | Notes |
|---|---|---|
amount | 1 for the cheapest test, any value inside your client's configured range | Outside the range β code 2003 |
userId | E.164 phone, e.g. +50224865444 (Guatemala) | The Sandbox does not actually deliver SMS / WhatsApp, but the format must be parseable |
channel | wa, sms, email, web, app | Depends on what is enabled per client. Unknown values β code 5000 |
client | Your slug | Wrong slug β code 5004 |
currency | GTQ, USD, MXN, CRC, HNL, DOP, COP, SVC | If omitted, Migo uses your client's first configured currency |
externalId | Any string you control, e.g. WEB-${Date.now()} | Returned in the Merchant Generic Callback payload |
ads | [] | Reserved β always send the empty array if unused |
Test cards inside the webviewβ
Once the customer opens the URL, the hosted webview asks for card data. The test cards that work depend on the card processor configured for your client (for Guatemala this is Cybersource). A few common Cybersource examples:
| PAN | Brand | Behavior |
|---|---|---|
4111111111111111 | Visa | Valid (approves) |
4456530000001096 | Visa | Valid with 3DS challenge |
4000000000000002 | Visa | Declines the transaction |
Use any future expiry, any valid CVV (4 digits for Amex, 3 otherwise). The approval/decline outcome (including 3DS behavior) is driven by the test card you use, not by a request field.
The full, authoritative card list per processor (Cybersource, FAC 2, Visa Epay, PusPayment, β¦) lives in Testing your integration β Test cards. Confirm which processor applies to your client before picking a card.
Receiving the resultβ
The terminal status reaches your backend through the Merchant Generic Callback β a POST from Migo to a URL you registered with support. Standard payload:
{
"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"
}
Authenticate the request with the static header you registered with Migo (no HMAC). Full details in Merchant Generic Callback.
Common Sandbox errorsβ
| HTTP | error.code | Likely cause | Quick fix |
|---|---|---|---|
| 401 | (none) | Wrong environment credentials | The API Gateway authorizer answers { "message": "Unauthorized" } with no Migo envelope and no code. Check that the token and the environment (Sandbox / Production) match. |
| 409 | 5000 | Missing required field, wrong type, or unknown channel | Verify body matches the schema in Create a Payment Link |
| 409 | 5004 | Wrong client slug | Copy the slug as Migo provided it (case-sensitive) |
| 400 | 2003 | amount outside configured range | Try amount: 1; ask Migo for the configured min/max |
Full catalog: Error Catalog β Payment Link / Middleware error codes.
What to copy into your .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
Never commit these.
React quickstart (Payment Link)β
End-to-end recipe to add a "generate payment link" form to a React app. The user types an amount, the app calls Migo, and a button surfaces the resulting URL. Everything below works against the Middleware Sandbox described above.
[ Amount input ] β POST /transactions β { uid, reference, URL }
[ Generate ] β
βΌ
[ Open payment link β URL ]
When to use this recipeβ
- You are building a single-page app and want to issue a Payment Link from a form.
- You can host a small backend in Express.js (or any equivalent: Next.js Route Handlers, your existing API service). Routing the call through your own backend is strongly recommended for this recipe β see the box below.
The main reason is secret hygiene: POST /transactions authenticates with your long-lived merchant token, which must never ship in browser code. A backend keeps that token server-side. Both /transactions endpoints are configured with CORS enabled at the service level, so the endpoint itself does not block browser calls β but if your production deployment sits behind the mw.migopayments.com reverse proxy and that proxy strips CORS headers, a fetch from the browser would also fail the preflight. The Express.js service in step 3 is that backend β it owns the merchant token, validates input, and is where you would later add order persistence, observability, and idempotency.
1. Project layout (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. Environment variablesβ
# .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
The token lives only inside the Express.js backend. The browser only sees /api (your backend's own routes).
3. Mandatory Express.js backendβ
Keep the merchant token out of the browser β call POST /transactions from your own backend. The Express.js service below is your own backend β it owns the merchant token, exposes a domain-flavored route to the browser (POST /api/orders/payment-link), validates the amount, and is the piece in the architecture that talks to Migo. Treat it as a real backend, not a passthrough proxy: this is where order persistence, idempotency, and observability go in a production setup.
// 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'));
Wire vite.config.ts to forward /api/* to http://localhost:8787 during development:
// 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. Types (browser β your backend)β
The browser talks to your Express.js backend, not to Migo. Type the contract accordingly:
// 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. Client wrapperβ
// 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. Form componentβ
// 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β
| Case | Input | Expected |
|---|---|---|
| Happy path | amount = 125.50 | "Open payment link" button appears, opens https://sandbox.migopayments.com/?orderId=... |
| Zero / empty | amount = 0 or empty | Local validation message; no network call |
| Wrong token | revoke / mistype MIGO_MERCHANT_TOKEN in the Express.js env | Migo's API Gateway authorizer rejects the token with a generic 401 { "message": "Unauthorized" } (no business code). Your backend maps the upstream 401 to a user-facing credentials error. |
| Wrong client | mistype MIGO_CLIENT in the Express.js env | Error "Unknown Migo client slug" (code 5004) |
| Out-of-range amount | amount = 99999999 | Error "Amount is outside the configured range" (code 2003) |
When the customer completes the webview, your backend receives a Merchant Generic Callback β wire that into your order system to close the loop.
8. Production hardeningβ
- Never ship
MIGO_MERCHANT_TOKENin browser code. Keep it inside the Express.js process. - Promote the dev-only Express.js service to your real backend (or a serverless function) with secrets loaded from your secret store.
- Switch
MIGO_BASE_URLtohttps://mw.migopayments.comand rotate to production credentials. Sandbox values do not work in production. - Validate
amountinside the Express.js handler β never trust the browser's number. - Persist the order on the way out (
orderId,amount,migoUid,status: 'PENDING') so you can match the eventual Merchant Generic Callback to the order that produced the link. - Add idempotency: the same
orderIdshould not generate a new MigoURLif it already exists.
Going to productionβ
Before going to production, remember that production credentials, base URLs, and webhook receivers are different β none of the Sandbox values above carry over.