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 caseManaged Payments
Use Payment Links
Build a checkout page
Build an advanced integration
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 Elements
Payment scenarios
Handle multiple currencies
Custom payment flows
    Overview
    Payments for existing customers
    Authorise and capture a payment separately
    Build a two-step checkout flow
    Collect payment details before creating an Intent
    Finalise payments on the server
    Take mail orders and telephone orders (MOTO)
    US and Canadian cards
    Forward card details to third-party API endpoints
    Payments line items
Flexible acquiring
Orchestration
In-person payments
Terminal
Beyond payments
Incorporate your company
Crypto
Financial Connections
Climate
HomePaymentsCustom payment flows

Payments for existing customers

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

A Checkout Session allows buyers to enter their payment details. If the buyer is an existing customer, you can configure the Checkout Session to prefill the details with one of the customer’s saved cards.

Checkout with one saved card

Create a Checkout Session
Server-side

Checkout supports reusing existing Customer objects with the customer parameter. When reusing existing customers, all objects created by Checkout, such as Payment Intents and Subscriptions, are associated with that Customer object.

From your server, create a Checkout Session and set the ui_mode to embedded.

To return customers to a custom page that you host on your website, specify that page’s URL in the return_url parameter. Include the {CHECKOUT_SESSION_ID} template variable in the URL to retrieve the session’s status on the return page. Checkout automatically substitutes the variable with the Checkout Session ID before redirecting.

Read more about configuring the return page and other options for customising redirect behaviour.

After you create the Checkout Session, use the client_secret returned in the response to mount Checkout.

Command Line
cURL
curl https://api.stripe.com/v1/checkout/sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d mode=payment \ -d "line_items[0][price]"=
{{PRICE_ID}}
\ -d "line_items[0][quantity]"=1 \ -d customer=
{{CUSTOMER_ID}}
\ -d ui_mode=embedded \ --data-urlencode return_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}"

OptionalDisplay additional saved payment methods
Server-side

Mount Checkout
Client-side

Checkout is available as part of Stripe.js. Include the Stripe.js script on your page by adding it to the head of your HTML file. Next, create an empty DOM node (container) to use for mounting.

index.html
<head> <script src="https://js.stripe.com/basil/stripe.js"></script> </head> <body> <div id="checkout"> <!-- Checkout will insert the payment form here --> </div> </body>

Initialise Stripe.js with your publishable API key.

Create an asynchronous fetchClientSecret function that makes a request to your server to create the Checkout Session and retrieve the client secret. Pass this function into options when you create the Checkout instance:

index.js
// Initialize Stripe.js const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
); initialize(); // Fetch Checkout Session and retrieve the client secret async function initialize() { const fetchClientSecret = async () => { const response = await fetch("/create-checkout-session", { method: "POST", }); const { clientSecret } = await response.json(); return clientSecret; }; // Initialize Checkout const checkout = await stripe.initEmbeddedCheckout({ fetchClientSecret, }); // Mount Checkout checkout.mount('#checkout'); }

Checkout renders in an iframe that securely sends payment information to Stripe over an HTTPS connection.

Common mistake

Avoid placing Checkout within another iframe because some payment methods require redirecting to another page for payment confirmation.

Customize appearance

Customise Checkout to match the design of your site by setting the background colour, button colour, border radius, and fonts in your account’s branding settings.

By default, Checkout renders with no external padding or margin. We recommend using a container element such as a div to apply your desired margin (for example, 16px on all sides).

Prefill fields on payment page

If all the following conditions are true, Checkout pre-fills 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 pre-filling fields.
  • The customer has a saved card. Checkout only supports pre-filling 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 pre-fills details from the card matching the following prioritisation:

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

When Checkout is collecting a shipping address, Checkout pre-fills shipping address fields if the customer’s shipping.address meets the Checkout Session’s supported countries.

Pre-fill timeout

The pre-filled payment method displays for 30 minutes following Checkout Session creation. After it expires, loading the same Checkout Session doesn’t pre-fill the payment method any more 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 for these events rather than waiting for your customer to be redirected back to your website. Triggering fulfilment only from your Checkout landing page is unreliable. Setting up your integration to listen for asynchronous events allows you to accept different types of payment methods with a single integration.

Learn more in our fulfilment guide for Checkout.

Handle the following events when collecting payments with the Checkout:

EventDescriptionAction
checkout.session.completedSent when a customer successfully completes a Checkout Session.Send the customer an order confirmation and fulfill their order.
checkout.session.async_payment_succeededSent when a payment made with a delayed payment method, such as ACH direct debt, succeeds.Send the customer an order confirmation and fulfill their order.
checkout.session.async_payment_failedSent when a payment made with a delayed payment method, such as ACH direct debt, fails.Notify the customer of the failure and bring them back on-session to attempt payment again.
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access programme.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc