Stripe Invoice Payment Settings

The list is resolved before the invoice is finalized, not when the customer pays

Payment settings configures an object that does not exist yet. Stripe creates the PaymentIntent at finalization, and the settings on the invoice at that moment are the ones that shape it.

That timing explains a class of failure that otherwise looks arbitrary. Stripe documents two ways payment method errors stop an invoice cold: "Stripe attempts to automatically select payment methods, but all of the payment methods have restrictions that prevent them from being used (this often happens when only one or two payment methods are enabled)", and "You manually select a payment method but a restriction prevents it from being used."

Restrictions are not exotic. Stripe notes that "a payment method might only operate in one currency or have limitations on the amount that can be paid. If there’s a limitation on a payment method, Stripe won’t automatically select it for you." ACH Direct Debit is USD and United States only. Bacs is GBP. BECS is AUD. An invoice raised in the wrong currency against a narrow method list has nothing valid left to offer.

When that happens the invoice does not become overdue. It never finalizes. Stripe "sends an invoice.finalization_failed webhook to notify you of the problem", records the detail in `last_finalization_error`, and the fix is to "change the payment_settings for the invoice so that it has at least one valid payment method." For your books that is the useful distinction: an invoice stuck here was never issued, so there is no receivable to chase and nothing to reconcile. There is a configuration bug.

The default payment method trap

This is the sharpest edge on the field, and it catches people who set the list deliberately.

Stripe’s instruction is explicit: "If you configured a default payment method on either the customer (as a customer-configured Account object or a Customer object) or the Subscription object associated with the invoice, be sure to include it in the list of payment_method_types. Otherwise, the payment will fail."

The two settings live in different places and are edited by different people. Someone narrows an invoice or a subscription to cards only, for a good reason. The customer’s saved default is a bank account. Nothing warns anyone, and the payment fails on an invoice that looks correctly configured.

The symptom in your books is a failed collection with no customer-side cause: no decline code worth acting on, no expired card, no insufficient funds. Before chasing the customer, check whether the method they have on file is still on the list the invoice offers.

Not every method can be offered on every invoice

The list is not freely composable, and the constraint is tied to how the invoice collects.

Stripe supports a long tail of methods for Invoicing, but a group of them work only with the `send_invoice` collection method, where Stripe emails the customer payment instructions rather than charging a stored method automatically. That group includes Klarna, Affirm, Afterpay and Clearpay, bank transfer, Konbini, Multibanco, PayNow, PromptPay, MB WAY and crypto. Several of them carry a second restriction: Stripe states you "can only add this payment method to individual invoices", which rules them out of a template-level default.

The practical reading is that offering buy now, pay later or a bank transfer on a subscription invoice that charges automatically is not a setting anyone forgot to switch on. It is a combination Stripe does not support, and the collection method has to change first. Whether the invoice charges automatically or asks the customer to pay is the collection method, and [automatic collection](/blog/stripe-automatic-collection-quickbooks) covers the `auto_advance` behaviour behind it.

The methods that do work under automatic charging are the ones with a stored, reusable authorization behind them: cards, wallets, and the direct debits. That authorization is a [mandate](/glossary/stripe-mandate), and `default_mandate` on payment settings is where an invoice names the one to use.

Why a configuration field ends up in your reconciliation

Two invoices for the same amount, issued the same day, can reach your bank in different weeks and net different money. The difference is the method, and the method was decided here.

Bank debits are the case that changes the shape of the books rather than the size of a number. A card answers immediately. An ACH debit is a request that gets answered days later, which means the payment can appear to succeed and then fail well after the invoice was marked paid and, quite possibly, after the period was closed. That is the whole subject of [failed ACH payments in QuickBooks](/blog/stripe-failed-ach-payment-quickbooks), and it starts with a payment method list that included `us_bank_account`.

Buy now, pay later runs the opposite way and surprises people who expect installments. The provider pays you up front and carries the instalment plan itself, so your books see one payment at a different fee. [Klarna and Afterpay in QuickBooks](/blog/klarna-afterpay-quickbooks) covers what that does to margin reporting.

None of this is visible on the invoice total. If your gross-to-net gap changes shape and your revenue did not, the payment method mix is worth checking before the sync is.

Where the setting actually lives

Three layers resolve into the list a customer sees, and knowing which one you are editing saves a lot of confusion.

The account default is the Invoice template, in the Dashboard under Settings, Billing, Invoice. This is what applies when payment settings on the invoice is null, which is the normal case.

The invoice override is `payment_settings.payment_method_types`, set through the API on the individual invoice. Stripe’s own example sets it to card plus customer_balance in a single call.

Per-method behaviour is `payment_method_options`, which Stripe describes as existing because "Some payment methods have additional options that you can set to customize the payment experience."

Platforms have a fourth layer. Under Connect, the platform can set a payment method configuration for connected accounts from Settings, Billing, Invoice, and Stripe notes that "Your connected accounts still have the ability to enable and disable individual payment methods after you enable the default configuration." A platform default is a starting point, not a lock.