Skip to main content
Migo Docs

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.

AI-assisted integration

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>"
The token goes raw

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.


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 } = response returns undefined β€” 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 your externalId.

β†’ 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:

NoticeWhat it meansHow to tell them apart
Payment callbackThe charge was approvedHas no subscriptionId
subsCallback activeThe subscription was createdCarries 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 /transactions with customKeys.plan.uid returns 201 and a URL.
  • 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 active subsCallback.
  • GET /api/v1/subscriptions/detail/{subUid} returns that subscription as active.
  • An inactive subsCallback revokes 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.