Detailed Checkout Guide

Checkout is the best payment flow, on web and mobile. Checkout builds on top of Stripe.js to provide your users with a streamlined, mobile-ready payment experience that is constantly improving. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

Try out Checkout right now by clicking the button below! Use our test card number4242 4242 4242 4242, any future month and year for the expiration, and any three-digit number for the CVC.

Checkout securely accepts your customer's payment details and directly passes them to Stripe's servers. Stripe returns a token representation of those payment details, which can then be submitted to your server for use. Checkout doesn't actually create charges—it only creates tokens. You can use those tokens to create the actual charge on your server. Or you can save the card for charging later, or sign the user up for recurring charges.

Integration

You can integrate Checkout in as little as a single line of client-side code. As we release new Stripe features, we'll automatically roll them out to your existing Checkout integration, so that you will always be using our latest technology without needing to change a thing.

Checkout supports two different integrations:

  • Simple: The simple integration provides a blue Pay with Card button as shown above. Upon completion of the payment form and receipt of the token, Checkout stores the token within a hidden input in your payment form and automatically submits the form for server-side use.
  • Custom: The custom integration lets you create a custom button and passes a Stripe token to a JavaScript callback. Your JavaScript callback will need to send the token to your server for use.
SimpleCustom

The simple integration uses a script tag inside your payment form to render the blue Checkout button. Upon completion of the Checkout process, Checkout will submit your form to your server, passing along a stripeToken as well as any elements your form contains.

<form action="/charge" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js" class="stripe-button"
    data-key="pk_test_6pRNASCoBOKtIshFeQd4XMUh"
    data-amount="2000"
    data-name="Stripe.com"
    data-description="2 widgets"
    data-image="/img/documentation/checkout/marketplace.png"
    data-locale="auto">
  </script>
</form>

We've placed a random API key in the code. Replace it with your actual publishable API key to test this code through your Stripe account.

Although optional, we highly recommend also having Checkout collect the user's postal code as address and postal code verifications help reduce fraud. Simply add data-zip-code="true" to the above and enable declines on verification failures in your account settings.

Note: Checkout must be loaded directly from https://checkout.stripe.com/checkout.js. Using a local copy of Checkout is unsupported, and may result in user-visible errors.

Received parameters

The following parameters are submitted to your form's action endpoint, along with any other elements in your form, once Checkout completes.

Parameter Description
stripeToken The ID of the token representing the payment details
stripeEmail The email address the user entered during the Checkout process
stripeBillingName
stripeBillingAddressLine1
stripeBillingAddressZip
stripeBillingAddressState
stripeBillingAddressCity
stripeBillingAddressCountry
Billing address details (if enabled)
stripeShippingName
stripeShippingAddressLine1
stripeShippingAddressZip
stripeShippingAddressState
stripeShippingAddressCity
stripeShippingAddressCountry
Shipping address details (if enabled)

The custom integration allows you to use any HTML element or JavaScript event to trigger Checkout. The custom integration requires solid JavaScript skills, and you'll have to perform all of the requisite steps that a simple integration does for you.

When your page loads, you should create a handler object using StripeCheckout.configure(). You can then call open() on the handler in response to any event. If you need to abort the Checkout process—for example, when navigation occurs in a single-page application, call close() on the handler. The key parameter must be passed to configure(). Any other options can be passed to either configure() or open().

The following custom custom Checkout integration uses jQuery, but you're free to use vanilla JavaScript if you'd rather.

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

<button id="customButton">Purchase</button>

<script>
  var handler = StripeCheckout.configure({
    key: 'pk_test_6pRNASCoBOKtIshFeQd4XMUh',
    image: '/img/documentation/checkout/marketplace.png',
    locale: 'auto',
    token: function(token) {
      // You can access the token ID with `token.id`.
      // Get the token ID to your server-side code for use.
    }
  });

  $('#customButton').on('click', function(e) {
    // Open Checkout with further options:
    handler.open({
      name: 'Stripe.com',
      description: '2 widgets',
      amount: 2000
    });
    e.preventDefault();
  });

  // Close Checkout on page navigation:
  $(window).on('popstate', function() {
    handler.close();
  });
</script>

Although optional, we highly recommend also having Checkout collect the user's postal code as address and postal code verifications help reduce fraud. Simply add data-zip-code="true" to the above and enable declines on verification failures in your account settings.

Note: Checkout must be loaded directly from https://checkout.stripe.com/checkout.js. Using a local copy of Checkout is unsupported, and may result in user-visible errors.

Configuration options

Change how Checkout looks and behaves using the following configuration options.

Required

