Skip to main content
Migo Docs

Subscription payment link

A subscription payment link is a regular transaction with a plan inside. Migo returns a hosted checkout URL you can send by email, WhatsApp or SMS, or embed in your app.

When your customer pays at that URL and the payment is approved, Migo creates the subscription automatically and stores the card for the following charges.

There is no POST /api/v1/subscriptions

The subscription isn't created by a call of its own: it's born from the payment. The only difference between a one-time charge and a subscription is the presence of customKeys.plan.uid in the transaction.

curl -X POST https://sb-mw.migopayments.com/transactions \
-H "Authorization: <your-merchant-token>" \
-H "Content-Type: application/json" \
-d '{
"amount": 99.00,
"currency": "GTQ",
"userId": "customer@example.com",
"channel": "web",
"client": "<your-client-slug>",
"externalId": "your-order-0001",
"customKeys": {
"emailTo": "customer@example.com",
"plan": { "uid": "<plan-uid>" },
"automaticRedirect": {
"approved": { "url": "https://your-app.example.com/checkout?status=approved" },
"denied": { "url": "https://your-app.example.com/checkout?status=denied" },
"expired": { "url": "https://your-app.example.com/checkout?status=expired" },
"cancelled": { "url": "https://your-app.example.com/checkout?status=cancelled" }
}
},
"ads": []
}'
The token goes without Bearer

On this route the token is sent raw: Authorization: <token>. The /v1/* routes (plans, subscriptions) do use Authorization: Bearer <token>.

Fields​

FieldRequiredNotes
amountYesReal amount in major units, as a JSON number β€” 99 or 99.50. Do not multiply by 100. This is the first charge; renewals use the plan's amount.
currencyNoGTQ (default) or USD. Send it explicitly; if omitted, Migo falls back to the first currency configured for your merchant.
userIdYesYour end customer's identifier, typically their email. Must be stable: the subscription is tied to this value.
channelYeswa | sms | email | web | app
clientYesYour merchant slug
externalIdNoYour order id. It comes back on the callbacks β€” that's how you reconcile. Use a unique one per sale.
customKeys.plan.uidYes (subscription)The key that triggers subscription creation. Omit it entirely for a one-time charge.
customKeys.emailToNoEmail for the payment receipt
customKeys.automaticRedirectNoPer-status browser return URLs. If you send it, it overrides the one configured on your account. UX only β€” it does not replace the callback.
adsYesAlways send []
Exact key path

It is customKeys.plan.uid. Not subscriptionData, not a top-level planUid. A misplaced key produces a perfectly valid one-time charge and no subscription at all β€” with no error.

Response​

201 Created (treat any 2xx as success):

{
"uid": "Ypo5z2zTpLqWoe3eVvZMH",
"reference": "REF000123",
"URL": "https://sandbox.migopayments.com/?orderId=Ypo5z2zTpLqWoe3eVvZMH"
}
FieldWhat it's for
URLThe checkout. Uppercase β€” response.URL, never response.url.
uidThe transaction identifier on Migo's side. Store it: it's what shows up in callbacks.
referenceHuman-readable charge reference
Store the uid Migo returns

Callbacks arrive with this uid, not with your externalId. If you look up your database by your own internal id, you'll find nothing and no subscription will ever be recorded β€” even though everything else works.

About the first charge amount​

The amount you send here is what's charged now. Subsequent renewals use the plan's amount, not this one. That lets you charge a different first installment (a promo, a manual proration) without touching the plan.

Each transaction is an individual, single-use payment intent: it gets paid, expires or is cancelled. To subscribe another customer, create another transaction. It is not a reusable shareable URL.

Errors​

HTTPerror.codeCauseWhat to do
401β€”Invalid or missing tokenCheck it's the token for the right environment and that it goes without Bearer
4095000A required field is missing or has the wrong typeReview amount, userId, channel, client
4095004The client does not existConfirm your slug; ask Migo to enable it in sandbox
4092003amount outside your configured min/maxAdjust the amount
4002004 / 2005 / 2006End customer blocked, suspended or excludedUse a different userId

Full catalog in Error Catalog.