Update a card on a subscription
Send a customer a card-update link. After a failed renewal the new card pays it; on a healthy subscription the card is checked with the bank and nothing is charged.
Cards get lost, reissued, and expire mid-subscription. POST /subscriptions/{id}/card-update returns a URL where the customer enters a new one, and once it goes through, that card becomes the one every future renewal bills.
What "goes through" means depends on the subscription:
| Status | What the new card does | Webhooks |
|---|---|---|
past_due | Pays the failed renewal. The subscription returns to active. | subscription.succeeded and subscription.payment_method_updated |
active | Is checked with the customer's bank. Nothing is charged and nothing is refunded. | subscription.payment_method_updated only |
Choosing a mode
mode decides which surface the returned url opens. It defaults to embedded.
hosted | embedded (default) | |
|---|---|---|
| What you get | A complete page, branded with your theme and logo | The bare card form |
| What's on it | Plan, billing period, the card being replaced, and the amount owed on a failed renewal | Only the card fields; the page around them is yours |
| Where it goes | Sent to the customer as-is, by email, SMS or your site | An iframe on your own account or billing page |
Pick hosted when the link travels to the customer on its own and has to stand up without context. Pick embedded when the customer is already signed in to your product — on an account or billing screen — and you are supplying the context yourself.
hosted
A complete, self-contained page carrying everything the customer needs to act on: who is asking, what is owed, what they are agreeing to from here, the card that is being replaced, and the form. It follows your checkout theme, so it arrives in your branding, not Mintcash's.
This is the page for a past_due subscription:
Your Acme Payments Ltd renewal didn't go through
Pay $4.99 with a new card to keep your subscription active.
By paying you authorise Acme Payments Ltd to charge this card $4.99 now, then $4.99 every 30 days for 1 more payment, then $9.99 every 30 days until you cancel. This card replaces the Mastercard •••• 0000 for all future payments.
The mandate line under the button spells out the whole commitment — the amount now, the remaining intro payments, the recurring price it steps up to, and the card being replaced — so the customer is agreeing to the full schedule rather than just today's charge.
On an active subscription the same page shows the subscription and the card on file, tells the customer their bank will check the card and they won't be charged, and the button reads Confirm card.
embedded
The same card fields with nothing around them, sized to drop into an iframe on a page of your own. No merchant header, no subscription summary, no mandate copy: that context is yours to supply, and you should — the customer is authorising future renewals either way.
This is the form for a past_due subscription. On an active one the button reads Confirm card and the form tells the customer they won't be charged.
const res = await fetch(
`https://api.mintcash.me/subscriptions/${subscriptionId}/card-update`,
{
method: "POST",
headers: { Authorization: ..., "Content-Type": "application/json" },
body: JSON.stringify({
mode: "hosted",
returnUrl: "https://example.com/account/billing",
}),
},
);
const { url } = await res.json();When the customer finishes
On either status, the hosted page shows the customer a result page, with a link back to your returnUrl if you passed one. The embedded form posts the same messages to your page as the embedded checkout: mintcash:checkout with status: "succeeded" once the card is paid or confirmed, or a failure status the customer can retry from. Use it to close the frame and update your billing screen, and wait for the webhook before you treat the card as changed.
When you can call it
The subscription must be active or past_due. Any other status comes back as 400; a cancelled subscription is terminal.
On a past_due subscription, two more conditions are checked before a link is minted:
| Condition | Why |
|---|---|
| It has an unsettled invoice | There must be a failed renewal for the new card to pay. A settled invoice has nothing owing. |
| No scheduled retry is mid-charge | Mintcash refuses to race its own retry on the old card rather than risk a double charge. |
Card update on active subscriptions is available on request
Tell your account manager, and we enable it on your account. Until then, the
call on an active subscription is rejected with 400 failed_precondition.
Switching it off also stops active links already sent: they open on an
invalid-link page. past_due subscriptions are not affected.
Without it, a customer who wants a different card on a healthy subscription can only cancel it and start a new one with the new card, which resets the billing period. Otherwise the next failed renewal opens the past_due flow, and Mintcash emails them a card-update link at that point anyway.
Any other refusal comes back as 400, except a spent attempt cap, which is 429. The API reference lists every status this endpoint returns.
Choosing the route on an active subscription
The optional provider field names the route the card is checked on: the value your payment routing scheme reads from metadata.provider. It defaults to the subscription's own metadata.provider, then to the acquirer that last took a payment for it. With neither, the check goes wherever your routing scheme sends an untagged payment. The new card is bound to whichever route checks it, so later renewals bill through it. On past_due the value must still be well formed, but it isn't used: the card pays the renewal like any other payment.
The flow on a past_due subscription
The new card has to actually pay before it replaces the old one. On a successful charge, in one transaction:
- The failed invoice is settled and the subscription returns to
active. - The subscription's payment method is swapped to the new card, so every future renewal bills it.
- The link is consumed, so it can't be used again.
You receive subscription.succeeded, and alongside it subscription.payment_method_updated carrying the new card and the previousToken it replaced, so you can update your own stored copy. The event fires on every swap; the token fields are only filled in when the customer consented to saving the card. See Event types.
The two usually arrive together, but act on each one by itself: subscription.succeeded means the renewal is paid, and subscription.payment_method_updated means the subscription now bills the new card.
A decline is not the end of the link: the customer can try another card until the invoice's attempt cap is spent.
The flow on an active subscription
The customer enters a new card and their bank checks it. No money moves, so there is nothing to refund. Some banking apps list the check as a card verification from you, with no amount. Once the bank confirms the card, the subscription's payment method is swapped to it and every future renewal bills it. The subscription's status and billing dates don't change.
You receive subscription.payment_method_updated on its own. Its payment is the card check: it reads succeeded, with amount: 0 and purpose: "card_verification". Don't book it as a payment. No payment.* or other subscription.* event fires for the check. See Payload reference.
Occasionally a confirmed card isn't put on the subscription, for example when the subscription was cancelled in the meantime, or the customer confirmed a different card afterwards. No event fires then, and the subscription keeps the card it had. GET /subscriptions/{id} always shows the card it will bill.
If a renewal fails while the bank is checking the card, the card is still put on the subscription and subscription.payment_method_updated fires, but the failed renewal stays unpaid. Retries bill the new card, or send the customer a new link to pay it.
If the bank declines the card, no webhook fires and nothing changes on the subscription. The customer can try another, up to the daily cap.
If a hosted link sent while the subscription was active is opened after a renewal has failed, the same page takes the failed renewal instead of only checking the card, and the past_due flow applies. The customer needs no other link.
The old card is not deleted
Payment methods are shared across a customer's other subscriptions and saved-card charges, so the card being replaced stays on file. Only this subscription moves to the new one.
Wait for the webhook
A 200 from this endpoint means a link was minted, not that anything was paid
and not that the card changed. On past_due, treat subscription.succeeded
as the signal to restore access, exactly as you would for any other
subscription charge. On either status, subscription.payment_method_updated
is the signal the card changed.
Notes
embeddedURLs are short-lived.hostedhands back the recovery link itself, so it survives 7 days in an inbox.embeddedhands back a checkout session, which expires after 15 minutes. Mint it when the customer is actually looking at the page, not ahead of time. Calling again after it lapses returns a fresh session on the same link, and costs nothing against the attempt cap. Calling twice in a row re-serves the same session, so a double-click can't charge twice. On anactivesubscription a differentreturnUrlorprovideropens a new form; onpast_duethe open form is re-served for up to an hour whateverreturnUrlyou pass.- Opening a link is free. Only a submitted card counts against the cap, so a customer who opens the page and leaves — or a mail scanner that prefetches the link — costs nothing.
- On
past_due, the cap is per invoice, not per link. Minting a new link does not buy more attempts. Once the five are spent, every link on that invoice stops working, the ones in dunning emails included: this endpoint returns429, and any link already in the customer's hands opens on a dead-end page instead of a card form. - On
active, the cap is per subscription. At most 5 cards may be submitted in any rolling 24 hours. After that this endpoint returns429until the oldest attempt falls out of the window. - Wallets are hidden. Apple Pay and Google Pay are not offered on either surface: a wallet sale leaves no token that renewals could bill.
It does not pause dunning
On a past_due subscription, handing out a card-update link does not suspend the retry schedule:
- Scheduled retries keep running against the old card while the link is live.
- A failed attempt on the link does not advance the ladder, and does not bring the cancellation date closer.
- If every scheduled retry is exhausted, the subscription is cancelled and the link dies with it — even if it still has days of TTL left.
Testing
Use your test keys and the test cards. Create a test subscription and pay it, so it's active, then call this endpoint on it:
| Card | What happens |
|---|---|
5123 8172 3406 0000 | The card is confirmed after a 3DS challenge, and subscription.payment_method_updated fires |
5519 2838 1203 0000 | The card is confirmed without 3DS, and subscription.payment_method_updated fires |
4302 9128 3702 0000 | The card is declined. No webhook fires and the subscription keeps its card |
Check that your handler treats the card check as a card change, not a payment: purpose is card_verification and amount is 0.
See also
- API reference → Update the card on a subscription
- Retries — the dunning ladder that runs alongside this
- Emails — the dunning emails that carry their own links
- Subscriptions — the state machine behind
activeandpast_due