Set up future payments
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. See the Checkout Session API reference for a complete list of parameters that you can use for Session creation.
Append the {CHECKOUT_SESSION_ID}
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.
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.session.completed
webhooks, which contain a Session object. Learn more about setting up webhooks. - Synchronously: Obtain the
sessionId
from the URL when a user redirects back to your site (appended to thesuccess_url
) and retrieve the Session object.
The right choice depends on your tolerance for dropoff, as customers may not always reach the success_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, "cancel_url": "https://example.com/cancel", "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 SetupIntentServer-side
Using the setup_intent
ID, retrieve the SetupIntent object. The returned object contains a payment_method
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.
Use the payment methodServer-side
If you didn’t create the Checkout Session with an existing customer, use the payment_method
ID to attach the PaymentMethod to a Customer. After you attach the PaymentMethod to a customer, you can charge the PaymentMethod using a PaymentIntent.