Subscriptions
Recurring billing. Create a subscription, query its status, or cancel it. Retries and email notifications are handled for you.
A Subscription represents a recurring agreement to charge a customer on a fixed interval. The lifecycle moves through created → pending → active → past_due → cancelled — see Concepts → Subscriptions for the full state machine and the retry schedule.
Create a subscription
Create a subscription.
Authentication: Basic Auth (public_key:secret_key) with merchant role.
In: header
Response Body
application/json
application/json
curl -X POST "https://sandbox.mintcash.me/subscriptions" \ -H "Content-Type: application/json" \ -d '{ "amount": 0, "billingIntervalDays": 0, "currency": "string", "externalId": "string" }'{
"amount": 0,
"billingIntervalDays": 0,
"createdAt": "string",
"currency": "string",
"currentPeriodEnd": "string",
"currentPeriodStart": "string",
"externalId": "string",
"id": "string",
"phases": [
{
"amount": 0,
"billingIntervalDays": 0,
"id": "string",
"iterations": 0,
"name": "string",
"order": 0
}
],
"redirectUrl": "string",
"status": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}Retrieve a subscription
Get a subscription by ID.
Authentication: Basic Auth (public_key:secret_key) with merchant role.
In: header
Path Parameters
Response Body
application/json
application/json
curl -X GET "https://sandbox.mintcash.me/subscriptions/string"{
"amount": 0,
"billingIntervalDays": 0,
"createdAt": "string",
"currency": "string",
"currentPeriodEnd": "string",
"currentPeriodStart": "string",
"externalId": "string",
"id": "string",
"phases": [
{
"amount": 0,
"billingIntervalDays": 0,
"id": "string",
"iterations": 0,
"name": "string",
"order": 0
}
],
"redirectUrl": "string",
"status": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}Update the card on a subscription
Returns a URL where the customer enters a new card. Once they pay with it, that card becomes the one every future renewal bills.
Only available while the subscription is past_due — that is, after a renewal has already failed. Changing the card on an active subscription is on the roadmap; today the call is rejected with 400.
mode picks the surface: hosted for a self-contained page you send the customer, embedded (the default) for the bare card form to put in a page of your own.
Links last 7 days — though an embedded URL is a checkout session that expires after 15 minutes, so call again for a fresh one. An invoice accepts at most 5 submitted cards across every link it has, the ones in dunning emails included. Handing out a link does not pause the retry schedule. See Guides → Update a card on a subscription for the full behaviour and limits.
Start a card update for a subscription whose renewal failed.
Returns a URL where the customer enters a new card. Paying it settles the failed invoice and returns the subscription to active, and that card becomes the one future renewals bill — MintCash sends subscription.payment_method_updated, normally alongside subscription.succeeded. The card that was failing is left alone rather than deleted: payment methods are shared across a customer's other subscriptions and saved-card charges.
Modes. hosted returns a self-contained recovery page that explains the failed renewal and takes the card on the same page — send it to the customer as-is. embedded — the default — returns the bare checkout form to embed in a page of your own.
When it is allowed. Only a past_due subscription with an unsettled invoice, and only while no scheduled retry is mid-charge — a competing charge is refused rather than raced. Reach for it when a customer tells you their card is dead, instead of waiting for the next dunning email.
Limits. The underlying link stops working after 7 days. hosted hands back that link, so its URL lasts as long; embedded hands back a checkout session, whose URL expires after 15 minutes — call again for a fresh one. Across every link on one invoice — the ones in dunning emails included — at most 5 cards may be submitted; past that the invoice's links are spent (card-testing protection). Opening a link costs nothing, only a submitted card counts. Calling twice in embedded mode re-serves the same link, and within the hour the same checkout session, so a double-click cannot charge twice; hosted mints a fresh page per call, because its token exists only at creation (the row keeps a hash). Card only: Apple Pay and Google Pay are hidden on both surfaces, since a wallet sale leaves no token renewals could bill. The customer is not asked whether to save the card either — handing it over is the point of the flow.
It does not pause dunning. Scheduled retries keep running on the old card while a link is live, and a failed recovery attempt does not advance the ladder. Whichever charge settles the invoice first wins; a second success on the same invoice is flagged for refund.
Authentication: Basic Auth (public_key:secret_key) with merchant role.
In: header
Path Parameters
hosted is a self-contained recovery page to send the customer as-is; embedded is the bare card form to put in a page of your own.
On embedded this is checkout's own return URL — the customer is sent there after the attempt, with paymentId appended. On hosted the recovery page keeps the customer on our side through the result and offers this as the way back to you, so a link without it simply has no return button.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://sandbox.mintcash.me/subscriptions/string/card-update" \ -H "Content-Type: application/json" \ -d '{}'{
"mode": "string",
"url": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}Cancel a subscription
Cancellation is immediate and irreversible. Pending invoices are not charged.
Cancel an active or past_due subscription.
Cancellation is immediate. The subscription will not renew. The current period remains valid (no prorated refund at MVP).
Authentication: Basic Auth (public_key:secret_key) with merchant role.
In: header
Path Parameters
Query Parameters
Response Body
application/json
application/json
curl -X DELETE "https://sandbox.mintcash.me/subscriptions/string"{
"amount": 0,
"billingIntervalDays": 0,
"createdAt": "string",
"currency": "string",
"currentPeriodEnd": "string",
"currentPeriodStart": "string",
"externalId": "string",
"id": "string",
"phases": [
{
"amount": 0,
"billingIntervalDays": 0,
"id": "string",
"iterations": 0,
"name": "string",
"order": 0
}
],
"redirectUrl": "string",
"status": "string"
}{
"code": "not_found",
"details": {},
"message": "string"
}