Stripe Can Now Declare Why You're Charging a Saved Card. Visa Has Required That Since 2017.
Stripe's new setup_credential_usage field flags recurring, installment, or unscheduled card charges — a Visa mandate that's been live since 2017.
On the 2026-09-30.preview API version, Stripe added two small fields to the card payment method options: setup_credential_usage and stored_credential_usage. Each takes one of three values — recurring, installment, or unscheduled — and each exists to answer a single question card networks have been asking merchants to answer for nine years: when you charge a card you saved, what kind of charge is this actually? Until this release, Stripe gave you a way to say a card would be used off-session. It never gave you a way to say what off-session use meant.
Nine years is a long gap between a network mandate and the field that lets a Stripe integration actually comply with it natively. That gap didn't mean merchants were operating outside the rules the whole time — Stripe has always had a way to pass this information through lower-level parameters most integrations never touch. It meant the common path, the one most SaaS billing code actually runs, had no obvious place to put it. A field nobody sets by default is a field most integrations leave unset.
What the two new fields actually do
setup_credential_usage goes on a SetupIntent, or on a PaymentIntent that uses setup_future_usage — the moment you're saving a card for later, not charging it yet. You set it to declare what you expect to do with that saved card. stored_credential_usage goes on the later PaymentIntent that actually fires the off-session charge, and it's echoed back on the resulting Charge object under payment_method_details.card, so it's queryable after the fact too. Both take the same three values, because both are describing the same underlying transaction category from two different points in its life.
| Value | What it means | A SaaS example |
|---|---|---|
recurring | An off-session charge that happens on a regular, predictable schedule | Monthly or annual subscription renewal, billed automatically on the same cycle each time |
installment | A fixed payment plan you manage yourself, not an issuer installment product | Splitting an annual plan into four quarterly charges you schedule and track |
unscheduled | An off-session charge with no fixed schedule or date | A usage-based top-up fired automatically when a prepaid credit balance runs low |
Notice what's conspicuously absent from that list: anything about whether the customer is present. That's deliberate. setup_future_usage already covers presence — on_session or off_session — and Stripe uses it to help manage requirements like Strong Customer Authentication. These new fields sit next to that parameter, not inside it, because presence and transaction category are two separate questions a card network needs answered, and conflating them is exactly the gap that left merchants under-declaring for years.
The mandate this maps to isn't new, or Stripe-specific
Visa's stored credential framework, in place since 2017, applies to any merchant or wallet that stores a cardholder's payment details for future use — including the first transaction, if you flag it that way. The obligations are specific: disclose to the cardholder that you're storing their card for subscriptions or unscheduled charges, flag the initiating transaction as one where details are being stored, carry the original transaction's identifier forward into every later merchant-initiated charge on that credential, and stop reusing the credential if the issuer ever declines the first authorization until a later one actually succeeds. Mastercard runs a parallel set of rules under its own stored-credential program. Neither network waited for Stripe, or any other processor, to give merchants a convenient API field — the requirement existed on the wire regardless, through lower-level transaction flags that most merchant-facing tooling never surfaced directly.
What's changed recently is enforcement, not the underlying rule. Visa introduced new assessments in November 2025 specifically aimed at ensuring stored credential transactions carry the correct flag. That's a real tightening, even though the public documentation describing it doesn't publish a per-transaction dollar figure the way some other network fees do.
| Program | Network | In effect since | What it actually checks |
|---|---|---|---|
| Stored Credential Framework | Visa | 2017 | Whether a saved-card transaction is flagged, disclosed, and linked to its originating authorization |
| New stored-credential assessments | Visa | November 2025 | Whether that flag is set correctly, not just present |
| Credential Continuity Program ("MASI") | Mastercard | April 29, 2026 (US) | Whether a recurring charge still uses an outdated card number the issuer's updater service had already refreshed, at $0.09 per transaction |
That third row is worth separating out clearly, because it's easy to lump it in with the other two and it's actually a different mechanism entirely. Mastercard's Credential Continuity fee has nothing to do with whether you declared recurring versus unscheduled correctly. It fires when a recurring-flagged charge runs on a stale card number that Mastercard's Account Billing Updater had already refreshed at least ten days earlier — a card-freshness problem, not a classification problem. We've covered that side of the stack in our card account updater guide. The two issues can and do coexist on the same transaction: a charge can be correctly flagged as recurring and still get hit with a continuity fee because nobody pulled the refreshed card number, or incorrectly flagged and still clear the continuity check because the card number itself is current. Treating them as one problem means you only ever fix half of it.
Why "just mark it off-session" was never enough
Before these fields existed, the honest answer to "how do most Stripe integrations represent transaction type to the network" was: through setup_future_usage=off_session and not much else. That's a real signal — it tells Stripe the customer won't be present — but it's a single bit of information standing in for what the networks actually want, which is a category. A subscription renewal, a self-managed installment plan, and an irregular usage top-up all look identical to off_session, even though Visa and Mastercard's own rules distinguish between them, and even though they behave completely differently from a billing perspective: one has a known next date, one has a known end date, one has neither.
That ambiguity doesn't show up as an obvious error. It shows up as a transaction that processes, sometimes with a slightly different authorization outcome than it would have gotten correctly classified, and no line in your dashboard that says "this got approved despite an incomplete network flag." It's the same quiet-failure pattern we've described with version drift elsewhere in Stripe's API and with reattempt-cap violations that show up as a line item on a processor statement nobody's dunning dashboard tracks. Nothing breaks loudly. The cost sits in authorization rates and network goodwill you can't easily attribute to a specific missing field, which is exactly why a field like this is easy to under-adopt even once it exists.
Sources: Datos Insights (formerly Aite-Novarica Group); SEON, citing a Merchant Risk Council survey; Fiserv Carat. None of these isolate the share caused specifically by stored-credential misclassification — no network publishes that breakdown — but every estimate puts real money on the table before you even get to this one specific field.
These three estimates don't agree with each other, and we're showing you that disagreement on purpose rather than picking the most dramatic number and presenting it as settled fact. What they agree on is direction: a meaningful share of declines on correctly-held, non-fraudulent cards are coming from somewhere in the authorization pipeline, and transaction classification is one of the few inputs to that pipeline a merchant actually controls end to end, rather than being at the mercy of an issuer's own risk model.
What to actually do about it
This isn't a migration project. It's a mapping exercise against billing logic you've already built.
- Classify your own off-session charge types first. Walk through every place your code charges a saved card without the customer present, and sort each into recurring, installment, or unscheduled before writing a single line against the new fields. Most SaaS businesses will find almost everything is
recurring, with usage-based top-ups as the mainunscheduledexception. - Set
setup_credential_usageat the point you actually know the answer. If a customer is signing up for a monthly plan, you know it'srecurringthe moment you create the SetupIntent — there's no reason to leave it unset and hope the charge-time field cleans it up later. - Don't confuse this with a card-freshness fix. If you're also worried about Mastercard's Credential Continuity exposure, that's a separate check against whether you're consuming updated card data from Stripe's account updater, not something this field resolves on its own.
- Test against the preview version in sandbox before touching production. A preview API version can still change shape, and Stripe's own upgrade guidance treats it as such — this is a case where being an early adopter buys you cleaner network signaling, not a case where you need to rush a production cutover this week.
None of this touches the cancellation side of your funnel — a subscriber who wants out still needs a clean path to leave, and that's a different problem than how a card network interprets a renewal charge. But it sits squarely in the same involuntary-churn category we've covered in our broader Stripe dunning guide: revenue you lose not because a customer chose to leave, but because something in the payment pipeline between "they want to stay" and "the charge succeeded" wasn't quite right. If you're trying to figure out how much of your own failed-renewal volume might be sitting in authorization friction rather than genuine card failure, run your numbers through our churn calculator — and if what you find is subscribers who are failing to pay because they've actually decided to leave, that's exactly the signal a well-built CancelFlow cancellation flow is designed to catch on its way out, instead of silently through a repeated failed charge.
Frequently asked questions
What is Stripe's setup_credential_usage field?+
It's a new parameter under payment_method_options.card, added on the 2026-09-30.preview API version, that you set on a SetupIntent or on a PaymentIntent using setup_future_usage. It declares how you intend to use a customer's saved card going forward, with three possible values: recurring, for off-session charges on a regular schedule; installment, for a fixed payment plan you manage yourself; and unscheduled, for off-session charges with no fixed schedule, like a usage-based top-up.
What's the difference between setup_credential_usage and stored_credential_usage?+
setup_credential_usage is set when you save the card — at setup time, before you know exactly when you'll charge it again. stored_credential_usage is set later, on the specific off-session PaymentIntent that actually charges the saved card, and it also appears on the resulting Charge object under payment_method_details.card. Both use the same three values, but one describes intent at save time and the other describes the actual transaction.
Is this the same thing as setup_future_usage?+
No, and that's the gap it closes. setup_future_usage only takes on_session or off_session — it tells Stripe whether the customer will be present for future charges, which Stripe needs for things like SCA. It says nothing about why you're charging the card again. setup_credential_usage and stored_credential_usage sit alongside it and answer the question setup_future_usage was never built to answer: is this a subscription renewal, an installment payment, or an irregular top-up.
Do I need to adopt this now if it's only on a preview API version?+
Not urgently, but it's worth testing in sandbox. A preview API version can still change before it's folded into a stable release, so Stripe's own guidance is to treat it as subject to revision. The underlying card network requirement it maps to isn't new or preview — Visa's stored credential framework has applied since 2017 regardless of what field Stripe exposes for it — so the usage type your transactions actually have hasn't changed. What's changed is whether you now have a native way to tell Stripe, and through Stripe the card networks, what that type is.
Stop losing subscribers today
One script tag. One function call. A live cancellation flow in under 10 minutes.
Start free trial →