Skip to main content
Migo Docs

Create a Payment Link

A Payment Link is a hosted webview URL that lets a Migo merchant collect a payment from an end customer without writing front-end payment code. Your backend creates the link by calling Migo, and you deliver the resulting URL to the customer through any channel you operate (WhatsApp, SMS, email, in-app message, QR code, etc.).

Your only API call is creating the transaction. The customer then completes the entire payment inside Migo's hosted webview β€” entering the card, choosing installments, passing 3D Secure β€” and Migo reports the outcome back to your backend through a webhook. You never collect card data and never call a "charge" endpoint yourself.

PCI certified?

If you are PCI DSS certified and want to own the checkout, you can manage the payment flow over the API (capture the card and charge it yourself) instead of the hosted webview β€” see Direct payment API (PCI required). Without PCI certification, use the hosted webview.

Test cards

To test in Sandbox without real charges, use Migo's test cards.

Your backend creates the link with POST /transactions, Migo answers { uid, reference, URL }, you deliver the URL to the customer, the customer pays inside the hosted webview, and Migo reaches a terminal status that lands on your backend through a webhook. Creation and reception are yours; the payment inside the webview happens entirely inside Migo. The step-by-step walkthrough is in the Payment Link Quick Start.

This page details creating the link; the result of the payment is later delivered to your backend through the Merchant Generic Callback.

POST /transactions​

This is the recommended endpoint for backend-to-backend integrations.

Endpoint​

POST https://sb-mw.migopayments.com/transactions (Sandbox)
POST https://mw.migopayments.com/transactions (Production)

Content type: application/json. Send the merchant token Migo issued for your application as the value of the Authorization header. The raw token (no scheme prefix) is recommended; a leading Bearer is tolerated and stripped:

Authorization: b6a615d8...0ba65c1 recommended (raw token)
Authorization: Bearer b6a615d8... accepted (the "Bearer " prefix is stripped)

Request body​

FieldTypeRequiredDescription
amountintegeryesTransaction subtotal in the smallest currency unit allowed by your client configuration. Must fall inside the min/max range configured for your client.
userIdstringyesIdentifier of the end customer in your domain (phone number, email, or your internal id).
channelstringyesCommunication channel through which you intend to deliver the payment link to the end customer (for example wa, app, sms, email, web).
clientstringyesSlug of your client as registered in Migo configuration.
adsarraynoReserved array, send [] if not used.

POST /transactions also accepts these optional fields: currency, externalId, customKeys, processorAmount, customerId, subscriptionData, and createdBy. The cURL and SDK examples that send currency/externalId are therefore valid against this endpoint too.

Allowed values for channel, userId, currency​

These three fields are validated against your client configuration. The values you can use depend on what is enabled for your specific client slug:

FieldCommon valuesHow to discover what your client accepts
channelwa (WhatsApp), sms, email, web, appChannels are gated per client. If your call returns error code 5000 for channel, the value is not enabled β€” ask your Migo contact to enable it.
userIdE.164 phone (+50224865444), email, or your internal idFormat is free-form: Migo stores it verbatim. Pick the format you can correlate with your own user records and stay consistent. For SMS / WhatsApp delivery the field must be a phone Migo can dispatch to.
currencyISO 4217 (GTQ, USD, MXN, CRC, HNL, DOP, COP, SVC)If omitted, Migo uses the first currency configured for your client. If the value isn't in the configured list it is silently coerced to the default β€” pass it explicitly when you need to be sure.

There is no public "client config" endpoint today, so the enabled channels, currencies, and processors are not self-service discoverable. Coordinate with your Migo contact to confirm what your client slug accepts, and treat a 5000/5004 error code response as a signal that a value is not enabled.

cURL example (Sandbox)​

Replace the placeholder token and client slug with the values issued to you for Sandbox.

