Payments for existing customers

Learn how to charge an existing payment method while a customer is on-session.

A Checkout Session allows customers to enter their payment details. If this is an existing customer, you can configure the Checkout Session to prefill the details with one of their saved cards. The Checkout Session displays up to 50 saved cards that a customer can choose to pay with.

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.

index.html

<html>
 <head>
 <title>Checkout</title>
 </head>
 <body>
 <form action="/create-checkout-session" method="POST">
 <button type="submit">Checkout</button>
 </form>
 </body>
</html>

Checkout supports reusing existing customer-configured Account objects with the customer_account parameter or Customer objects with the customer parameter. When reusing existing customers, all objects created by Checkout, such as PaymentIntents and Subscriptions, are associated with the object that represents that customer.

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 preview version in your code.

To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.

For most use cases, we recommend modeling your customers as customer-configured Account objects instead of using Customer objects.

Append the {the related setting} template variable to the success_url to get access to the Session ID after your customer successfully completes a Checkout Session. After creating the Checkout Session, redirect your customer to the URL returned in the response.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Optional Display additional saved payment methods Server-side

Prefill fields on payment page

If all the following conditions are true, Checkout prefills the email, name, card, and billing address fields on the payment page using details from the customer’s saved card:

Checkout is in payment or subscription mode; setup mode doesn’t support prefilling fields.
The customer has a saved card. Checkout only supports prefilling card payment methods.
The saved card has allow _ redisplay set to always or you adjusted the default display setting .
The payment method includes billing_details required by the Checkout Session’s billing_address_collection value:
auto requires values for email , name , and address[country] . US, CA, and GB billing addresses also require address[postal _ code] .
required requires values for email , name , and all address fields.

If your customer has multiple saved cards, Checkout prefills details from the card matching the following prioritization:

In payment mode, Stripe prefills the fields using the customer’s newest saved card.
In subscription mode, Stripe prefills the customer’s default payment method if it’s a card. Otherwise, Stripe prefills the newest saved card.

When Checkout is collecting a shipping address, it prefills shipping address fields if the customer’s shipping address is in one of the Checkout Session’s supported countries.

To let your customers remove saved cards during a Checkout Session, set save_payment_method_options[payment_method_remove] to enabled.

Prefill timeout

The prefilled payment method displays for 30 minutes following Checkout Session creation. After it expires, loading the same Checkout Session doesn’t prefill the payment method anymore for security reasons.

Handle post-payment events Server-side

Stripe sends a checkout.session.completed event when a customer completes a Checkout Session payment. Use the Dashboard webhook tool or follow the webhook guide to receive and handle these events, which might trigger you to:

Send an order confirmation email to your customer.
Log the sale in a database.
Start a shipping workflow.

Listen to events rather than waiting for your customer to be redirected back to your website. Triggering fulfillment only from your Checkout success page is unreliable.

Learn more in our fulfillment guide for Checkout.