Save payment details during payment

Learn how to accept a payment and save your customer's payment details for future purchases.

Use Stripe Checkout to embed a prebuilt payment form on your website that allows your customers to save their payment details for future purchases.

Set up Stripe
Server-side

First, register for a Stripe account.

Use our official libraries to access the Stripe API from your application:

Create a customer
Server-side

To set a card up for future payments, you must attach it to a Customer. Create a Customer object when your customer creates an account with your business. Customer objects allow for reusing payment methods and tracking across multiple payments.

Successful creation returns the Customer object. You can inspect the object for the customer id and store the value in your database for later retrieval.

You can find these customers in the Customers page in the Dashboard.

Create a Checkout Session
Server-side

From your server, create a Checkout Session and set the ui_mode to embedded. You can configure the Checkout Session with line items to include and options such as currency.

You can also create a Checkout Session for an existing customer, allowing you to pre-fill Checkout fields with known contact information and unify your purchase history for that customer.

To return customers to a custom page that you host on your website, specify that page’s URL in the return_url parameter. Include the {CHECKOUT_SESSION_ID} template variable in the URL to retrieve the session’s status on the return page. Checkout automatically substitutes the variable with the Checkout Session ID before redirecting.

Read more about configuring the return page and other options for customising redirect behaviour.

After you create the Checkout Session, use the client_secret returned in the response to mount Checkout.

Mount Checkout
Client-side
Server-side

Checkout is available as part of Stripe.js. Include the Stripe.js script on your page by adding it to the head of your HTML file. Next, create an empty DOM node (container) to use for mounting.

index.html
<head>
  <script src="https://js.stripe.com/v3/"></script>
</head>
<body>
  <div id="checkout">
    <!-- Checkout will insert the payment form here -->
  </div>
</body>

Initialise Stripe.js with your publishable API key.

Create an asynchronous fetchClientSecret function that makes a request to your server to create the Checkout Session and retrieve the client secret. Pass this function into options when you create the Checkout instance:

index.js
// Initialize Stripe.js
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

initialize();

// Fetch Checkout Session and retrieve the client secret
async function initialize() {
  const fetchClientSecret = async () => {
    const response = await fetch("/create-checkout-session", {
      method: "POST",
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  };

  // Initialize Checkout
  const checkout = await stripe.initEmbeddedCheckout({
    fetchClientSecret,
  });

  // Mount Checkout
  checkout.mount('#checkout');
}

Checkout renders in an iframe that securely sends payment information to Stripe over an HTTPS connection.

Common mistake

Avoid placing Checkout within another iframe because some payment methods require redirecting to another page for payment confirmation.

Save payment method
Server-side

After setting up your embedded Checkout integration, choose a configuration for your integration to save the payment methods used by your customers.

By default, payment methods used to make a one-off payment with Checkout aren’t available for future use.

Save payment methods to charge them off-session

You can set Checkout to save payment methods used to make a one-off payment by passing the payment_intent_data.setup_future_usage argument. This is useful if you need to capture a payment method on-file to use for future fees, such as cancellation or no-show fees.

If you use Checkout in subscription mode, Stripe automatically saves the payment method to charge it for subsequent payments. Card payment methods saved to customers using either setup_future_usage or subscription mode don’t appear for return purchases in Checkout (more on this below). We recommend using custom text to link out to any relevant terms regarding the usage of saved payment information.

Caution

Global privacy laws are complicated and nuanced. We recommend contacting your legal and privacy team prior to implementing setup_future_usage because it might implicate your existing privacy compliance framework. Refer to the guidance issued by the European Protection Board to learn more about saving payment details.

Save payment methods to prefill them in Checkout

By default, Checkout uses Link to provide your customers with the option to securely save and reuse their payment information. If you prefer to manage payment methods yourself, use saved_payment_method_options.payment_method_save when creating a Checkout Session to let your customers save their payment methods for future purchases in Checkout.

Passing this parameter in either payment or subscription mode displays an optional tickbox to let customers explicitly save their payment method for future purchases. When customers tick this tickbox, Checkout saves the payment method with allow_redisplay: always. Checkout uses this parameter to determine whether a payment method can be pre-filled on future purchases. When using saved_payment_method_options.payment_method_save, you don’t need to pass in setup_future_usage to save the payment method.

Using saved_payment_method_options.payment_method_save requires a Customer. To save a new customer, set the Checkout Session’s customer_creation to always. Otherwise, the session doesn’t save the customer or the payment method.

If payment_method_save isn’t passed in or if the customer doesn’t agree to save the payment method, Checkout still saves payment methods created in subscription mode or using setup_future_usage. These payment methods have an allow_redisplay value of limited, which prevents them from being pre-filled for returning purchases and allows you to comply with card network rules and data protection regulations. Learn how to change the default behaviour enabled by these modes and how to change or override allow_redisplay behaviour.

Note

You can use Checkout to save cards and other payment methods to charge them off-session, but Checkout only pre-fills saved cards. Learn how to pre-fill saved cards. To save a payment method without an initial payment, use Checkout in setup mode.