Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in
OverviewAccept a paymentUpgrade your integration
Online payments
OverviewFind your use case Use Managed PaymentsRecurring payments
In-person payments
Payment methods
Payment operations
Balances and settlement time ReceiptsRefunds and cancellations
Advanced integrations
Beyond payments

Save a customer's payment method without making a payment

Learn how to save a payment method and charge it later.

The Checkout Sessions API in setup mode lets you save a customer’s payment details without an initial payment. This is helpful if you want to onboard customers now, set them up for payments, and charge them using the Payment Intents API in the future—when they’re offline.

Use this integration to set up recurring payments or to create one-time payments with a final amount determined later, often after the customer receives your service.

Card-present transactions

Card-present transactions, such as collecting card details through Stripe Terminal, use a different process for saving the payment method.

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

If you need to use manual server-side confirmation or your integration requires presenting payment methods separately, see our alternative guide.

Set up Stripe
Server-side

First, create a Stripe account or sign in.

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 up a payment method 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.

Compare Customers v1 and Accounts v2 references

If your Connect platform uses customer-configured Accounts, use our guide to replace Customer and event references in your code with the equivalent Accounts v2 API references.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results

curl -X POST https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Use setup mode
Server-side

Create a Checkout Session with mode=setup.

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 mode=setup \
  -d ui_mode=custom \
  -d currency=usd

Attach the payment method to a Customer
Server-side

If you didn’t create the Checkout Session with an existing customer, use the ID of the PaymentMethod to attach the payment method to a customer.

Otherwise, the payment method automatically attaches to the customer you provided when creating the Checkout Session.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results

curl https://api.stripe.com/v1/payment_methods/
{{PAYMENT_METHOD_ID}}
/attach \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
"{{CUSTOMER_ID}}"

Retrieve the payment method
Server-side

After a customer successfully completes their Checkout Session, handle the checkout.session.completed webhook. Retrieve the Session object in the webhook, and then do the following:

  • Get the value of the setup_intent key, which is the SetupIntent ID created during the Checkout Session.
  • Use the SetupIntent ID to retrieve the SetupIntent object. The returned object contains a payment_method ID that you can attach to a customer in the next step.

Learn more about setting up webhooks.

Charge the payment method later
Server-side

After you attach the PaymentMethod to a customer, you can make an off-session payment using a PaymentIntent:

  • Set customer to the customer ID and payment_method to payment method ID.
  • Set off_session to true to indicate that the customer isn’t in your checkout flow during a payment attempt and can’t fulfill an authentication request made by a partner, such as a card issuer, bank, or other payment institution. If, during your checkout flow, a partner requests authentication, Stripe requests exemptions using customer information from a previous on-session transaction. If the conditions for exemption aren’t met, the PaymentIntent might result in an error.
  • Set the value of the PaymentIntent’s confirm property to true, which causes confirmation to occur immediately when you create the PaymentIntent.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d customer=
"{{CUSTOMER_ID}}"
 \
  -d payment_method=
"{{PAYMENT_METHOD_ID}}"
 \
  -d off_session=true \
  -d confirm=true

If a payment attempt fails, the request also fails with a 402 HTTP status code, and the PaymentIntent status is requires_payment_method. Notify your customer to return to your application (for example, by sending an email or in-app notification) and direct your customer to a new Checkout Session to select another payment method.

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 customer=
"{{CUSTOMER_ID}}"
 \
  -d "line_items[0][price_data][currency]"=usd \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][unit_amount]"=1099 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d ui_mode=custom \
  --data-urlencode return_url="https://example.com/return"
Proxying: stripe.com/docs/payments/save-and-reuse ✕