Option Description
data-key Your publishable key (test or live)
token(Only available with the custom integration) The callback to invoke when the Checkout process is complete
function(token)
  • token is the Token object created
  • token.id can be used to create a charge or can be attached to a customer
  • token.email contains the email address entered by the user
  • args is an object containing the billing and shipping addresses, if enabled (see example)
{
  // Billing name and address
  "billing_name": "Stripe",
  "billing_address_country": "United States",
  "billing_address_zip": "94110",
  "billing_address_state": "CA",
  "billing_address_line1": "18th Street, 3180",
  "billing_address_city": "San Francisco",

  // Shipping name and address
  "shipping_name": "Stripe",
  "shipping_address_country": "United States",
  "shipping_address_zip": "94110",
  "shipping_address_state": "CA",
  "shipping_address_line1": "18th Street, 3180",
  "shipping_address_city": "San Francisco"
}

Highly recommended

Option Description
data-image A relative or absolute URL pointing to a square image of your brand or product. The recommended minimum size is 128x128px. The supported image types are: .gif, .jpeg, and .png.
data-name The name of your company or website
data-description A description of the product or service being purchased
data-amount The amount (in cents) that's shown to the user. Note that you will still have to explicitly include the amount when you create a charge using the API.
data-locale Specify auto to display Checkout in the user's preferred language, if available. English will be used by default.

Optional

Option Description
data-currency The currency of the amount (3-letter ISO code). The default is USD.
data-panel-labelpanelLabel The label of the payment button in the Checkout form (e.g. Subscribe, Pay {{amount}}, etc.). If you include {{amount}} in the label value, it will be replaced by a localized version of data-amount. Otherwise, a localized data-amount will be appended to the end of your label. Checkout does not translate custom labels to the user's preferred language.
data-zip-codezipCode Specify whether Checkout should validate the billing postal code (true or false). The default is false, but we highly recommend setting to true and enabling declines on verification failures in your account settings.
data-billing-addressbillingAddress Specify whether Checkout should collect the user's billing address (true or false). The default is false.
data-shipping-addressshippingAddress Specify whether Checkout should collect the user's shipping address (true or false). The default is false.
data-email If you already know the email address of your user, you can provide it to Checkout to be pre-filled.
data-label(Only available with the simple integration) The text to be shown on the blue button. Default is Pay with Card. Checkout does not currently translate this label.
data-allow-remember-meallowRememberMe Specify whether to include the option to "Remember Me" for future purchases (true or false). The default is true.
data-bitcoin Specify whether to accept Bitcoin (true or false). The default is false.
data-alipay Specify whether to accept Alipay ("auto", true, or false). The default is false.
data-alipay-reusablealipayReusable Specify if you need reusable access to the customer's Alipay account (true or false). The default is false.
opened(Only available with the custom integration) function()
The callback to invoke when Checkout is opened (not supported in IE6 and IE7)
closed(Only available with the custom integration) function()
The callback to invoke when Checkout is closed (not supported in IE6 and IE7). Called after the token callback (for successful tokenizations).

FAQ

Does Checkout require HTTPS?

All submissions of payment info using Checkout are made via a secure HTTPS connection. However, in order to protect yourself from certain forms of man-in-the-middle attacks, you must serve the page containing the payment form over HTTPS as well. In short, the address of the page containing Checkout must start with https:// rather than just http://.

If you are not familiar with the process of buying SSL certificates and integrating them with your server to enable a secure HTTPS connection, please visit our help page for SSL.

Does Checkout verify that credit cards are valid?

Yes, Checkout verifies card details with the credit card networks to ensure they are valid. For additional protection, you can opt to have Checkout collect the billing postal code, and make sure that postal code validation is turned on for your account.

What browsers does Checkout support?

Checkout strives to support all known browsers. If you have an issue with Checkout on a specific browser, please contact us so we can improve its support.

How do I prevent the Checkout popup from being blocked?

You need to call handler.open when the user clicks on an element on the page. Do not call handler.open in a callback. This design indicates to the browser that the user is explicitly requesting the popup. Otherwise, mobile devices and some versions of Internet Explorer will block the popup and prevent users from checking out. This only applies to custom integrations.

// This will work:
$("#button").on("click", function() {
  handler.open({
    image: '/square-image.png',
    name: 'Demo Site',
    description: '2 widgets',
    amount: 2000
  });
});

// This will not work:
$("#failbutton").on("click", function() {
  $.ajax({
    url: "/",
  }).done(function() {
    handler.open({
      image: '/square-image.png',
      name: 'Demo Site',
      description: '2 widgets',
      amount: 2000
    });
  });
});