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.
POST /api/v1/subscriptionsThe 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.
Create the linkβ
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": []
}'
BearerOn this route the token is sent raw: Authorization: <token>. The /v1/* routes (plans,
subscriptions) do use Authorization: Bearer <token>.
Fieldsβ
| Field | Required | Notes |
|---|---|---|
amount | Yes | Real 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. |
currency | No | GTQ (default) or USD. Send it explicitly; if omitted, Migo falls back to the first currency configured for your merchant. |
userId | Yes | Your end customer's identifier, typically their email. Must be stable: the subscription is tied to this value. |
channel | Yes | wa | sms | email | web | app |
client | Yes | Your merchant slug |
externalId | No | Your order id. It comes back on the callbacks β that's how you reconcile. Use a unique one per sale. |
customKeys.plan.uid | Yes (subscription) | The key that triggers subscription creation. Omit it entirely for a one-time charge. |
customKeys.emailTo | No | Email for the payment receipt |
customKeys.automaticRedirect | No | Per-status browser return URLs. If you send it, it overrides the one configured on your account. UX only β it does not replace the callback. |
ads | Yes | Always send [] |
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"
}
| Field | What it's for |
|---|---|
URL | The checkout. Uppercase β response.URL, never response.url. |
uid | The transaction identifier on Migo's side. Store it: it's what shows up in callbacks. |
reference | Human-readable charge reference |
uid Migo returnsCallbacks 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.
One use per linkβ
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β
| HTTP | error.code | Cause | What to do |
|---|---|---|---|
401 | β | Invalid or missing token | Check it's the token for the right environment and that it goes without Bearer |
409 | 5000 | A required field is missing or has the wrong type | Review amount, userId, channel, client |
409 | 5004 | The client does not exist | Confirm your slug; ask Migo to enable it in sandbox |
409 | 2003 | amount outside your configured min/max | Adjust the amount |
400 | 2004 / 2005 / 2006 | End customer blocked, suspended or excluded | Use a different userId |
Full catalog in Error Catalog.
Relatedβ
- Subscription callback β how you learn the outcome
- Plans β where the plan uid comes from
- Hosted Webview β how to customize the checkout