Checkout API Quickstart Beta

    Learn how to get started quickly with new Checkout using the CheckoutSessions API.

    The CheckoutSessions API is an offering to allow you to provide dynamic amounts and ad-hoc line items that aren’t tied to SKUs or plans. The flow is simple, you will need to create a session on your server to start Checkout on the client.

    1. Enable Checkout in the Dashboard
    2. Create a CheckoutSession on your server
    3. Add Checkout to your website

    Step 1: Enable Checkout in the Dashboard

    To begin using Checkout, log into the Stripe Dashboard, navigate to your Business settings > Checkout section, and click Get started.

    Step 2: Create a CheckoutSession on your server

    We currently have official support for this beta API in our Ruby, Python, and Node.js bindings.

    When you create an instance of the Stripe object with a client library, you must append a beta flag (checkout_sessions_beta=v1) in order to access the functionality.

    Once you have set up your Stripe-Version header, you are ready to create a CheckoutSession to be used in the new Checkout. You are required to provide a list of line_items, a cancel_url, a success_url, and allowed_source_types. See the API reference for a complete list of parameters that can be used for session creation.

    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    Stripe.api_version = "2018-11-08; checkout_sessions_beta=v1"
    
    Stripe::Checkout::Session.create(
      :success_url => "https://www.example.com/success",
      :cancel_url => "https://www.example.com/cancel",
      :allowed_source_types => ["card"],
      :line_items => [{
        :amount => 2000,
        :quantity => 2,
        :name => "Blue banana",
        :currency => "usd"
      }]
    )
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    stripe.api_version = "2018-11-08; checkout_sessions_beta=v1"
    
    stripe.checkout.Session.create(
      success_url="https://www.example.com/success",
      cancel_url="https://www.example.com/cancel",
      allowed_source_types=["card"],
      line_items=[
        {
          "amount": 2000,
          "quantity": 2,
          "name": "Blue banana",
          "currency": "usd"
        }
      ]
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    stripe.checkout.sessions.create(
      {
        success_url: "https://www.example.com/success",
        cancel_url: "https://www.example.com/cancel",
        allowed_source_types: ["card"],
        line_items: [{
          amount: 2000,
          quantity: 2,
          name: "Blue banana",
          currency: "usd"
        }]
      },
      {stripe_version: "2018-11-08; checkout_sessions_beta=v1"}
      function(err, coupon) {
        // asynchronously called
      }
    );
    

    Your client integration needs the id field from the API response, so be sure to make that available in your template.

    Step 3: Add Checkout to your website

    To use Checkout on your website, you must add a snippet of code that includes the id field from the session that you created in the previous step.

    Checkout relies on Stripe.js. To get started, include the following script tag on your website—it should always be loaded directly from https://js.stripe.com:

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

    Next, create an instance of the Stripe object by providing your publishable API key as the first parameter:

    var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {betas: ['checkout_beta_4']});

    When your customer is ready to pay, call redirectToCheckout to begin the checkout process. This is where you provide the id from session creation as a parameter to Checkout.

    stripe.redirectToCheckout({
      sessionId: {%= session.id %},
    }).then(function (result) {
      // Display result.error.message to your customer
    });

    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.

    Once payment is successful, you should fulfill the customer’s purchase. You can use webhooks to fulfill the purchase when the checkout_beta.session_succeeded event triggers. For more details about handling purchase fulfillment with Checkout, refer to the documentation.

    You should not rely on the redirect to the successUrl page for fulfilling purchases, as customers may not always visit the successUrl page when they make a successful payment.

    Next steps

    Congrats! You now have a complete Checkout integration using the Checkout Sessions API. When testing your integration with your test API key, you can use a test card number to ensure that it works correctly.

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.