Skip to main content
Migo Docs

Direct payment API (PCI required)

Besides the hosted webview, you can manage the payment flow yourself over the API: you collect the card data in your own frontend and send it to Migo to authorize the charge. You own the entire checkout experience.

Requires PCI DSS certification

This flow sends raw card data (PAN, CVV, and expiry) to the Migo API. Collecting, transmitting, or storing untokenized card data requires you to be PCI DSS certified at the level matching your volume.

If you are not PCI certified, this flow will not work for you β€” integrate with the hosted Payment Link webview: the customer enters the card inside Migo's page and you never touch card data, so your PCI scope drops to SAQ-A.

Flow at a glance​

1. POST /transactions create the transaction β†’ uid
2. POST /pay send the card data β†’ authorize the charge (requires PCI)
3. GET /transactions?uid=... query the status
4. POST /pay/revert reverse an authorized charge
5. POST .../{uid}/dismiss dismiss an unpaid transaction

It's the same transaction model as the Payment Link: you create the transaction the same way, but instead of delivering the webview URL to the customer, you capture the card and call /pay.

Authentication and hosts​

Every call authenticates with your merchant token in the Authorization header (raw token; a leading Bearer is tolerated and stripped).

EnvironmentHost
Sandboxhttps://sb-mw.migopayments.com
Productionhttps://mw.migopayments.com

1. Create the transaction​

Identical to Create a Payment Link: POST /transactions.

curl -X POST https://sb-mw.migopayments.com/transactions \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{
"client": "<your-client-slug>",
"amount": 49,
"currency": "GTQ",
"userId": "oo41332322",
"channel": "web",
"ads": []
}'

Response:

{
"uid": "RULbsGlJRAWFCi6TkuTEa",
"reference": "INFOTECHGT000015",
"URL": "https://sandbox.migopayments.com/?orderId=RULbsGlJRAWFCi6TkuTEa"
}

In this flow you ignore the URL field (that's the hosted webview) and keep the uid to charge over the API.

2. Charge with the card data β€” POST /pay​

PCI step

This is the only step that touches card data. Only send it from a backend inside your PCI scope β€” never from the browser with your merchant token exposed.

curl -X POST https://sb-mw.migopayments.com/pay \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{
"processor": "visa-cybersource",
"installments": 1,
"card": {
"number": "4111111111111111",
"expMonth": "11",
"expYear": "2030",
"cvv": "123"
},
"transactionUid": "RULbsGlJRAWFCi6TkuTEa",
"billTo": {
"firstName": "Braian",
"lastName": "Florian",
"email": "customer@example.com",
"phoneNumber": "50244866448",
"address": "Guatemala zona 10, Oakland",
"city": "Guatemala",
"state": "GU",
"country": "GT",
"zipCode": "01000"
},
"sessionId": "58f60d2807514d8d9700308bad100287",
"tokenize": false,
"isForSubscription": false
}'
FieldTypeNotes
processorstringCard processor for your client (e.g. visa-cybersource). Confirm it with Migo.
installmentsnumberNumber of installments (1 if not used).
card.numberstringCard PAN. PCI data.
card.expMonth / card.expYearstringExpiry month and year. The year format depends on your account's processor β€” two or four digits β€” and we confirm it when we enable the account. Sending the wrong one is not rejected as a validation error: it surfaces as a communication failure with the processor.
card.cvvstringSecurity code. PCI data.
transactionUidstringThe uid returned when creating the transaction.
billToobjectCardholder billing data (firstName, lastName, email, phoneNumber, address, city, state, country, zipCode).
sessionIdstringDevice-fingerprint session id required by the processor for its fraud analysis.
tokenizebooleantrue to store a reusable card token.
isForSubscriptionbooleantrue if the charge is for a subscription.

Response (approved) β€” includes the status and the processor's paymentData:

{
"transaction": {
"reference": "INFOTECHGT000015",
"status": "approved",
"channel": "web",
"createdAt": "2026-06-12T22:43:39.000Z",
"paymentData": { "id": "7813042339096130604807", "pay": { "...": "..." } }
}
}

3. Query the transaction β€” GET /transactions​

curl 'https://sb-mw.migopayments.com/transactions/?uid=RULbsGlJRAWFCi6TkuTEa' \
-H 'Authorization: <merchant-token>'

Returns the full transaction record, including status (approved, reversed, …), total, currency, installments, timestamps, and paymentInfo β€” a normalized payment summary (card brand and last 4 digits, payer data, 3D Secure result, and authorization/capture events) that's the same shape regardless of which processor handled the charge. See Normalized payment details (paymentInfo) for the full shape of the field.

4. Reverse a charge β€” POST /pay/revert​

curl -X POST https://sb-mw.migopayments.com/pay/revert \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>' \
-d '{ "transactionUid": "RULbsGlJRAWFCi6TkuTEa" }'

The transaction moves to status: "reversed".

5. Dismiss a transaction β€” POST .../{uid}/dismiss​

For a transaction that hasn't been paid yet (abandoned or expired):

curl -X POST https://sb-mw.migopayments.com/api/v1/integrations/transactions/RULbsGlJRAWFCi6TkuTEa/dismiss \
-H 'Content-Type: application/json' \
-H 'Authorization: <merchant-token>'

Responds 200 OK. Behavior and eligible states in Dismiss transaction.

Receiving the result​

The terminal status is also delivered to your backend through the Merchant Generic Callback, just like in the hosted-webview flow.

Errors​

See the Error catalog for the Middleware error codes (error.code) and their semantics.