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 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:
| Notice | Has subscriptionId | What to do |
|---|---|---|
| Payment result | No | Treat it as a one-time payment |
subsCallback | Yes | Create / 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)"
}
| Field | Notes |
|---|---|
subscriptionId | The subscription identifier. It's what distinguishes this notice from the payment one. |
transactionId | The transaction that originated the charge |
status | active or inactive |
nextRenewalDate | Not ISO 8601. It's a JavaScript Date.toString() β parse it with a tolerant library, not strict Date.parse. |
amount | A number in subsCallback; a string in the payment callback. Don't assume the same type in both. |
States delivered by callbackβ
status | When |
|---|---|
active | Subscription signup and every successfully charged renewal |
inactive | Charge retries exhausted β stop billing and revoke access |
cancelled and expired are not notifiedThe 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.
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.
Relatedβ
- Subscriptions β the four states and how to read them
- Charges β what triggers each notice