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 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. Before saving or charging a customer’s payment mathod, make sure you:
- Add terms to your website or app that state how you plan to save payment method details, such as:
- The customer’s agreement allowing you to initiate 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.
- Use a saved payment method for only the purpose stated in your terms.
- Collect explicit consent from the customer for this specific use. For example, include a "Save my payment method for future checkbox.
- Keep a record of your customer’s written agreement to your terms.
Caution
SCA regulation requires that you authenticate your customer up front if you intend to collect payments from them again in the future. The cardholder’s bank might decline future payments and ask for additional authentication if the customer never authenticated initially.
Note
When using Elements with the Checkout Sessions API, only cards and ACH Direct Debit are supported for saved payment methods. You can’t save other payment methods, such as bank accounts.
Prerequisites
- Follow the Checkout guide to accept a payment.
- Follow this guide to save the payment method used during a payment so you can retrieve it for use in future payments by the same customer.
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.
Use the Accounts v2 API to represent customers
The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a specify a preview version in your code.
To request access to the Accounts v2 preview, sign up.
For most use cases, we recommend modeling your customers as customer-configured Account objects instead of using Customer objects.
Saving a payment method requires an object that represents your customer. This object can be a customer-configured Account if you use the Accounts v2 API, or a Customer if you use the Customers API. Pass an existing customer or create a new one by setting customer_creation to always on the Checkout Session.
curl https://api.stripe.com/v1/checkout/sessions \ -u ":" \ -d "line_items[0][price]=sk_test_Gx4mWEgHtCMr4DYMUIqfIrsz" \ -d "line_items[0][quantity]=2" \ -d mode=payment \ -d ui_mode=elements \ -d customer_creation=always \ -d "saved_payment_method_options[payment_method_save]=enabled"{{PRICE_ID}}
After you create the Checkout Session, use the client secret returned in the response to build your checkout page.
Note
In the latest version of Stripe.js, specifying enableSave to auto is optional because that’s the default value when saved payment methods are enabled on the Checkout Session.
The Payment Element automatically displays a consent collection checkbox when saved payment methods are enabled on the Checkout Session. You can explicitly configure this behavior using elementsOptions on initCheckoutElementsSdk.
const checkout = stripe.initCheckoutElementsSdk({ clientSecret, elementsOptions: { savedPaymentMethod: { // Default is 'auto' in the latest version of Stripe.js - this configuration is optional enableSave: 'auto', } } });
Reuse a previously saved payment method
Each saved payment method is linked to an object that represents your customer. This object can be a customer-configured Account if you use the Accounts v2 API, or a Customer if you use the Customers API. Before creating the Checkout Session, authenticate your customer, and pass the corresponding object ID to the Checkout Session.
Note
In the latest version of Stripe.js, enableRedisplay defaults to auto when saved payment methods are enabled on the Checkout Session.
The Payment Element automatically redisplays previously saved payment methods for your customer to use during checkout when saved payment methods are enabled on the Checkout Session.
curl https://api.stripe.com/v1/checkout/sessions \ -u ":" \ -d "line_items[0][price]=sk_test_Gx4mWEgHtCMr4DYMUIqfIrsz" \ -d "line_items[0][quantity]=2" \ -d mode=payment \ -d ui_mode=elements \ -d "customer_account={{PRICE_ID}}"{{CUSTOMER_ACCOUNT_ID}}
You can explicitly configure the redisplay behavior using elementsOptions on initCheckoutElementsSdk.
const checkout = stripe.initCheckoutElementsSdk({ clientSecret, elementsOptions: { savedPaymentMethod: { // Default is 'auto' in the latest version of Stripe.js - this configuration is optional enableSave: 'auto', // Default is 'auto' in the latest version of Stripe.js - this configuration is optional enableRedisplay: 'auto', } } });