Integration in 4 steps
The whole recurring flow is four steps, and only two of them are your code. Work in sandbox from start to finish; going live is just changing the base URL.
The AI agent guide is this same journey in a deterministic format, meant to be handed to a coding assistant.
Before you startβ
export MIGO_API_BASE="https://sb-mw.migopayments.com" # sandbox
export MIGO_TOKEN="<your-merchant-token>"
export MIGO_CLIENT="<your-client-slug>"
On POST /transactions the token is sent without the Bearer prefix. The /v1/* routes do use
Authorization: Bearer <token>. This is the difference that costs the most time.
Step 1 β Create the planβ
The plan defines how much and how often. Create it once and reuse it across as many subscriptions as you want.
curl -X POST "$MIGO_API_BASE/api/v1/plans" \
-H "Authorization: Bearer $MIGO_TOKEN" -H "Content-Type: application/json" \
-d '{"client":"'"$MIGO_CLIENT"'","plan":{"name":"Monthly plan","amount":99.00,
"currency":"GTQ","type":"interval","methods":["<processor-slug>"],"installments":[1],
"frequency":{"frequency":30,"day":1,"shortDescription":"Monthly",
"longDescription":"Charged every 30 days"},
"autoRenewal":true,"dailyAttempts":3,"daysNotifyExpiringCard":7}}'
Verify: the response carries the plan uid. Store it β it's the only thing you need from step 1.
β Full field contract in Plans.
Step 2 β Generate the payment linkβ
This is the only call you make per sale. The plan travels inside the transaction at
customKeys.plan.uid: that key is exactly what turns a one-time charge into a subscription.
curl -X POST "$MIGO_API_BASE/transactions" \
-H "Authorization: $MIGO_TOKEN" -H "Content-Type: application/json" \
-d '{"amount":99.00,"currency":"GTQ","userId":"customer@example.com","channel":"web",
"client":"'"$MIGO_CLIENT"'","externalId":"your-order-0001","ads":[],
"customKeys":{"emailTo":"customer@example.com","plan":{"uid":"<plan-uid>"}}}'
Response (201):
{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "REF000123",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
Verify:
- Read it as uppercase
URL.const { url } = responsereturnsundefinedβ the single most common bug in this integration. - Store
uid: it's the identifier Migo will use when it talks to you in callbacks, not yourexternalId.
β All fields and their rules in Subscription payment link.
Step 3 β Receive the callbackβ
Your customer opens the URL, pays with their card, and Migo creates the subscription by itself.
You find out through the callback, not through the browser redirect.
Implement your endpoint before the first test payment, so the first notice has somewhere to land. You'll get two notices for the first charge:
| Notice | What it means | How to tell them apart |
|---|---|---|
| Payment callback | The charge was approved | Has no subscriptionId |
subsCallback active | The subscription was created | Carries subscriptionId and nextRenewalDate |
Rules you can't skip:
- Idempotency is mandatory. The same notice may arrive more than once; processing it twice must not change your state.
- Act only on
approved. The callback also fires for declined payments. - Verify the secret on every request before reading the body.
β Payload, headers and replay examples in Subscription callback.
Step 4 β Let Migo chargeβ
There's no step 4 on your side: you're done. On every renewal Migo takes the stored card, charges
it and sends you another subsCallback. If the charge fails it retries per the plan; once retries
are exhausted the subscription becomes inactive and you're notified.
All that's left is reacting to the callback: grant or revoke access.
β Cadence, retries and history in Charges.
Verificationβ
Consider the integration finished when:
- You created a plan and stored its uid.
POST /transactionswithcustomKeys.plan.uidreturns201and aURL.- Your callback endpoint rejects a request with an invalid secret.
- Your endpoint is idempotent: the same notice twice duplicates nothing.
- You completed one real sandbox payment and received the
activesubsCallback. GET /api/v1/subscriptions/detail/{subUid}returns that subscription asactive.- An
inactivesubsCallbackrevokes access in your app.
Going liveβ
Swap sb-mw.migopayments.com for mw.migopayments.com, use the production token and register the
production callback URL with Migo. Sandbox plans do not migrate: create them again.