Merchant Generic Callback
The Merchant Generic Callback is the outbound HTTP request that Migo sends to a merchant-owned endpoint with the final result of the transaction. It applies to every Migo payment flow: transactions created via Payment Link (POST /transactions) and transactions processed through the alternative payment method APIs. Your backend registers a URL with Migo and receives the notification there when the transaction reaches its final status.
For most integrations Migo sends a standard JSON payload documented below. The dispatch is driven by per-client configuration so the request method, URL, headers, body, and timeout can be customized when needed; the standard payload covers the common case and is what you should design your handler around unless you have agreed on a custom shape with Migo.
The Merchant Generic Callback does not sign the body with HMAC and has no automatic retries. Authenticity is validated through the headers you register (see Authenticating the request) and delivery is a single attempt (see Behavior on error).
How to configure your callbackβ
There are two ways to configure the callback:
- Migo-assisted configuration. Send the information to Migo via support ticket or your integration contact so Migo can register your endpoint.
- Self-service configuration. If your merchant has access enabled to Client Config Management, you can update
config.callbackthrough the Update Client Config flow.
For Migo-assisted configuration, send:
- Endpoint URL. The URL on your side that will receive the
POSTnotifications (for examplehttps://api.yourdomain.com/webhooks/transactions). - Security headers (optional). Any custom HTTP headers Migo should include so you can authenticate the request β typically a static
x-api-keyorAuthorization: Bearer <token>. By default Migo sends no extra headers; you must provide them explicitly if you want them.
Self-service configuration through Client Config Managementβ
When access is enabled for your merchant, the Update Client Config flow in Client Config Management (PUT /properties on that surface) can persist the callback configuration in the existing Client Config structure. Send callback inside config; if you do not send callback, Update Client Config keeps the previous behavior and only updates the properties you included.
status defines the transaction states configured for the callback. It acts as a filter over the statuses Migo notifies (see When the callback fires). Do not place it inside callback.data.status: it is persisted as callback.status.
Request example:
{
"client": "merchant-slug",
"source": "merchant-portal",
"config": {
"callback": {
"enabled": true,
"type": "generic",
"functionName": "generic",
"status": ["approved", "denied"],
"data": {
"url": "https://merchant.example.com/callback",
"method": "POST",
"headers": {
"x-api-key": "<merchant-secret>"
},
"data": {
"reference": "{{reference}}",
"uid": "{{uid}}",
"country": "{{country}}",
"currency": "{{currency}}",
"channel": "{{channel}}",
"status": "{{status}}",
"createdAt": "{{createdAt}}",
"amount": "{{total}}",
"externalId": "{{externalId}}",
"extraData": {
"source": "client-config"
}
}
}
}
}
}
| Field | Type | Required | Description |
|---|---|---|---|
config.callback.enabled | boolean | Yes | Enables the callback configuration for the client. |
config.callback.type | string | Yes | Configured callback type. For this contract, use generic. |
config.callback.functionName | string | Conditional | Function name or mechanism configured for the callback. For generic callback, generic can be used; other mechanisms may require a value agreed with Migo. |
config.callback.status | array of strings | Yes | Transaction states configured for the callback. It must be a non-empty array with supported statuses, for example approved and denied. It is persisted as callback.status. |
config.callback.data.url | string | Yes | Absolute URL for your receiver. It must be valid and non-empty. |
config.callback.data.method | string | Yes | HTTP method Migo will use to call your endpoint. It must be a method supported by the callback configuration. |
config.callback.data.headers | object | Yes | Headers Migo will send to the receiver. It must be an object; use placeholders or static values only when they are agreed for your integration. |
config.callback.data.data | object | Yes | Body template that Migo resolves against the transaction before sending the callback. It must be an object. It accepts an extraData key with additional fields β see Additional fields. |
config.callback.data.extraData | object | No | Optional object persisted alongside the callback configuration. To add fields to the notification body, use extraData inside data instead (see Additional fields). |
Configuration validations:
urlmust be a valid, non-empty URL.methodmust be a supported HTTP method.headersmust be an object.datamust be an object.extraDatais optional.statusmust be a non-empty array with supported statuses.- If
callbackis invalid, the update is not persisted.
Headers such as Authorization, x-api-key, token, secret, password, or apiKey may contain credentials. They must not be exposed in full in logs, tickets, screenshots, or shared examples; use masked values or placeholders when documenting them.
When the callback firesβ
Migo emits the callback at the end of the transaction, only for terminal statuses, regardless of how the payment originated (payment link, direct API, or alternative payment method):
| Trigger source | Statuses that fire the callback |
|---|---|
| Payment flows (cards and alternative payment methods) | approved, denied, refunded, reversed |
| Manual capture flows (authorization pending capture) | authorized |
| Cancellation flows | cancelled |
| Services / credits flows (direct dispatch) | approved, denied |
Two important clarifications:
authorizedis notified only on integrations with manual capture, when the processor authorizes the payment pending capture.cancelledis notified when the transaction is cancelled (for example, cancelling a QR or a pending payment).- Other lifecycle statuses (
expired,pending,challenge, etc.) do not fire the Merchant Generic Callback, even though the configuration accepts declaring them incallback.status. callback.statusis an additional filter: if you define it, out of the firing statuses above only the ones in your list are delivered.
You may receive the callback through either dispatch path depending on which Migo flow handled the transaction. Your handler should not assume a single source; design it to be idempotent on (uid, status).
Standard payloadβ
Migo sends a POST with Content-Type: application/json to the URL you registered. The body is:
{
"reference": "ORDER-98765",
"uid": "ak_D3b0ETlw3HwPmQ3MNK",
"country": "GT",
"currency": "GTQ",
"channel": "WhatsApp",
"status": "approved",
"amount": 150,
"externalId": "ext_auth_123",
"createdAt": "05/03/2026 07:22:32"
}
| Field | Type | Max length | Description | Example |
|---|---|---|---|---|
reference | string | 100 | Migo-issued reference for the transaction. Returned in the response of POST /transactions. | ORDER-98765 |
uid | string | 100 | Unique transaction identifier issued by Migo. Same value returned by the create-link call. | ak_D3b0ETlw3Hw... |
country | string | 2 | ISO 3166-1 alpha-2 country code where the operation took place. | GT |
currency | string | 3 | ISO 4217 currency code. | GTQ |
channel | string | 100 | Channel or platform where the transaction originated. | WhatsApp |
status | string | 20 | Status of the transaction. One of approved, denied, reversed, refunded, cancelled; on manual capture flows also authorized. | approved |
amount | integer | 12 | Total transaction amount in the smallest currency unit. | 150 |
externalId | string | 100 | External identifier associated with the transaction. Its content depends on the payment method and the processor: it can be the processor's payment reference or id, the order number, the generated QR id, or the identifier your backend sent when creating the transaction. | ext_auth_123 |
createdAt | string | 19 | Timestamp when the transaction was originally created, formatted as DD/MM/YYYY HH:MM:SS. | 05/03/2026 07:22:32 |
Additional fields (extraData)β
If you need the notification to include extra fields, configure extraData inside the body template (data in the callback configuration): an object of key/value pairs that is appended to the payload. Values can be static or {{...}} placeholders resolved against the transaction.
The body composition follows these rules:
- No body template configured β Migo sends the standard payload above.
- Body template with only
extraDataβ Migo sends the standard payload plus your extra fields. - Body template with your own fields β your fields replace the standard payload, and
extraDatais appended at the end.
Authenticating the request on your sideβ
The Merchant Generic Callback does not sign the body with HMAC. Authenticity is delegated to the merchant via the headers you registered with Migo β typically a static API key sent on Authorization or a custom header (for example x-api-key).
Verify the header in your handler before processing the body. If you need stronger guarantees (HMAC, signed JWT, mTLS), coordinate with Migo so the configuration can be extended for your client; it is not part of the standard contract.
Receiver skeleton (Node.js / Express)β
import express from 'express';
const app = express();
const MIGO_API_KEY = process.env.MIGO_WEBHOOK_API_KEY;
app.post(
'/webhooks/transactions',
express.json({ limit: '1mb' }),
async (req, res) => {
// 1. Authenticate the request via the header you registered with Migo.
if (req.header('x-api-key') !== MIGO_API_KEY) {
return res.status(401).send('invalid credentials');
}
const { uid, status, reference, amount, currency } = req.body;
// 2. Idempotency: dedupe on (uid, status). Migo may deliver the same
// notification more than once if a queued message is replayed.
if (await alreadyProcessed(uid, status)) {
return res.status(200).json({ ack: 'duplicate' });
}
// 3. Process based on req.body.status:
// - "approved" -> mark order as paid, fulfill, etc.
// - "denied" -> mark order as failed, notify the customer.
// - "refunded" -> reverse fulfillment, update accounting.
// - "reversed" -> idem.
// - "authorized" -> payment authorized, pending capture (manual capture flows).
// - "cancelled" -> transaction cancelled, release the order.
await processCallback(req.body);
// 4. Respond 2xx so Migo records a successful delivery.
res.status(200).json({ ack: 'received' });
},
);
Recommendations:
- Always respond
2xxonce your processing is durable; failing the response makes Migo log a delivery error. - Make the handler idempotent on
(uid, status). Treat repeat deliveries as a normal case. - Validate the schema against the standard payload above; only extend it if you have agreed on a custom payload with Migo.
- Keep your processing fast or move it to a queue inside your system. Migo applies a default timeout of 25 seconds.
Behavior on errorβ
Migo makes a single delivery attempt per notification: there are no automatic retries on any dispatch path. If your endpoint responds with an HTTP error or the request exceeds the timeout (25 seconds by default), the failure is logged and the request / response are persisted as transaction steps, so a Migo operator can reprocess manually if needed.
Even without retries, design your handler to be idempotent: the queue infrastructure that dispatches part of the callbacks guarantees at-least-once delivery, so you may occasionally receive the same notification more than once.
If your business requires specific delivery guarantees, coordinate with Migo.
Configuration exampleβ
{
"enabled": true,
"type": "generic",
"functionName": "generic",
"status": ["approved", "denied"],
"data": {
"method": "POST",
"url": "https://api.merchant.com/migo/callback?trx={{uid}}",
"headers": {
"Authorization": "Bearer <merchant-static-api-key>",
"Content-Type": "application/json"
},
"data": {
"transactionUid": "{{uid}}",
"reference": "{{reference}}",
"status": "{{status}}",
"amount": "{{total}}",
"currency": "{{currency}}",
"metadata": "{{customKeys}}",
"extraData": {
"source": "client-config"
}
},
"timeout": 30000
}
}
When a transaction with uid = "abcd1234efgh" reaches approved, Migo sends a POST to https://api.merchant.com/migo/callback?trx=abcd1234efgh with the Authorization header above and a JSON body where every placeholder is resolved against the transaction, plus the source field appended by extraData.
Relatedβ
- Create a Payment Link β the inbound contract you call to obtain the webview URL.
- Hosted Webview β the customer payment experience for Payment Link.