Skip to main content
Migo Docs

Sandbox Quickstart

Get your first end-to-end Payment Link charge running in Sandbox.

Two sandboxes, two surfaces
  • Middleware Sandbox (https://sb-mw.migopayments.com) β€” Payment Links, hosted webview, tokenization, charges. This is what you call to get a URL for 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.

  1. Get your credentials β€” a client slug and a merchant token. β†’ Credentials checklist
  2. Create the transaction β€” a POST /transactions with the amount and userId; it returns a URL. β†’ Minimal request
  3. Open the URL β€” it's the hosted webview where your customer pays by card. β†’ Test cards
  4. Receive the result β€” Migo POSTs the final status to your backend. β†’ Receiving the result

Base URLs (Middleware)​

SurfaceSandboxProduction
API hosthttps://sb-mw.migopayments.comhttps://mw.migopayments.com
Hosted webviewhttps://sandbox.migopayments.comhttps://web.migopayments.com
OpenAPI reference/api-reference/migo-apisame β€” 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:

ItemWhat it looks likeHow to get it
client slugShort string, e.g. migoDeveloperCreated when Migo onboards your application
Merchant token64-char hex, e.g. b6a615d8...0ba65c1Issued 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​

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

SlugCountryRails commonly enabled in Sandbox
migoDeveloperGuatemalazigi, 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​

FieldSandbox-friendly valueNotes
amount1 for the cheapest test, any value inside your client's configured rangeOutside the range β†’ code 2003
userIdE.164 phone, e.g. +50224865444 (Guatemala)The Sandbox does not actually deliver SMS / WhatsApp, but the format must be parseable
channelwa, sms, email, web, appDepends on what is enabled per client. Unknown values β†’ code 5000
clientYour slugWrong slug β†’ code 5004
currencyGTQ, USD, MXN, CRC, HNL, DOP, COP, SVCIf omitted, Migo uses your client's first configured currency
externalIdAny 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:

PANBrandBehavior
4111111111111111VisaValid (approves)
4456530000001096VisaValid with 3DS challenge
4000000000000002VisaDeclines 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​

HTTPerror.codeLikely causeQuick fix
401(none)Wrong environment credentialsThe API Gateway authorizer answers { "message": "Unauthorized" } with no Migo envelope and no code. Check that the token and the environment (Sandbox / Production) match.
4095000Missing required field, wrong type, or unknown channelVerify body matches the schema in Create a Payment Link
4095004Wrong client slugCopy the slug as Migo provided it (case-sensitive)
4002003amount outside configured rangeTry 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.

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.
Why your own backend is recommended

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​

CaseInputExpected
Happy pathamount = 125.50"Open payment link" button appears, opens https://sandbox.migopayments.com/?orderId=...
Zero / emptyamount = 0 or emptyLocal validation message; no network call
Wrong tokenrevoke / mistype MIGO_MERCHANT_TOKEN in the Express.js envMigo'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 clientmistype MIGO_CLIENT in the Express.js envError "Unknown Migo client slug" (code 5004)
Out-of-range amountamount = 99999999Error "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_TOKEN in 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_URL to https://mw.migopayments.com and rotate to production credentials. Sandbox values do not work in production.
  • Validate amount inside 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 orderId should not generate a new Migo URL if 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.