Process alternative payment
Initiate the alternative payment flow with a specific processor selected from the list returned at creation time. The response shape depends on the processor — Migo normalizes it through a data.type discriminator so the merchant frontend can render the right UI.
POST https://mw.migopayments.com/api/v1/integrations/transactions/{transactionId}/payments
See the live spec entry: POST /api/v1/integrations/transactions/{transactionId}/payments.
Auth recap. Every call sends
Authorization: Bearer <token>.
Request — one body for every method
The body is identical for every processor: a processor plus a data object. Map all possible data fields once and leave the ones that don't apply to the chosen method as null or empty — the Migo runtime reads only the keys the processor needs and ignores the rest. This keeps a single client-side body type for every method.
| Field | Type | Required | Notes |
|---|---|---|---|
processor | string | yes | Must be present in the paymentMethods array returned at creation time. |
data | object | yes (may be {}) | Unified field envelope. Send all fields and leave the ones that don't apply as null; see the field to processor mapping. |
Field to processor mapping
Keep a single data that covers every method. Fill only what applies to the chosen processor; leave the rest null, empty, or omitted — Migo only reads the active processor's keys.
{
"processor": "<akisiQR | bamPaymentButton | bancoIndustrial | pronet | quickPayQR | yoloQR | zigi | zigiQR | nequi | globalPay-PSE | fri>",
"data": {
"phoneNumber": null,
"user": null,
"bank": { "key": null },
"email": null,
"fisType": { "key": null },
"fiscalNumber": null,
"installments": null,
"userName": null,
"userType": { "key": null }
}
}
Field in data | Type | Used by |
|---|---|---|
phoneNumber | string | nequi; fri (at least one of phoneNumber / user) |
user | string | fri (at least one of phoneNumber / user) |
bank | object { key } | globalPay-PSE |
email | string | globalPay-PSE |
fisType | object { key } | globalPay-PSE |
fiscalNumber | string | globalPay-PSE |
installments | number | globalPay-PSE |
userName | string | globalPay-PSE |
userType | object { key } | globalPay-PSE |
Processors with no data fields (send data: {}): akisiQR, bamPaymentButton, bancoIndustrial, pronet, quickPayQR, yoloQR, zigi, zigiQR. In Guatemala every available method falls here — the customer pays from their app after Migo issues the QR / push.
The field values for globalPay-PSE (the bank, fisType, userType keys) and the fri field descriptor are fetched via payment intents.
cURL — BAM Payment Button (Guatemala)
curl -X POST https://mw.migopayments.com/api/v1/integrations/transactions/trx_8f3c2b1d9e7a/payments \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"processor": "bamPaymentButton",
"data": {}
}'
Node.js
const res = await fetch(
`https://mw.migopayments.com/api/v1/integrations/transactions/${transactionId}/payments`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MIGO_JWT}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
processor: 'bamPaymentButton',
data: {},
}),
}
);
const { data } = await res.json();
// data.type drives the rendering branch
if (data.type === 'url') window.location.href = data.data; // Zigi, BAM Payment Button
if (data.type === 'base64') renderImage(data.data); // Akisi QR, Banco Industrial, YOLO QR
if (data.type === 'json') renderStructuredPayload(data.data); // Pronet, QuickPay QR, FRI
Per-processor request examples
Every example uses the same unified body shape. Keep the same client-side type and only populate the fields that apply — Migo ignores keys outside the active processor's payload.
Guatemala — methods with no data
akisiQR, bamPaymentButton, bancoIndustrial, pronet, quickPayQR, yoloQR, zigi, zigiQR — the customer pays from their app after Migo issues the QR / push notification. Send an empty data:
{
"processor": "akisiQR",
"data": {}
}
yoloQR (Bantrab's YOLO wallet)
yoloQR follows the same shape (empty data) and returns a ready-to-render QR as data.type base64:
{
"success": true,
"message": "Success",
"data": {
"transaction_id": "37d25fa5-608f-f111-9968-005056afc378",
"type": "base64",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMQAAADE…",
"cancelAt": 600
}
}
transaction_id is the charge identifier at Bantrab, not the transaction uid in Migo: to query the status or dismiss the transaction, use the uid returned by create transaction.
Before you integrate it, keep these rules in mind:
- GTQ only. In a transaction in any other currency, yoloQR does not appear in data.paymentMethods and /payments returns 400.
- Amount within the limits. Migo applies the minimum and maximum configured for your account and for the method; when no minimum is configured, the minimum is GTQ 50.00. Outside those limits the method still appears in data.paymentMethods and the payment page shows it disabled or hides it, depending on your account's configuration; a direct call to /payments is rejected with 400.
- Single-use QR. Each QR accepts one payment and each transaction generates a single QR. If the customer needs to try again, create a new transaction.
- Expiration on Migo's side. The cancelAt field tells you how many seconds the QR has left; when it runs out, Migo cancels the transaction. The provider supports neither refunds nor cancellations, so dismissing the transaction only cancels it in Migo.
- Asynchronous confirmation. The result arrives when the provider reports the payment, and Migo passes it on through the callback configured for your account.
- Payment after expiration. If the customer pays a QR that already expired, the transaction stays cancelled and you do not receive a new callback: the payment is left for Migo to review manually. If your customer reports paying an expired transaction, contact Migo Operations with the uid.
To show progress while the customer pays, query the transaction status. The cancelAt field is the time the QR has left:
curl https://mw.migopayments.com/api/v1/integrations/transactions/{transactionId} \
-H 'Authorization: Bearer <token>'
{
"success": true,
"message": "Transaction status",
"data": {
"uid": "{transactionId}",
"status": "pending",
"cancelAt": 2940
}
}
If the transaction does not exist or does not belong to your account, the query returns 404. The status it returns is the one Migo has stored; the callback remains the authoritative result.
As with every other method, the authoritative list for a given transaction is the data.paymentMethods array returned by create transaction: if yoloQR is not there, it is not enabled for your account. Contact Migo Operations to request it.
fri (push payment, Guatemala sandbox)
fri requires at least one of user or phoneNumber (descriptor fetched via payment intents):
{
"processor": "fri",
"data": { "user": "fri-user-001" }
}
globalPay-PSE (Colombia — bank selector)
Fill data with the values returned by the payment intent:
{
"processor": "globalPay-PSE",
"data": {
"bank": { "key": "1552" },
"email": "customer@example.com",
"fisType": { "key": "CC" },
"fiscalNumber": "2345678421",
"installments": 1,
"userName": "John Doe",
"userType": { "key": "N" }
}
}
Response shape by data.type
data.type | Render strategy | Payload field | Example processors |
|---|---|---|---|
url | Redirect customer to URL | data.data is the URL string | Zigi, BAM Payment Button |
qr | Render QR image from a raw EMVCo string | data.data is the QR string | (none currently) |
base64 | Drop the value into <img src=...> directly | data.data is a data:image/png;base64,… URI | Akisi QR, Banco Industrial, YOLO QR |
json | Structured payload (references) | data.data is the structured payload | Pronet, QuickPay QR, FRI |
data.data, not data.valueThe runtime emits the payload under data.data. Earlier recipes (notably recipes/guatemala.md) used data.value — that variant is outdated. When parsing the response, always read data.data.
Sample for type: "url":
{
"success": true,
"message": "success",
"data": {
"uid": "trx_8f3c2b1d9e7a",
"type": "url",
"data": "https://gateway.example.com/redirect/abc",
"cancelAt": 600
}
}
Sample for type: "base64" (Akisi QR — verified against sb-mw.migopayments.com):
{
"success": true,
"message": "Success",
"data": {
"transaction_id": "12740927961946781727",
"type": "base64",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAJQAAA…"
}
}
The transaction identifier in the response comes back as uid for some rails (e.g. Zigi, BAM Payment Button) and as transaction_id for others (e.g. Akisi QR, QuickPay QR, YOLO QR). The two fields you must always read to render are type and data.
Payment details
Once confirmed, the transaction exposes the normalized result in paymentInfo, the same as card payments: the payment method, the payer and the charge events. Alternative methods are charged in a single step, so paymentInfo.authorization comes back empty and the result is in paymentInfo.capture. See Normalized payment details (paymentInfo).
Polling vs webhooks
Migo confirms the final status through your processor webhook (APPROVED, DENIED, EXPIRED; in yoloQR expiration ends in cancelled). For UX you can poll the transaction status every 3–5 seconds while the customer completes the rail; do not rely on polling for state-of-record — the webhook is authoritative.
Errors
| HTTP | Cause |
|---|---|
| 400 | Missing parameters, processor not allowed for this client, or required data keys missing (response includes data.missingValues) |
| 401 | User-side authentication failed (Ridivi) |
| 405 | Processor temporarily unavailable (e.g. Banco Industrial returns an unavailabilityReason) |
| 500 | Processor request could not be processed |
For the semantics of each Middleware ownCode and the status-code mapping, see the Error catalog.