How alternative payments work

Alternative payments are built around an asynchronous checkout. The merchant starts the transaction, the customer completes the payment in an external rail, and Migo receives the processor result before the merchant treats the order as paid.

This page explains the flow at a product level. For schemas and exact payloads, use the Migo API reference. Authentication is shared across every call — see Authentication.

Actors

Actor	Responsibility
Merchant backend	Creates the order, calls Migo, stores the Migo transaction id, and waits for final status.
Merchant frontend	Shows the customer's available rails and renders the URL, QR, HTML, JSON payload, or payment button returned by Migo.
Migo API	Creates the transaction, validates the selected processor, routes the payment request, and normalizes the response.
Processor	Owns the rail-specific authorization experience and final approval or denial.
Customer	Confirms the payment in the external app, wallet, bank page, QR flow, or cash network.

End-to-end lifecycle

Merchant order
   │
   ▼
Create Migo transaction
   │
   ▼
Show enabled payment methods
   │
   ▼
Customer selects a rail
   │
   ├─► Optional: fetch payment intent metadata
   │
   ▼
Process payment
   │
   ▼
Render rail instruction
   │
   ▼
Customer completes payment
   │
   ▼
Processor confirms final status
   │
   ▼
Merchant fulfills or releases the order

Step 1 — Create the transaction

The merchant backend creates the alternative-payment transaction with the amount, channel, client, customer identifier, and optional metadata. Migo validates the merchant configuration and returns:

• a Migo transaction id;
• the alternative payment methods enabled for that merchant client;
• the expiration window for the transaction.

Go to Create transaction for the request details.

Step 2 — Let the customer choose a rail

The merchant frontend should render only the methods returned by Migo. That list is already filtered by the merchant client's configuration and the global alternative-payment processor catalog.

For example, one Guatemala merchant may receive QR rails (akisiQR, bancoIndustrial, quickPayQR) while another receives wallet or hosted-button options (zigi, pronet, bamPaymentButton). The frontend should not hard-code availability.

Go to Available payment methods to see the rails available for the selected country.

Step 3 — Fetch payment intent metadata when needed

Some rails need a pre-step before the payment can start. In Guatemala, most rails (zigi, akisiQR, bancoIndustrial, quickPayQR, pronet, bamPaymentButton) do not require it; the sandbox fri method can return a fixture you use to simulate an authorization.

Use payment intents only for processors that need that metadata. Rails that return a static redirect, QR, or cash reference can usually go directly to payment processing.

Go to Payment intents for supported processors and response examples.

Step 4 — Process the selected payment

The merchant backend calls the payment endpoint with the selected processor and the rail-specific data. Migo returns a normalized response that tells the merchant frontend what to render:

Response type	Customer experience
url	Redirect the customer to a hosted payment page.
base64	Drop the data:image/png;base64,… value straight into an <img> to show a QR.
html	Render or submit an HTML form.
json	Render a structured instruction or reference.
payButton	Show a wallet-style push-payment action.

See the authoritative per-rail mapping and the data.data field caveat in Process payment — Response shape by data.type.

Go to Process payment for processor-specific examples.

Step 5 — Wait for final confirmation

Most alternative payments are not final at the moment the customer sees the instruction. The merchant can keep the UI responsive with short polling, but the authoritative result should come from the final processor confirmation handled by Migo.

Fulfill the order only after the transaction reaches a successful final state. If the customer leaves, the rail expires, or the order is cancelled, release the checkout with Dismiss transaction.

Integration checklist

• Store the Migo transaction id with the merchant order.
• Render only payment methods returned by the create transaction response.
• Use payment intents only when the chosen processor requires metadata.
• Treat redirects, QR codes, cash references, and wallet pushes as asynchronous flows.
• Fulfill after final confirmation, not after rendering the payment instruction.
• Dismiss abandoned or expired transactions when the merchant order is no longer payable.