Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 38 ยท Checkout and Payment Intents

Customers, SetupIntents and Saved Payment Methods

Save cards for later with Stripe Customer objects and SetupIntents. Learn on-session and off-session use, default payment methods, listing and detaching cards and mapping Stripe customers to your users.

One-time guests are easy: they pay, you never see them again. Real businesses want returning customers to pay in one click, subscriptions to renew automatically, and support staff to see a customer's history in one place. Stripe's answer is the Customer object plus PaymentMethods attached to it.

The Customer object

A Customer (cus_...) holds an email, name, address, tax details, a default payment method, and a list of everything they bought. Create one the first time a user needs to pay, and store the ID on your own user record.

JavaScript
// Real Stripe usage (read-only).
const customer = await stripe.customers.create({
  email: user.email,
  name: user.name,
  metadata: { user_id: String(user.id) },   // link back to your database
});

await db.users.update(user.id, { stripeCustomerId: customer.id });

Two rules keep this tidy. First, create the customer once per user and look it up later by the stored ID; creating a new customer on every payment scatters history and breaks subscriptions. Second, store the link in both directions (your stripeCustomerId, Stripe's metadata.user_id) so you can always find one from the other.

Saving a card: SetupIntent

To save a payment method without charging, use a SetupIntent (seti_...). It works like a PaymentIntent but collects and validates the method (including any 3D Secure) instead of an amount. The result is a pm_... attached to the customer, authenticated so it can later be charged off-session when the customer is not present.

JavaScript
// Real Stripe usage (read-only).
const setupIntent = await stripe.setupIntents.create({
  customer: customer.id,
  usage: "off_session",                  // we will charge them without them present
  automatic_payment_methods: { enabled: true },
});
// Send setupIntent.client_secret to the browser; mount the Payment Element with it,
// then call stripe.confirmSetup(...) instead of confirmPayment.

If you want to save a card while charging the customer, add setup_future_usage: "off_session" (or "on_session") to the PaymentIntent. Checkout does the same with payment_intent_data.setup_future_usage, or, for subscriptions, saves the method automatically.

Saving a card

Customer cus_ per user
SetupIntent Collect, no charge
PaymentMethod pm_ attached
1 / 2

On-session versus off-session

  • On-session payments happen while the customer is on your site and can respond to 3D Secure. A "pay with saved card" button is on-session: you create a PaymentIntent with customer and payment_method and confirm it in the browser.
  • Off-session payments happen without them: subscription renewals, usage bills, a "top up when balance is low" feature. You create the PaymentIntent with off_session: true and confirm: true. If the bank demands authentication anyway, the call fails with authentication_required and you must email the customer to come back.
JavaScript
// Real Stripe usage (read-only).
try {
  await stripe.paymentIntents.create({
    amount: 1500,
    currency: "usd",
    customer: customer.id,
    payment_method: savedPaymentMethodId,
    off_session: true,
    confirm: true,
  });
} catch (err) {
  if (err.code === "authentication_required") {
    // notify the customer to complete authentication on-session
  }
}

Managing saved methods

You can list a customer's methods, set a default, and detach one:

JavaScript
// Real Stripe usage (read-only).
const methods = await stripe.paymentMethods.list({ customer: customer.id, type: "card" });

await stripe.customers.update(customer.id, {
  invoice_settings: { default_payment_method: methods.data[0].id },
});

await stripe.paymentMethods.detach(methods.data[0].id);

When you show saved cards to the customer, display brand, last4 and exp_month/exp_year only. Card data you may store is covered in PCI DSS and Card Data Safety.

Stand-in: a customer vault

Here is the bookkeeping in plain JavaScript: customers, attached methods, a default, and an off-session charge that picks the default. It is a stand-in, not Stripe.

Node.js Customers and saved methods (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Billing details and tax data

A customer can also hold a billing address, a shipping address, a phone number, a tax ID (VAT, GST) and a preferred locale for emails. Collecting the address at checkout matters for tax calculation (see the billing lessons) and for fraud checks: address and postal-code verification results come back on the card check.

Deleting a customer and privacy laws

Privacy rules such as the GDPR give people rights over their data. Deleting a customer in Stripe (stripe.customers.del) removes their saved payment methods and cancels subscriptions, but Stripe may keep records it legally must. Decide in advance how your "delete my account" feature maps to Stripe: typically cancel subscriptions, detach cards, delete the customer, and keep only the invoices your accountants need.

Guests: do you need a customer?

Not always. For one-time, no-account purchases Checkout can create a customer for you (customer_creation: "always") or leave the payment customer-less. Subscriptions and saved cards always need one.

Next: a lesson on a subject that protects you from double charges: Idempotency and Safe Retries.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When do you use a SetupIntent?

    SetupIntents collect and authenticate a method for future use.
  2. 2. A subscription renewal charge runs at 3 a.m. Which kind of payment is it?

    The customer is not present, so it is off-session.
  3. 3. Why create a Stripe customer once per user?

    Duplicates scatter payment history and complicate subscriptions.
  4. 4. What card details are typically safe to display to a returning customer?

    Brand, last4 and expiry identify a card without exposing it.

Summary

  • Create one Customer per user and store the cus_ ID.
  • Use SetupIntents (or setup_future_usage) to save methods for later.
  • On-session payments allow challenges; off-session ones rely on earlier authentication and may fail with authentication_required.
  • List, set default and detach methods via the API; display only brand, last4 and expiry.
  • Plan how account deletion maps to Stripe data.

Next: Idempotency and Safe Retries