Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseManaged Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Other Stripe products

Save payment details during payment

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

Copy page

Use Stripe Checkout for a fast, low-code integration 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:

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# 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 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.

Create a Checkout Session
Client-side
Server-side

Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.

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

checkout.html
<html>
  <head>
    <title>Buy cool new product</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>

A Checkout Session is the programmatic representation of what your customer sees when they’re redirected to the payment form. You can configure it with options such as:

You must populate success_url with the URL value of a page on your website that Checkout returns your customer to after they complete the payment. You can optionally also provide a cancel_url value of a page on your website that Checkout returns your customer to if they terminate the payment process before completion.

Note

Checkout Sessions expire 24 hours after creation by default.

After creating a Checkout Session, redirect your customer to the URL returned in the response.

# This example sets up an endpoint using the Sinatra framework.
# Watch this video to get started: https://youtu.be/8aA9Enb8NVc.

require 'json'
require 'sinatra'
require 'stripe'

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


post '/create-checkout-session' do
  session = Stripe::Checkout::Session.create({
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'T-shirt',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    mode: 'payment',
    # These placeholder URLs will be replaced in a following step.
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
  })

  redirect session.url, 303
end

Payment methods

By default, Stripe enables cards and other common payment methods. You can turn individual payment methods on or off in the Stripe Dashboard. In Checkout, Stripe evaluates the currency and any restrictions, then dynamically presents the supported payment methods to the customer.

To see how your payment methods appear to customers, enter a transaction ID or set an order amount and currency in the Dashboard.

You can enable Apple Pay and Google Pay in your payment methods settings. By default, Apple Pay is enabled and Google Pay is disabled. However, in some cases Stripe filters them out even when they’re enabled. We filter Google Pay if you enable automatic tax without collecting a shipping address.

Checkout’s Stripe-hosted pages don’t need integration changes to enable Apple Pay or Google Pay. Stripe handles these payments the same way as other card payments.

Confirm your endpoint

Confirm your endpoint is accessible by starting your web server (for example, localhost:4242) and running the following command:

Command Line
curl -X POST -is "http://localhost:4242/create-checkout-session" -d ""

You should see a response in your terminal that looks like this:

Command Line
HTTP/1.1 303 See Other
Location: https://checkout.stripe.com/c/pay/cs_test_...
...

Testing

You should now have a working checkout button that redirects your customer to Stripe Checkout.

  1. Click the checkout button.
  2. You’re redirected to the Stripe Checkout payment form.

If your integration isn’t working:

  1. Open the Network tab in your browser’s developer tools.
  2. Click the checkout button and confirm it sent an XHR request to your server-side endpoint (POST /create-checkout-session).
  3. Verify the request is returning a 200 status.
  4. Use console.log(session) inside your button click listener to confirm the correct data returned.

For more information about configuring and testing your hosted Checkout integration, see Accept a Payment.

Save payment method
Server-side

After setting up your hosted 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-time 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-time 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.

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_creation=always \
  -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]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success.html" \
  --data-urlencode cancel_url="https://example.com/cancel.html" \
  -d "payment_intent_data[setup_future_usage]"=off_session

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.

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_creation=always \
  -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]"=2000 \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success.html" \
  --data-urlencode cancel_url="https://example.com/cancel.html" \
  -d "saved_payment_method_options[payment_method_save]"=enabled

Passing this parameter in either payment or subscription mode displays an optional checkbox to let customers explicitly save their payment method for future purchases. When customers check this checkbox, Checkout saves the payment method with allow_redisplay: always. Checkout uses this parameter to determine whether a payment method can be prefilled 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 prefilled for returning purchases and allows you to comply with card network rules and data protection regulations. Learn how to change the default behavior enabled by these modes and how to change or override allow_redisplay behavior.

Note

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

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