curl --location 'https://sb-mw.migopayments.com/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: <your-sandbox-token>' \
--data '{
"amount": 1,
"userId": "50224865444",
"channel": "wa",
"client": "<your-client-slug>",
"ads": []
}'

Successful response​

{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "CAMPGT020007SB",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
FieldDescription
uidUnique transaction identifier in Migo. Use it to correlate the transaction with the Merchant Generic Callback and with any support enquiry.
referenceHuman-friendly reference that Migo derives from your client configuration. Surfaced in webhook payloads, dashboards, and refund operations.
URLHosted webview URL you deliver to the end customer. The field name is uppercase (URL, not url), exactly as emitted by the handler β€” keep that casing when you parse the response.
Common pitfall β€” destructuring URL

TypeScript / JavaScript snippets that use const { url } = response will silently get undefined. Always destructure as const { URL: paymentLink } = response or read the field with bracket notation response.URL.

What the customer does next​

Once you deliver the URL, everything else happens inside Migo's hosted webview β€” there is no further API call for you to make. See Hosted webview for how the checkout behaves, and the Payment Link Quick Start for what the customer does step by step.

Receiving the result​

Migo notifies your backend once the transaction reaches a terminal status (approved, denied, refunded, reversed). The Payment Link product delivers this through the Merchant Generic Callback β€” an outbound POST from Migo to a URL you register with support, carrying { uid, reference, status, amount, currency, ... }.

MechanismDirectionWhen
Merchant Generic CallbackMigo β†’ your backendThe transaction reaches a terminal status

Use the uid you received when creating the transaction to correlate the callback with it. The callback is not signed with HMAC β€” authenticity is delegated to a static API key/header you register with Migo. See Merchant Generic Callback β†’ Authenticating the request.

If you also need to look up the transaction (support, reconciliation), GET /transactions?uid= returns the full record, including paymentInfo β€” the normalized payment summary (card brand, last 4 digits, 3D Secure result, authorization/capture events). See Normalized payment details (paymentInfo).

Errors​

POST /transactions returns a Migo error envelope. The most actionable field is error.code (not error.ownCode β€” that field does not exist in the real response), which maps to a Migo error catalog entry.

Two error code spaces

Payment Link errors use the Middleware code space (low integers like 2002, 2007, 5000, 5004, nested under error.code). They are different from the Gateway error codes (7000–8099) documented in the Error Catalog. The full Payment Link error list is mirrored at the bottom of that page so you can map every code in one place.

HTTPcodeCauseWhat to do
4095000Required fields missing or invalid bodyCheck that amount, userId, channel, client are present with the right types.
401(none)Invalid token on POST /transactionsThe token is validated by the API Gateway custom authorizer, not the handler. On failure the gateway returns a generic 401 with body { "message": "Unauthorized" } β€” there is no Migo error envelope and no code. Verify the merchant token and the Sandbox/Production environment match.
4095004client slug not found in Migo configurationConfirm the slug; create or activate the client config in coordination with Migo.
4092003amount outside the min/max range configured for your merchant account, or any value in processorAmount exceeds amountAdjust the amount, or update the per-processor overrides so each is <= amount.
4002006End customer is excluded for this clientExcluded users cannot transact for this client.
4002004End customer is blocked for this clientBlocked users cannot transact for this client.
4002005End customer is suspended for this clientSuspended users cannot transact while the suspension is active.
4002002Generic creation errorRetry; if the error persists, contact Migo support with the uid (when available) and the request payload.

Next steps​

  1. Deliver the URL to the end customer through your channel of choice.
  2. Implement the Merchant Generic Callback so your backend receives the transaction outcome (approved / denied / refunded / reversed) once the customer completes the webview.
  3. For a copy-paste browser integration, follow the React Payment Link recipe. For a checklist of every value you need in Sandbox, see the Sandbox Quickstart.
  4. For the rest of the payment lifecycle (refunds, captures, processor-specific behavior, 3DS), explore the Migo Middleware API reference and the additional sections of this portal.