You're viewing our new Unified Payments API documentation. Click here to access our Classic API docs.

Checkout.js customization guide

Display your company's logo, use custom fonts and add some color to represent your brand's personality — it’s putty in your hands.

The Checkout.js experience is made up of two parts: the payment widget, and the payment lightbox.

The payment widget

The payment widget includes a Pay Now button and icons for all accepted payment methods. Depending on your preferences, you can configure the payment widget for three different display options:

1 - Payment icons and the Pay Now button (both)

1 - Payment icons and the Pay Now button (both)

2 - Payment icons (only)

2 - Payment icons (only)

3 - Pay Now button (only)

3 - Pay Now button (only)

Styling the payment widget

Why not add a bit of color to your Checkout.js widget? Match every element to the colors of your brand with just a few lines of code. Here's a list of the data-key attributes and JavaScript keys used to style the widget:

Data-key attributes
JavaScript keys
Description
Default value

data-widget-color

widgetColor

Choose a #HEX value for your widget color.

#333333

data-button-color

buttonColor

Choose a #HEX value for your button color.

#00b660

data-button-label-color

buttonLabelColor

Choose a #HEX value for your button's text color.

#ffffff

data-button-label

buttonLabel

String value to insert the text inside the widget button.

Maximum characters: 12.

Pay Now

data-render-mode

renderMode

0 = All
1 = Pay button only
2 = Icons only
3 = Active icons only (clicking an icon opens the payment lightbox)

0

Try customizing your widget with this JSFiddle (click Edit in JSFiddle). To make it simple, we've filled in the configurable keys for you. Study the code and play with the colors to make it look awesome.

The payment lightbox

Once a customer clicks the Pay Now button, the payment lightbox opens. The payment lightbox supports credit and debit card payments (by default), and it can also be customized to offer alternative payment options.

In its standard form, the payment lightbox looks like this:

Styling the payment lightbox

You can configure the payment lightbox to display text, colors and even a custom logo. The table below shows the data-key attributes and JavaScript keys used to customize your payment lightbox.

Data-key attributes
JavaScript keys
Description
Default

data-title

title

The title of your payment form.

n/a

data-subtitle

subtitle

The subtitle of your payment form.

n/a

data-logo-url

logoUrl

The URL of your company logo beginning with https (must be 180 x 36 pixels).

Checkout.com's logo

data-theme-color

themeColor

Choose a #HEX value for your theme.

#00b660

data-form-button-label

formButtonLabel

A string value that sets the text inside the lightbox's submit button.

Maximum characters: 12.

Checkout Now

data-theme

theme

Sets the colour scheme of the lightbox.

  • standard = blue
  • light = white

standard

Use the code excerpt below to understand how to customize the widget and lightbox fully. We've pre-entered all the customizable parameters for you — they're the attributes between these comments:

// Customizable attributes start
...
...
// Customizable attributes end

Make sure you remove these comments from your own code.

<form class="payment-form" method="POST" action="https://merchant.com/successUrl">
  <script>
    window.CKOConfig = {
      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      paymentToken: 'pay_tok_SPECIMEN-000',
      customerEmail: 'user@email.com',
      value: 100,
      currency: 'EUR',
      cardFormMode: 'cardTokenisation',
      paymentMode: 'cards' || 'mixed' || 'localpayments',
      countryCode: 'DE',
      renderMode: 0 || 1 || 2 || 3,
          
// Customizable attributes start
          
      buttonLabel: 'BUY NOW',
      widgetColor: '#123123',
      buttonColor: '#123123',
      buttonLabelColor: '#123123',
      title: 'Merchant',
      subtitle: 'Merchant Subtitle',
      logoUrl: 'https://docs.checkout.com/img/merchant-logo.png',
      formButtonLabel: 'Complete Purchase',
      theme: 'light',
          
// Customizable attributes end
          
    };
  </script>
  <script async src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
</form>

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 customization guide


Suggested Edits are limited on API Reference Pages

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