Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support

Checkout Reference (legacy)

This page is for the legacy version of Checkout

We released a new version of Checkout in April 2019 which redirects to a Stripe-hosted payments page and supports card payments, Apple Pay, and Google Pay. You can use the Checkout Migration Guide to move from the legacy version of Checkout to the new version. If you’d like to embed your payments form on your site, we recommend using Stripe Elements.

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 (for example, 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.

Checkout, running in the browser, securely accepts the payment information but does not initiate a payment attempt. The actual charge request is triggered from your server.

Integrating Checkout

Example integrations

We have Checkout integration guides for several platforms and languages to get you up and running as quickly as possible:

  • Sinatra
  • Rails
  • Flask
  • Express
  • ASP.NET (MVC)
  • ASP.NET (Web Forms)
  • Go
  • PHP

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.

The simple integration uses a <script> tag inside your payment form to render the blue Checkout button. Upon completion of the Checkout process, Checkout submits your form to your server, passing along a stripeToken and any elements your form contains. When adding the following code to your page, make sure that the form submits to your own server-side code within the action attribute:

<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="" data-description="Widget" data-image="" data-locale="auto" data-zip-code="true" data-currency="usd"
</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.

The above configuration also accepts the user’s postal code, when applicable, and passes this to Stripe. Although optional, use address and postal code verifications to help reduce fraud.

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.

ParameterDescription
stripeTokenThe ID of the token representing the payment details
stripeEmailThe 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)

Configuration options

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

Required

Option Description

key

string

Your publishable key (test or live)

token

source

function

(Only available with the custom integration)

The callback to invoke when the Checkout process is complete. Pass either a token callback or a source callback, not both. Checkout will call the token callback with a Token object and the source callback with a Source object.

function(token, args)

  • 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. function(source, args)
  • source is the Source object created
  • source.id can be used to create a charge or can be attached to a customer
  • source.owner.email contains the email address entered by the user
  • args is an object containing the billing and shipping addresses, if enabled. An example of the args object:
{ // 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

Option Description

image

string

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.

name

string

The name of your company or website

description

string

A description of the product or service being purchased

amount

number

The amount (in usd) that’s shown to the user in the Checkout dialog. Note that you still have to explicitly include the amount when you create a charge using the API.

locale

string

Specify auto to display Checkout in the user’s preferred language , if available. English will be used by default.

zipCode

Boolean

Specify whether Checkout should validate the billing postal code (true or false). The default is false, but we recommend setting it to true and enabling declines on verification failures in your account settings .

billingAddress

Boolean

Specify whether Checkout should collect the user’s billing address (true or false). The default is false.

Optional

Option Description

currency

string

The currency of the amount (3-letter ISO code). The default is USD.

panelLabel

string

The label of the payment button in the Checkout form (for example, Subscribe, Pay {{amount}}, and so on). 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.

shippingAddress

Boolean

Specify whether Checkout should collect the user’s shipping address (true or false). The default is false.

email

string

If you already know the email address of your user, you can provide it to Checkout to be prefilled.

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.

allowRememberMe

Boolean

Specify whether to include the option to “Remember Me” for future purchases (true or false). The default is true. This feature is dependent on being able to set cookies or use the browser’s localStorage, and may not be available if your customer has certain privacy settings enabled.

opened

function

(Only available with the custom integration)

function()

The callback to invoke when Checkout is opened.

closed

function

(Only available with the custom integration)

function()

The callback to invoke when Checkout is closed. Called after the token or source callback (for successful tokenizations or Source creations).

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 (for example, 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 }); }); });
Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Generating and using tokens
Integrating Checkout
Supported languages
HTTPS requirements
Supported browsers
Preventing Checkout from being blocked
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$