Stripe SetupIntent

Why `succeeded` here does not mean you were paid

A SetupIntent runs through a status ladder that looks almost identical to the one on a PaymentIntent, which is exactly why it trips people up. Stripe documents six values: `requires_payment_method`, `requires_confirmation`, `requires_action`, `processing`, `canceled`, and `succeeded`.

On a PaymentIntent, `succeeded` means the money was collected. On a SetupIntent, `succeeded` means the payment method is set up and ready to be charged at some point in the future. The same word describes two very different outcomes, and only one of them is a sale.

This matters most when someone is scanning a list rather than reading an object. A row that says `succeeded` next to a customer name and a card brand reads like a completed purchase. If the underlying object is a SetupIntent, no money moved, and there is nothing to reconcile against your bank.

The cancellation reasons are a useful tell in the other direction. Stripe records `abandoned`, `requested_by_customer`, or `duplicate` on a canceled SetupIntent. None of those is a failed payment, because there was no payment to fail. A customer who abandons a card-saving flow has not had anything declined.

Where you meet one without meaning to

Most people never call the Setup Intents API directly. They meet SetupIntents through other Stripe features that create them quietly.

The common one is Checkout. A Checkout Session has a `mode`, and Stripe defines the `setup` value as "save payment details to charge your customers later". A session in that mode produces a SetupIntent rather than a PaymentIntent, and stores its id in the session’s `setup_intent` field. The session’s `payment_status` then reads `no_payment_required`, which Stripe defines as covering the case where "the Checkout Session is in `setup` mode and doesn’t require a payment at this time".

So a `setup` mode Checkout Session is a hosted page that takes card details and charges nothing. It completes successfully, it produces a real object, and your bank account is untouched.

Stripe’s own examples of when to use this are worth repeating, because they describe ordinary businesses rather than edge cases: a car rental company that collects card details before the rental and charges after it ends, a crowdfunding site that saves cards and only charges them if the campaign hits its target, and a utility company that collects bank details up front and charges a different amount each month.

Every one of those has a gap between collecting the payment method and taking the money. The SetupIntent is what lives in that gap.

The charge that comes later is an ordinary charge

The `usage` field is where the SetupIntent records what you plan to do next. Stripe documents two values. `on_session` means you only intend to reuse the payment method while the customer is in your checkout flow and able to authenticate. `off_session` means the customer may or may not be present, and it is the default when you do not specify.

Off-session use is the interesting case for bookkeeping, because it is the one where a charge appears with no customer action behind it. Stripe is direct about the obligation that comes with it: charging someone when they are not actively using your site requires permission, set up as an agreement or mandate that covers the customer’s consent, the expected frequency, and how the amount will be determined.

When that later payment finally runs, it is not special. It creates a PaymentIntent and a charge like any other sale, and it produces a [balance transaction](/glossary/stripe-balance-transaction) carrying the gross amount, the [fee](/glossary/stripe-fee), and the net. Your books see that charge and record it normally.

So the full arc for a saved-card business is two events separated by time: a SetupIntent that creates nothing in your accounting, then a charge weeks or months later that creates everything. Reconciling the second one has nothing to do with the first.