Set up future payments
Learn how to save payment details and charge your customers later.
To collect customer payment details that you can reuse later, use Checkout’s setup mode. Setup mode uses the Setup Intents API to create Payment Methods.
Check out our full, working sample on GitHub.
Set up StripeServer-side
First, you need a Stripe account. Register now.
Use our official libraries to access the Stripe API from your application:
Create a Checkout SessionClient-sideServer-side
Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.
<html> <head> <title>Checkout</title> </head> <body> <form action="/create-checkout-session" method="POST"> <button type="submit">Checkout</button> </form> </body> </html>
To create a setup mode Session, use the mode parameter with a value of setup when creating the Session. You can optionally specify the customer parameter to automatically attach the created payment method to an existing customer. Checkout uses Dynamic payment methods by default, which requires you to pass the currency parameter when using setup mode.
Append the {CHECKOUT_ template variable to the success_ 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.
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.
Retrieve the Checkout SessionServer-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.webhooks, which contain a Session object. Learn more about setting up webhooks.session. completed - Synchronously: Obtain the Session ID from the
success_when a user redirects back to your site. Use the Session ID to retrieve the Session object.url
The right choice depends on your tolerance for dropoff, as customers may not always reach the success_ 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_ 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. 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_ ID for the next step.
Retrieve the SetupIntentServer-side
Using the setup_ ID, retrieve the SetupIntent object. The returned object contains a payment_ ID that you can attach to a customer in the next step.
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 /v1/checkout/session endpoint. Doing this prevents you from having to make two network requests to access the newly created PaymentMethod ID.
Charge the payment method laterServer-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
trueto 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 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.
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.