Glossary

Stripe Default Payment Method

A Stripe default payment method is the saved card or bank account Stripe charges for an automatically collected invoice, picked from up to four settings in a fixed order: the invoice’s own default, the subscription’s, the customer’s invoice_settings default, and the legacy customer default_source.

Also called: default_payment_method, invoice_settings.default_payment_method, default_source, subscription default payment method

14-day free trial · card required · cancel anytime

Definition

In Stripe, “the default payment method” is not one field. It is a lookup. When an invoice is set to charge automatically, Stripe checks several places a payment method can be stored and uses the first one it finds. Stripe’s subscription invoice guide says it directly: “When trying to collect payment on an invoice, Stripe uses the first available payment method in this list, in this order.”

The list has four levels. First the invoice’s own default_payment_method. Then the subscription’s default_payment_method. Then the customer’s invoice_settings.default_payment_method. Last, the legacy default_source on the customer. A subscription also carries its own legacy default_source, and Stripe’s API reference says the subscription’s default_payment_method “takes precedence over default_source.”

The consequence catches people out. A customer can have exactly the right card saved as their default and still be charged on a different one, because a more specific setting higher up the list wins. Most “we updated the card and the renewal still failed” tickets come down to this order.

Key points

  • +Order for an invoice: the invoice default, then the subscription default, then the customer’s invoice_settings default, then the legacy customer default_source.
  • +On a subscription, default_payment_method takes precedence over the subscription’s own default_source.
  • +A subscription default overrides the customer default for every future invoice of that subscription.
  • +The customer default lives under invoice_settings, not as a top-level field on the customer.
  • +save_default_payment_method=on_subscription stores the card from a successful payment as the subscription default. Stripe says it defaults to off.
  • +The customer portal’s payment method update flow sets the customer default, not a subscription default.
  • +A Dashboard payment update link changes only its own subscription and can’t change the customer default.
  • +If a subscription restricts payment_method_types, the default’s type must be on the list or it can’t pay that subscription’s invoices.

The four places Stripe looks, in order

Stripe’s collection order, from its guide to how subscriptions work with invoices, runs from the most specific setting to the most general.

First, the invoice default payment method, on the invoice object. It applies to that one invoice only, which makes it the tool for charging a single invoice to a different card without touching anything else.

Second, the subscription default payment method. Stripe’s API reference describes it as the “ID of the default payment method for the subscription,” adds that “It must belong to the customer associated with the subscription,” and says it takes precedence over the subscription’s default_source.

Third, the customer default payment method, stored as invoice_settings.default_payment_method on the customer. This is the one most people mean when they say “the card on file.”

Fourth, the legacy customer default_source, from Stripe’s older Sources and Cards APIs. Stripe’s customer reference points newer integrations away from it: “If you use payment methods created through the PaymentMethods API, see the invoice_settings.default_payment_method field instead.”

The subscription reference spells out the fall-through in its own words. If neither the subscription’s default_payment_method nor its default_source is set, “invoices will use the customer’s invoice_settings.default_payment_method or default_source.”

Why a card update doesn’t reach every subscription

Take a customer with two subscriptions. The first was created with payment_settings.save_default_payment_method set to on_subscription, so its first successful payment saved the card ending 4242 as that subscription’s own default. The second subscription has no default of its own and falls through to the customer.

The 4242 card expires. The customer opens your billing portal and adds a new card ending 1881. Stripe’s portal deep-link reference says the payment method update flow saves it as customer.invoice_settings.default_payment_method. The second subscription renews on 1881 without anyone noticing. The first subscription still has 4242 at level two of the list, which beats the customer default at level three, so its renewal tries the expired card and fails.

Nothing is broken. The setting that would have made the first subscription follow the customer was never there. The fix is to remove the subscription-level default so it falls through to the customer again, or to set it to the new card. Stripe’s portal integration guide notes that “If you have subscriptions that override the customer-level default payment method, customers can remove this override,” and tells you to check the subscription’s default_payment_method on customer.updated to see whether they did.

How each Stripe flow sets it

Which level a payment method lands on depends on the tool that saved it, and the tools don’t agree.

Subscription payments. Stripe says setting payment_settings.save_default_payment_method to on_subscription saves “the payment method from a successful subscription payment as subscription.default_payment_method,” and that “The setting defaults to off.” Integrations that copied Stripe’s examples often have it on, which is how subscription-level defaults pile up without anyone choosing them.

Customer portal. Stripe describes the payment_method_update flow as the way “to let your customer add a new payment method,” and says “The payment method is set as the customer.invoice_settings.default_payment_method.” Customer level only.

