Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseUse Managed Payments
Use Payment Links
Use a prebuilt checkout page
Build a custom integration with Elements
    Overview
    Compare Checkout Sessions and PaymentIntents
    Quickstart guides
    Design an advanced integration
    Customize look and feel
    Manage payment methods
    Collect additional information
    Build a subscriptions integration
    Dynamic updates
    Add discounts
    Collect taxes on your payments
    Let customers pay in their local currency
    Save and retrieve customer payment methods
      Save the payment method used for a payment
      Save a payment method without making a payment
    Send receipts and paid invoices
    Manually approve payments on your server
    Authorize and capture a payment separately
    Elements with Checkout Sessions API beta changelog
Build an in-app integration
Payment methods
Add payment methods
Manage payment methods
Faster checkout with Link
Payment interfaces
Payment Links
Checkout
Web Elements
In-app Payments
Payment scenarios
Handle multiple currencies
Custom payment flows
Flexible acquiring
Orchestration
In-person payments
Terminal
Beyond payments
Incorporate your company
Crypto
Financial Connections
Climate
Understand fraud
Radar fraud protection
Manage disputes
Verify identities
HomePaymentsBuild a custom integration with ElementsSave and retrieve customer payment methods

Save a customer's payment method when they use it for a payment

Learn how to save your customer's payment details for future purchases when they make a payment.

Use the Checkout Sessions API to save payment details during a purchase. This is useful for situations such as:

  • Charging a customer for an e-commerce order and storing the payment details for future purchases.
  • Initiating the first payment in a series of recurring payments.
  • Charging a deposit and storing the payment details to charge the full amount later.

Compliance

You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. These requirements generally apply if you want to save your customer’s payment method for future use, such as displaying a customer’s payment method to them in the checkout flow for a future purchase or charging them when they’re not actively using your website or app. Add terms to your website or app that state how you plan to save payment method details and allow customers to opt in.

When you save a payment method, you can only use it for the specific usage you have included in your terms. To charge a payment method when a customer is offline and save it as an option for future purchases, make sure that you explicitly collect consent from the customer for this specific use. For example, include a “Save my payment method for future use” checkbox to collect consent.

To charge a customer when they’re offline, make sure your terms include the following:

  • The customer’s agreement to your initiating a payment or a series of payments on their behalf for specified transactions.
  • The anticipated timing and frequency of payments (for example, if the charges are for scheduled installments, subscription payments, or unscheduled top-ups).
  • How you determine the payment amount.
  • Your cancellation policy, if the payment method is for a subscription service.

Make sure you keep a record of your customer’s written agreement to these terms.

Note

When using Elements with the Checkout Sessions API, only cards are supported for saved payment methods. You can’t save other payment methods, such as bank accounts.

Set up Stripe
Server-side

First, register for a Stripe account.

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

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile gem 'stripe'

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d name="Jenny Rosen" \ --data-urlencode email="jennyrosen@example.com"

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.

Enable saved payment methods

Caution

Global privacy laws are complicated and nuanced. Before implementing the ability to store customer payment method details, work with your legal team to make sure that it complies with your privacy and compliance framework.

To allow a customer to save their payment method for future use, specify the saved_payment_method_options.payment_method_save parameter when creating the Checkout Session.

Saving a payment method requires a Customer. Pass an existing customer or create a new one by setting customer_creation to always on the Checkout Session.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "line_items[0][price]"=
{{PRICE_ID}}
\ -d "line_items[0][quantity]"=2 \ -d mode=payment \ -d ui_mode=custom \ -d customer_creation=always \ -d "saved_payment_method_options[payment_method_save]"=enabled

After you create the Checkout Session, use the client secret returned in the response to build your checkout page.

Pass in additional elementsOptions on initCheckout to enable the Payment Element to display a consent collection checkbox for you.

checkout.js
const checkout = await stripe.initCheckout({ fetchClientSecret, elementsOptions: { savedPaymentMethod: { enableSave: 'auto', } } });

Reuse a previously saved payment method

Each saved payment method is linked to a Customer object. Before creating the Checkout Session, authenticate your customer, and pass the corresponding Customer ID to the Checkout Session.

The Payment Element automatically redisplays previously saved payment methods for your customer to use during checkout.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "line_items[0][price]"=
{{PRICE_ID}}
\ -d "line_items[0][quantity]"=2 \ -d mode=payment \ -d ui_mode=custom \ -d customer=
{{CUSTOMER_ID}}

Pass in additional elementsOptions on initCheckout to enable the Payment Element to redisplay previously saved payment methods for your customer to use during checkout.

checkout.js
const checkout = await stripe.initCheckout({ fetchClientSecret, elementsOptions: { savedPaymentMethod: { enableSave: 'auto', enableRedisplay: 'auto', } } });

OptionalBuild a saved payment method UI

You can build your own saved payment method UI instead of using the built-in UI provided by the Payment Element.

To prevent the Payment Element from handling consent collection and displaying the previously saved payment methods, pass in additional elementsOptions on initCheckout.

checkout.js
const checkout = await stripe.initCheckout({ fetchClientSecret, elementsOptions: { savedPaymentMethod: { enableSave: 'never', enableRedisplay: 'never', } } });

Collect consent

Caution

Global privacy laws are complicated and nuanced. Before implementing the ability to store customer payment method details, work with your legal team to make sure that it complies with your privacy and compliance framework.

In most cases, you must collect a customer’s consent before you save their payment method details. The following example shows how to obtain consent using a checkbox.

index.html
<label> <input type="checkbox" id="save-payment-method-checkbox" /> Save my payment information for future purchases </label> <button id="pay-button">Pay</button> <div id="confirm-errors"></div>

When you call confirm, you can indicate to Stripe that your customer has provided consent by passing the savePaymentMethod parameter. When you save a customer’s payment details, you’re responsible for complying with all applicable laws, regulations, and network rules.

checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => { const button = document.getElementById('pay-button'); const errors = document.getElementById('confirm-errors'); const checkbox = document.getElementById('save-payment-method-checkbox'); button.addEventListener('click', () => { // Clear any validation errors errors.textContent = ''; const savePaymentMethod = checkbox.checked; checkout.confirm({savePaymentMethod}).then((result) => { if (result.type === 'error') { errors.textContent = result.error.message; } }); }); });

Render saved payment methods

Use the savedPaymentMethods array on the front end to render the customer’s available payment methods.

Note

The savedPaymentMethods array includes only the payment methods that have allow_redisplay set to always. Follow the steps for collecting consent from your customer and make sure to properly set the allow_redisplay parameter.

index.html
<div id="saved-payment-methods"></div>
checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => { const container = document.getElementById('saved-payment-methods'); checkout.session().savedPaymentMethods.forEach((pm) => { const label = document.createElement('label'); const radio = document.createElement('input'); radio.type = 'radio'; radio.value = pm.id; label.appendChild(radio); label.appendChild(document.createTextNode(`Card ending in ${pm.card.last4}`)); container.appendChild(label); }); });

Confirm with a saved payment method

When your customer selects a saved payment method and is ready to complete checkout, call confirm and pass in the paymentMethod ID.

index.html
<button id="pay-button">Pay</button>
checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => { const button = document.getElementById('pay-button'); button.addEventListener('click', () => { checkout.confirm({paymentMethod: selectedPaymentMethod}).then((result) => { if (result.error) { // Confirmation failed. Display the error message. } }); }); });
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc