Skip to main content
Migo Docs

Subscription callback

Migo notifies your backend over HTTP POST every time a subscription changes state or a charge runs. That notice β€” subsCallback β€” is your source of truth.

The browser redirect is not a confirmation

The customer landing back on your success URL does not mean the payment was approved: they may close the tab first, or open that URL by hand. Grant access only when the callback arrives.

The two notices of the first charge​

The first payment fires two distinct notifications with the same transaction identifier. Tell them apart by the presence of subscriptionId:

NoticeHas subscriptionIdWhat to do
Payment resultNoTreat it as a one-time payment
subsCallbackYesCreate / renew / revoke the subscription
app.post('/migo/callback', async (req, res) => {
if (!verifySecret(req)) return res.status(401).end();

const { subscriptionId } = req.body;
if (subscriptionId) {
await handleSubscription(req.body); // idempotent
} else {
await handlePayment(req.body); // charge result
}
return res.status(200).end(); // ack fast
});

If you answer anything other than 2xx, Migo retries. That's why your handler must be idempotent.

Payload β€” subsCallback​

Fields sit at the root of the body:

{
"subscriptionId": "sub_000001",
"transactionId": "trx_A1",
"status": "active",
"transactionStatus": "approved",
"plan": "Monthly plan",
"amount": 99.00,
"email": "customer@example.com",
"nextRenewalDate": "Sat Aug 08 2026 06:00:00 GMT+0000 (Coordinated Universal Time)"
}
FieldNotes
subscriptionIdThe subscription identifier. It's what distinguishes this notice from the payment one.
transactionIdThe transaction that originated the charge
statusactive or inactive
nextRenewalDateNot ISO 8601. It's a JavaScript Date.toString() β€” parse it with a tolerant library, not strict Date.parse.
amountA number in subsCallback; a string in the payment callback. Don't assume the same type in both.

States delivered by callback​

statusWhen
activeSubscription signup and every successfully charged renewal
inactiveCharge retries exhausted β€” stop billing and revoke access
cancelled and expired are not notified

The callback only emits active and inactive. If you need to know about a cancellation or an expiry, reconcile against the API: poll GET /api/v1/subscriptions/detail/{subUid} with a scheduled job. This is the most common gap when building on this integration.

Notice authentication​

The notice arrives with a header and secret configured per merchant β€” there's no HMAC and no fixed header name. HTTP Basic is also supported.

Verify the secret before reading the body and answer 401 if it doesn't match. Agree the exact header name and secret with Migo when your account is set up.

Configurable payload​

The body is built from a per-merchant template, so the exact keys you receive depend on your configuration.

Ask for the identifiers to be included

The default template may omit subscriptionId and transactionId. Without them you can neither tell the two notices apart nor reconcile. Confirm with Migo that both are included before going live.

Test your handler without waiting for a real payment​

POST these to your own endpoint. They reproduce the real shape of the notice:

# 1. Signup / renewal β†’ grant access
curl -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: $CALLBACK_SECRET" \
-d '{"subscriptionId":"sub_TEST_001","transactionId":"trx_TEST_A1","status":"active",
"transactionStatus":"approved","plan":"Monthly plan","amount":99.00,
"email":"customer@example.com",
"nextRenewalDate":"Sat Aug 08 2026 06:00:00 GMT+0000 (Coordinated Universal Time)"}'

# 2. Payment result for the SAME charge (no subscriptionId, amount is a string)
curl -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: $CALLBACK_SECRET" \
-d '{"uid":"trx_TEST_A1","status":"approved","reference":"REF000123","amount":"99",
"currency":"GTQ","externalId":"your-order-0001"}'

# 3. Duplicate delivery of notice 1 β†’ must change nothing
# 4. Retries exhausted β†’ revoke access
curl -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: $CALLBACK_SECRET" \
-d '{"subscriptionId":"sub_TEST_001","transactionId":"trx_TEST_A2","status":"inactive","plan":"Monthly plan"}'

# 5. Wrong secret β†’ must answer 401
curl -i -X POST "$CALLBACK_URL" -H 'Content-Type: application/json' \
-H "$CALLBACK_HEADER: WRONG" -d '{"subscriptionId":"x","status":"active"}'

Your handler passes if: (1) it grants access and stores subscriptionId + nextRenewalDate; (2) it treats notice 2 as a payment and does not overwrite the subscription; (3) the duplicate changes nothing; (4) the inactive revokes access; (5) the wrong secret returns 401.

Email notifications​

Besides the callback, Migo emails the end customer at several points of the cycle: addPaymentMethod, deletePaymentMethod, cancelSubscription, subPayProblem, subscriptionSuspended and notifyCardExpiration.

These are cardholder notifications, not an integration contract: don't rely on them for your business logic.

  • Subscriptions β€” the four states and how to read them
  • Charges β€” what triggers each notice