Dashboard payment update links. Stripe’s single-use links work the other way: “A link can only update the payment method on the associated subscription, and can’t change the customer’s default payment method.” The new method must be a card, the subscription must be active, past_due or trialing, each link works once, and an unused link expires after 30 days.

Your own code. After collecting a card with a setup-mode Checkout Session, Stripe’s guide shows both options. On the customer: “All future invoices for this customer will now charge the new PaymentMethod.” On the subscription: it “will cause all future invoices for that subscription to be paid with the specified payment method, overriding any invoice_settings.default_payment_method set on the associated Customer.”

Checking which card a renewal will actually use

When a renewal charges the wrong card, or fails on a card the customer swears they replaced, walk the list in Stripe’s order and stop at the first value that isn’t empty. On the invoice, look at default_payment_method: it is usually empty, but an override set on one invoice wins over everything. On the subscription, look at default_payment_method, then default_source. On the customer, look at invoice_settings.default_payment_method, then default_source.

One more setting can block the payment method you found. A subscription can restrict payment_settings.payment_method_types. Stripe warns that if a subscription uses a default payment method, you should include that method’s type in the list: “Otherwise, the default payment method can’t be used to pay the subscription’s invoices.” A bank account default on a subscription limited to cards is the classic case.

This order covers automatic collection. An invoice sent with collection_method=send_invoice is paid by the customer on the hosted invoice page, where they choose from the eligible payment method types.

What the default payment method changes in QuickBooks

Less than you might expect, and that is the useful part. With Invoice Sync on, Acodei keys on the invoice, not on the card. When a Stripe invoice is finalized, Acodei creates a QuickBooks invoice that reproduces its line items and tax lines as your mapping settings allow. When the invoice is paid, by a successful charge, by a manual payment per your settings, or by a credit balance offset, Acodei creates a payment receipt or credit memo and applies it to that QuickBooks invoice. That automatic application needs QuickBooks Automatic Application switched on.

So the default payment method decides whether and when a Stripe invoice gets paid. It doesn’t change what the QuickBooks invoice says. If a renewal keeps trying an expired card because a subscription default overrides the customer’s new one, fix the order in Stripe. The QuickBooks payment follows once Stripe marks the invoice paid.

Want to see this on your own Stripe data?

Start a free trial

14-day free trial · card required · cancel anytime

Frequently asked questions

What is the default payment method in Stripe?

It is the saved payment method Stripe charges for an automatically collected invoice. Stripe picks it from four settings in order: the invoice’s default_payment_method, the subscription’s default_payment_method, the customer’s invoice_settings.default_payment_method, and finally the legacy customer default_source. The first one that is set wins.

Why did Stripe charge an old card after the customer updated it?

Most often because the subscription has its own default_payment_method. A subscription default overrides the customer default for every invoice of that subscription, so a new card saved on the customer never reaches it. Remove the subscription-level default so it falls back to the customer, or set it to the new card.

Does updating a card in the Stripe customer portal update every subscription?

Only the subscriptions without a default of their own. Stripe’s payment method update flow saves the new method as the customer’s invoice_settings.default_payment_method. Subscriptions that fall through to the customer pick it up. A subscription with its own default_payment_method keeps charging that one unless the override is removed.

What is the difference between default_source and default_payment_method?

default_source belongs to Stripe’s older Sources and Cards APIs. default_payment_method belongs to the PaymentMethods API that current integrations use. Where both exist on a subscription, Stripe says default_payment_method takes precedence. On the customer, the modern field is invoice_settings.default_payment_method, and default_source is the last fallback.

Does the payment method Stripe charges change what syncs to QuickBooks?

Not the invoice itself. With Acodei’s Invoice Sync, the QuickBooks invoice is created when the Stripe invoice is finalized, and the payment is recorded and applied when the invoice is paid. The default payment method affects whether the charge succeeds and when, which decides when that payment appears.

What customers say about running Stripe through Acodei

Stripe Verified Partner BadgeIntuit QuickBooks
★★★★★
“If you're testing out all the different Stripe/QuickBooks integration apps right now, let me save you some time. This one is the best one by far.”
RyanOwner at Indie Music Academy
★★★★★
“Works well and is really helpful for massive transactions. The support is really fast and helpful. 100% recommended.”
AndresCo-founder and CEO at Kanguro Collections and Reinsurance

Related reading

More glossary terms

See the full glossary

Ready to try Acodei?

Connect Stripe to QuickBooks Online in minutes and let the fees, refunds, and payouts land where your accountant expects them.

14-day free trial · card required · cancel anytime