Mintcash
Guides

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:

StatusWhat the new card doesWebhooks
past_duePays the failed renewal. The subscription returns to active.subscription.succeeded and subscription.payment_method_updated
activeIs 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.

 hostedembedded (default)
What you getA complete page, branded with your theme and logoThe bare card form
What's on itPlan, billing period, the card being replaced, and the amount owed on a failed renewalOnly the card fields; the page around them is yours
Where it goesSent to the customer as-is, by email, SMS or your siteAn 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:

mode: hosted — secure.mintcash.me/r/<token>
AAcme Payments Ltd

Your Acme Payments Ltd renewal didn't go through

Pay $4.99 with a new card to keep your subscription active.

Your subscription
Renews$4.99 every 30 daysoverdue since 22 Oct 2026 · 1 of 3 intro payments left
Then$9.99 every 30 daysfrom 21 Dec 2026
Card on fileMastercard •••• 0000
Member since22 Sep 2026
Pay with a new card
Card details0000 0000 0000 0000
Expiry dateMM / YY
Security codeCVC
Pay $4.99 and update my card

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.

Secured by MintcashQuestions? ops@acme-payments.example

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.

mode: embedded — secure.mintcash.me/c/<session>
Card details0000 0000 0000 0000
Expiry dateMM / YY
Security codeCVC
Pay $4.99
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:

ConditionWhy
It has an unsettled invoiceThere must be a failed renewal for the new card to pay. A settled invoice has nothing owing.
No scheduled retry is mid-chargeMintcash 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

Rendering diagram…

The new card has to actually pay before it replaces the old one. On a successful charge, in one transaction:

  1. The failed invoice is settled and the subscription returns to active.
  2. The subscription's payment method is swapped to the new card, so every future renewal bills it.
  3. 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

  • embedded URLs are short-lived. hosted hands back the recovery link itself, so it survives 7 days in an inbox. embedded hands 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 an active subscription a different returnUrl or provider opens a new form; on past_due the open form is re-served for up to an hour whatever returnUrl you 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 returns 429, 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 returns 429 until 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:

CardWhat happens
5123 8172 3406 0000The card is confirmed after a 3DS challenge, and subscription.payment_method_updated fires
5519 2838 1203 0000The card is confirmed without 3DS, and subscription.payment_method_updated fires
4302 9128 3702 0000The 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