Skip to main content
Migo Docs

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.

Unsigned contract, no retries

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.callback through the Update Client Config flow.

For Migo-assisted configuration, send:

  1. Endpoint URL. The URL on your side that will receive the POST notifications (for example https://api.yourdomain.com/webhooks/transactions).
  2. Security headers (optional). Any custom HTTP headers Migo should include so you can authenticate the request β€” typically a static x-api-key or Authorization: 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"
}
}
}
}
}
}
FieldTypeRequiredDescription
config.callback.enabledbooleanYesEnables the callback configuration for the client.
config.callback.typestringYesConfigured callback type. For this contract, use generic.
config.callback.functionNamestringConditionalFunction 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.statusarray of stringsYesTransaction 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.urlstringYesAbsolute URL for your receiver. It must be valid and non-empty.
config.callback.data.methodstringYesHTTP method Migo will use to call your endpoint. It must be a method supported by the callback configuration.
config.callback.data.headersobjectYesHeaders 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.dataobjectYesBody 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.extraDataobjectNoOptional object persisted alongside the callback configuration. To add fields to the notification body, use extraData inside data instead (see Additional fields).

Configuration validations:

  • url must be a valid, non-empty URL.
  • method must be a supported HTTP method.
  • headers must be an object.
  • data must be an object.
  • extraData is optional.
  • status must be a non-empty array with supported statuses.
  • If callback is invalid, the update is not persisted.
Sensitive headers

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 sourceStatuses that fire the callback
Payment flows (cards and alternative payment methods)approved, denied, refunded, reversed
Manual capture flows (authorization pending capture)authorized
Cancellation flowscancelled
Services / credits flows (direct dispatch)approved, denied

Two important clarifications:

  • authorized is notified only on integrations with manual capture, when the processor authorizes the payment pending capture.
  • cancelled is 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 in callback.status.
  • callback.status is 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"
}
FieldTypeMax lengthDescriptionExample
referencestring100Migo-issued reference for the transaction. Returned in the response of POST /transactions.ORDER-98765
uidstring100Unique transaction identifier issued by Migo. Same value returned by the create-link call.ak_D3b0ETlw3Hw...
countrystring2ISO 3166-1 alpha-2 country code where the operation took place.GT
currencystring3ISO 4217 currency code.GTQ
channelstring100Channel or platform where the transaction originated.WhatsApp
statusstring20Status of the transaction. One of approved, denied, reversed, refunded, cancelled; on manual capture flows also authorized.approved
amountinteger12Total transaction amount in the smallest currency unit.150
externalIdstring100External 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
createdAtstring19Timestamp 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 extraData is 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 2xx once 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.