Checkout.js

Checkout.js offers your customers a quick, easy payment experience.

Checkout.js is our simplest solution. If you'd prefer a more customizable payment form, take a look at Frames.

How it works

Checkout.js is a widget that sits on your checkout page and provides all the tools you need to securely collect a customer's card details and send them straight to us for tokenization - tokenization - The industry standard process for protecting sensitive data by replacing it with an algorithmically generated number called a token. At Checkout.com we use tokenization to protect our customers' confidential payment information from fraudsters. Payment information is substituted with randomly generated numbers — the tokens — and passed to us over the internet. Using the token, we can locate the payment details from our secure vault and complete the request without the need to transfer any sensitive data. — they never even touch your server. We'll then send you a card token, allowing you to request a card payment.

Try it out

Why not give Checkout.js a test run? Click the Pay Now button below and the form will spring to life. Use the following details to complete the form:

  • email address — we've filled this in for you
  • use one of our test cards, for example, 4242 4242 4242 4242
  • use any future expiry date (mm/yy)
  • and the CVV is 100

Integrate Checkout.js

Before you start

Make sure you have your public_key. You can find it in the Hub, under Settings > Channels. If you don't have an account with us yet, sign up for your free test account at Checkout.com.

Step 1: Pick a display method

First, you need to choose a display method. We offer three ways to integrate Checkout.js into your website, so you can pick the one that best fits your requirements:

Method
Description

window.CKOConfig

Our recommended option, which allows you to run Checkout.js synchronously or asynchronously. This simple integration method provides a widget displaying accepted payment icons alongside a Pay Now button that triggers the payment form.

Checkout.configure()

Gives you more control over how and when the Pay Now button and payment lightbox appear.

We offer two variants:

  • Variant A, which opens the payment lightbox instantly, without the use of a Pay Now button.
  • Variant B, which uses a custom Pay Now button to launch the payment lightbox.

Checkout.js can only be run synchronously with this method.

Checkout.render()

Renders the payment widget automatically onto your page, displaying the accepted payment icons, the Pay Now button, and the lightbox payment form.

Checkout.render() offers an asynchronous payment process. This means that it can take several days to confirm the success or failure of a payment.

Step 2: Add the code snippet to your site

Next, copy the code snippet for your chosen method and add it to your checkout page.

You'll need to replace the example publicKey with your own, and edit the required key-value pairs to reflect the order details (see the JavaScript keys table below for details).

The card token will be posted via the URL specified in the form's action attribute.

<form class="payment-form" method="POST" action="https://merchant.com/successUrl">
  <script>
    window.CKOConfig = {
      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      customerEmail: 'user@email.com',
      value: 100,
      currency: 'GBP',
      paymentMode: 'cards',
      cardFormMode: 'cardTokenisation',
      cardTokenised: function(event) {
        console.log(event.data.cardToken);
      }
    };
  </script>
  <script async src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
</form>
<script src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
<form class="payment-form" method="POST" action="https://merchant.com/successUrl">
  <script>
    Checkout.configure({
      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      customerEmail: 'user@email.com',
      value: 100,
      currency: 'GBP',
      paymentMode: 'cards',
      cardFormMode: 'cardTokenisation',
      cardTokenised: function (event) {
        console.log(event.data.cardToken);
      }
    });
    Checkout.open();
  </script>
</form>
<script src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
<form class="payment-form" method="POST" action="https://merchant.com/successUrl">
  <script>
    Checkout.configure({
      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      customerEmail: 'user@email.com',
      value: 100,
      currency: 'GBP',
      payButtonSelector: '.customButton' || '#customButton',
      paymentMode: 'cards',
      cardFormMode: 'cardTokenisation',
      cardTokenised: function (event) {
        console.log(event.data.cardToken);
      }
    });
    Checkout.open();
  </script>
</form>
<script src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
<form class="payment-form" method="POST" action="https://merchant.com/successUrl">
  <script>
    Checkout.render({
      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      paymentToken: 'pay_tok_SPECIMEN-000',
      customerEmail: 'user@email.com',
      value: 100,
      currency: 'GBP',
      cardFormMode: 'cardTokenisation',
      cardTokenised: function(event) {
        console.log(event.data.cardToken);
      }
    });
  </script>
</form>

When you're processing live payments, replace <script async src="https://cdn.checkout.com/sandbox/js/checkout.js"></script> with <script async src="https://cdn.checkout.com/js/checkout.js"></script>.

JavaScript keys

These are the JavaScript keys you need to use when embedding Checkout.js.

JavaScript keys
Description

cardFormMode
Required

Set to cardTokenisation to charge with card token.

currency
Required

The payment currency (three-letter ISO 4217 code).

publicKey
Required

Your public key. You'll find this in the Hub.

value
Required

The payment amount, written as a whole number (0 and decimal figures are not allowed).

For most currencies, the value is 100 times one unit of currency (e.g. 1 US Dollar is equivalent to 'value = 100').

A full description of how value is calculated for all our supported currencies is available here.

customerEmail
Optional

The customer's email address.

Make Checkout.js your own

Configuration options

You'll find a list of all the possible configuration options, plus some examples, in our Checkout.js reference guide.

Customization

Checkout.js gives you the flexibility to adjust its look and feel to suit your brand and checkout page. You can display your company's logo, use custom fonts and add some color to represent your brand's personality. Check out our customization guide for more details.

Next step

Now that you've got your card token, you're ready to request your first card payment.

Start testing

Ready to try out your integration? Create a test account to get everything working perfectly before going live.
Get test account

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.

Checkout.js


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.