Skip to main content
Migo Docs

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.

FieldTypeRequiredNotes
processorstringyesMust be present in the paymentMethods array returned at creation time.
dataobjectyes (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 dataTypeUsed by
phoneNumberstringnequi; fri (at least one of phoneNumber / user)
userstringfri (at least one of phoneNumber / user)
bankobject { key }globalPay-PSE
emailstringglobalPay-PSE
fisTypeobject { key }globalPay-PSE
fiscalNumberstringglobalPay-PSE
installmentsnumberglobalPay-PSE
userNamestringglobalPay-PSE
userTypeobject { 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.

Availability

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.typeRender strategyPayload fieldExample processors
urlRedirect customer to URLdata.data is the URL stringZigi, BAM Payment Button
qrRender QR image from a raw EMVCo stringdata.data is the QR string(none currently)
base64Drop the value into <img src=...> directlydata.data is a data:image/png;base64,… URIAkisi QR, Banco Industrial, YOLO QR
jsonStructured payload (references)data.data is the structured payloadPronet, QuickPay QR, FRI
Field name is data.data, not data.value

The 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 identifier field varies by rail

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​

HTTPCause
400Missing parameters, processor not allowed for this client, or required data keys missing (response includes data.missingValues)
401User-side authentication failed (Ridivi)
405Processor temporarily unavailable (e.g. Banco Industrial returns an unavailabilityReason)
500Processor request could not be processed

For the semantics of each Middleware ownCode and the status-code mapping, see the Error catalog.