Set up future payments

First, you need a Stripe account. Register now.

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

# Available as a gem
sudo gem install stripe

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

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.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="setup" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
  -d "cancel_url"="https://example.com/cancel"

Your Stripe.js integration needs the id field from the Session creation API response, so make it available to the JavaScript or HTML file you call redirectToCheckout from.

Checkout relies on Stripe.js, Stripe’s foundational JavaScript library for building payment flows.

<script src="https://js.stripe.com/v3/"></script>

var stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

var checkoutButton = document.getElementById('checkout-button');

checkoutButton.addEventListener('click', function() {
  stripe.redirectToCheckout({
    // Make the id field from the Checkout Session creation API response
    // available to this file, so you can provide it as argument here
    // instead of the {{CHECKOUT_SESSION_ID}} placeholder.
    sessionId: '{{CHECKOUT_SESSION_ID}}'
  }).then(function (result) {
    // If `redirectToCheckout` fails due to a browser or network
    // error, display the localized error message to your customer
    // using `result.error.message`.
  });
});

This code is typically invoked from an event handler that triggers in response to an action taken by your customer, such as clicking on a payment button.

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 the success_url) and retrieve the Session object.

curl https://api.stripe.com/v1/checkout/sessions/cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

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.

Using the setup_intent ID, retrieve the SetupIntent object.

curl https://api.stripe.com/v1/setup_intents/seti_1EzVO3HssDVaQm2PJjXHmLlM \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Note the payment_method ID returned for the next step.

If you didn’t create the Checkout Session with an existing customer, attach the PaymentMethod to a Customer. After it has been attached to a Customer, you can charge the PaymentMethod using a PaymentIntent.