Checkout Reference (legacy)

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.

• Generating and using tokens
• Integrating Checkout
• Supported languages
• HTTPS requirements
• Supported browsers
• Preventing Checkout from being blocked

Generating and using tokens

With Stripe, sensitive cardholder data does not hit your server, greatly minimizing your PCI compliance burden. Stripe takes care of the hardest parts of PCI compliance, like redacting logs and encrypting card details. Just enable HTTPS on your checkout page, and we'll take over from there.

Here's the whole workflow:

1. The customer arrives at your payment page that includes the Checkout code, loaded over HTTPS.
2. The customer clicks the payment button (e.g., Pay with Card), completes the payment form, and clicks Pay $9.99 within the Checkout window (or whatever your Checkout pay button is).
3. Checkout sends the payment details directly to Stripe from the customer's browser, assuming the details pass basic validation.
4. Stripe returns a token to Checkout, or an error message if the card-network validation fails.
5. Checkout takes the returned token and stores it in the page's primary form—the one surrounding the <script> tag above, in a hidden element named stripeToken.
6. Checkout submits the form to your server.
7. Your server uses the posted token to charge the card.

Integrating Checkout

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. 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.

<form action="your-server-side-code" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js" class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-amount="999"
    data-name="Stripe.com"
    data-description="Widget"
    data-image="https://stripe.comhttps://stripe.com/img/documentation/checkout/marketplace.png"
    data-locale="auto"
    data-zip-code="true">
  </script>
</form>
<form action="your-server-side-code" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js" class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-amount="999"
    data-name="Stripe.com"
    data-description="Widget"
    data-image="https://stripe.com/img/documentation/checkout/marketplace.png"
    data-locale="auto"
    data-zip-code="true">
  </script>
</form>

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

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

<script>
var handler = StripeCheckout.configure({
  key: 'pk_test_TYooMQauvdEDq54NiTphI7jx',
  image: 'https://stripe.com/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.
  }
});

document.getElementById('customButton').addEventListener('click', function(e) {
  // Open Checkout with further options:
  handler.open({
    name: 'Stripe.com',
    description: '2 widgets',
    zipCode: true,
    amount: 2000
  });
  e.preventDefault();
});

// Close Checkout on page navigation:
window.addEventListener('popstate', function() {
  handler.close();
});
</script>
<script src="https://checkout.stripe.com/checkout.js"></script>

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

<script>
var handler = StripeCheckout.configure({
  key: 'pk_test_TYooMQauvdEDq54NiTphI7jx',
  image: 'https://stripe.com/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.
  }
});

document.getElementById('customButton').addEventListener('click', function(e) {
  // Open Checkout with further options:
  handler.open({
    name: 'Stripe.com',
    description: '2 widgets',
    zipCode: true,
    amount: 2000
  });
  e.preventDefault();
});

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

Configuration options

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

Required

{
  // Billing name and address
  "billing_name": "Stripe",
  "billing_address_country": "United States",
  "billing_address_zip": "94111",
  "billing_address_state": "CA",
  "billing_address_line1": "1234 Main Street",
  "billing_address_city": "San Francisco",
  "billing_address_country_code": "US",

  // Shipping name and address
  "shipping_name": "Stripe",
  "shipping_address_country": "United States",
  "shipping_address_zip": "94111",
  "shipping_address_state": "CA",
  "shipping_address_line1": "1234 Main Street",
  "shipping_address_city": "San Francisco",
  "shipping_address_country_code": "US"
}
{
  // Billing name and address
  "billing_name": "Stripe",
  "billing_address_country": "United States",
  "billing_address_zip": "94111",
  "billing_address_state": "CA",
  "billing_address_line1": "1234 Main Street",
  "billing_address_city": "San Francisco",
  "billing_address_country_code": "US",

  // Shipping name and address
  "shipping_name": "Stripe",
  "shipping_address_country": "United States",
  "shipping_address_zip": "94111",
  "shipping_address_state": "CA",
  "shipping_address_line1": "1234 Main Street",
  "shipping_address_city": "San Francisco",
  "shipping_address_country_code": "US"
}

Highly recommended

Optional

Supported languages

In addition to English, Checkout supports the following languages:

• Bulgarian (bg)
• Czech (cs)
• Danish (da)
• German (de)
• Greek (el)
• English (en)
• British English (en-GB)
• Spanish (es)
• LATAM/Caribbean Spanish (es-419)
• Estonian (et)
• Finnish (fi)
• French (fr)
• Canadian French (fr-CA)
• Hungarian (hu)
• Indonesian (id)
• Italian (it)
• Japanese (ja)
• Lithuanian (lt)
• Latvian (lv)
• Malaysian (ms)
• Maltese (mt)
• Norwegian Bokmal (nb)
• Dutch (nl)
• Polish (pl)
• Portuguese (pt)
• Brazilian Portuguese (pt-BR)
• Romanian (ro)
• Russian (ru)
• Slovak (sk)
• Slovenian (sl)
• Swedish (sv)
• Turkish (tr)
• Simplified Chinese (zh)

Custom strings passed to Checkout (e.g., name, description, panelLabel and label) are not automatically translated.

Checkout also uses the locale to format numbers and currencies. For example, when loading Checkout with currency set to EUR and locale set to auto, a browser configured to use English (en) could see €25.00 while one configured for Hungarian (hu) would see 25,00 €. If you provide a specific locale, Checkout will use that locale for number and currency formatting.

HTTPS requirements

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, check out our security documentation for more information.

Supported browsers

Checkout strives to support all recent versions of major browsers. For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

• We support Internet Explorer and Edge per Microsoft's lifecycle policy. We currently support IE11 and above.
• We support Chrome and Safari on all platforms and Firefox on desktop platforms.
• We require TLS 1.2 to be supported by the browser.
• We respond to bug reports but do not proactively test other mobile browsers.

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

Preventing Checkout from being blocked

You can prevent Checkout's popup from being blocked by calling 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:
document.getElementById("button").addEventListener("click", function() {
  handler.open({
    image: '/square-image.png',
    name: 'Demo Site',
    description: '2 widgets',
    amount: 2000
  });
});

// This will not work:
document.getElementById("failbutton").addEventListener("click", function() {
  fetch("/").then(function() {
    handler.open({
      image: '/square-image.png',
      name: 'Demo Site',
      description: '2 widgets',
      amount: 2000
    });
  });
});
// This will work:
document.getElementById("button").addEventListener("click", function() {
  handler.open({
    image: '/square-image.png',
    name: 'Demo Site',
    description: '2 widgets',
    amount: 2000
  });
});

// This will not work:
document.getElementById("failbutton").addEventListener("click", function() {
  fetch("/").then(function() {
    handler.open({
      image: '/square-image.png',
      name: 'Demo Site',
      description: '2 widgets',
      amount: 2000
    });
  });
});