Set up future payments

Learn how to save payment details in a Checkout session and charge your customers later.

To collect customer payment details that you can re-use later, use Checkout’s setup mode. Setup mode uses the Setup Intents API to create Payment Methods.

Set up Stripe Server-side

First, you need a Stripe account. Register now.

Use our official libraries to access the Stripe API from your application:

Command Line

Select a language

Ruby

Python

PHP

Java

Node.js

.NET

No results

# Available as a gem
sudo gem install stripe

Gemfile

Select a language

Ruby

Python

PHP

Java

Node.js

.NET

No results

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a Checkout Session Server-side

From your server, create a Checkout Session and set the ui_mode to embedded_page. To create a setup mode Checkout Session, set the mode to setup.

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 {the related setting} 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.

You can optionally specify the customer parameter to automatically attach the created payment method to an existing customer.

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

Select a language

Ruby

Python

PHP

Java

Node.js

.NET

No results

# This example sets up an endpoint using the Sinatra framework.
require 'json'
require 'sinatra'
require 'stripe'

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')

post '/create-checkout-session' do
 session = client.v1.checkout.sessions.create({
 currency: 'usd',
 mode: 'setup',
 ui_mode: 'embedded_page',
 return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
 })

 {clientSecret: session.client_secret}.to_json
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’s payment methods review page.

Checkout supports Apple Pay and Google Pay with no integration changes. Learn how to test wallets.

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

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_GvF3BSyx8RSXMK5yAFhqEd3H');

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.createEmbeddedCheckoutPage({
 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).

Retrieve the Checkout Session Server-side

After a customer successfully completes their Checkout Session, you need to retrieve the Session object. There are two ways to do this:

Asynchronously : Handle checkout. session. completed webhooks , which contain a Session object. Learn more about setting up webhooks .
Synchronously : Obtain the Session ID from the return _ url when a user redirects back to your site. Use the Session ID to retrieve the Session object.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

The right choice depends on your tolerance for dropoff, as customers may not always reach the return_url after a successful payment. It’s possible for them close their browser tab before the redirect occurs. Handling webhooks prevents your integration from being susceptible to this form of dropoff.

After you have retrieved the Session object, get the value of the setup_intent key, which is the ID for the SetupIntent created during the Checkout Session. A SetupIntent is an object used to set up the customer’s bank account information for future payments.

Example checkout.session.completed payload:

{
 "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
 "object": "event",
 "api_version": "2019-03-14",
 "created": 1561420781,
 "data": {
 "object": {
 "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
 "object": "checkout.session",
 "billing_address_collection": null,
 "client_reference_id": null,
 "customer": "",
 "customer_email": null,
 "display_items": [],
 "mode": "setup",
 "setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM",
 "submit_type": null,
 "subscription": null,
 "success_url": "https://example.com/success"
 }
 },
 "livemode": false,
 "pending_webhooks": 1,
 "request": {
 "id": null,
 "idempotency_key": null
 },
 "type": "checkout.session.completed"
}

Note the setup_intent ID for the next step.

Retrieve the SetupIntent Server-side

Using the SetupIntent ID, retrieve the SetupIntent object. The returned object contains a payment_method ID that you can attach to a customer in the next step.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Note

If you’re requesting this information synchronously from the Stripe API (as opposed to handling webhooks), you can combine the previous step with this step by expanding the SetupIntent object in the request to the /the relevant part of the product endpoint. Doing this prevents you from having to make two network requests to access the newly created PaymentMethod ID.

Charge the payment method later Server-side

If you didn’t create the Checkout Session with an existing customer, use the ID of the PaymentMethod to attach the PaymentMethod to a Customer. After you attach the PaymentMethod to a customer, you can make an off-session payment using a PaymentIntent:

Set customer to the ID of the Customer and payment_method to the ID of the PaymentMethod.
Set off_session to true to indicate that the customer isn’t in your checkout flow during a payment attempt and can’t fulfil 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 throw 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

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

When a payment attempt fails, the request also fails with a 402 HTTP status code and the status of the PaymentIntent 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

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results