Checkout.js reference

We've gathered all those hard-to-find bits of information in this handy Checkout.js reference guide to help you build your integration with ease.

Configuration options

This is a complete list of Checkout.js configuration options.

Required

📘
Please note: You can only create payments in currencies that have been enabled for your account. Please contact your customer success manager if you need to process in additional currencies.

Data-key-attributes	JavaScript keys	Description
`data-public-key`	`publicKey`	Your public key — find it in the Hub.
`data-payment-token`	`paymentToken`	Your payment token. This is only required when creating an alternative payment charge with payment token.
`data-customer-email`	`customerEmail`	The customer's email address.
`data-value`	`value`	The payment value displayed in the payment lightbox.
`data-currency`	`currency`	The payment currency displayed in the payment lightbox.
`data-payment-mode`	`paymentMode`	Specifies the available payment methods. Mixed: all enabled credit/debit cards and alternative/local payments. cards: all enabled credit/debit cards only. localpayments = alternative payment methods. This is a required field for card payments and must be set to either `cards` or `mixed`.
`data-card-form-mode`	`cardFormMode`	Set to `cardTokenisation` to enable the card tokenization charge option. This is a required field for card payments and must be set to `cardTokenisation` (i.e. `cardFormMode: cardTokenisation`). This does not apply for alternative payments.

Optional

Date-key-attributes	JavaScript keys	Description	Default
`data-debug-mode`	`debugMode`	Set to `true` to view console messages.	n/a
`data-namespace`	`namespace`	Customize the default Checkout namespace.	n/a

Customer details

📘
Please note:
billingDetails is the only way to send customer details when using Checkout.js.

Data-key-attributes	JavaScript keys	Description	Default
`data-customer-name`	`customerName`	The name of the customer.	n/a
Sorry, not supported.	`billingDetails`	Payment billing details: `{addressLine1, addressLine2, postcode, country, city, phone{number}}`.	n/a

Billing details example

<form class="payment-form" method="POST" action="https://merchant.com/chargeCard">
  <script>
    window.CKOConfig = {
      publicKey: 'pk_test_6ff46046-30af-41d9-bf58-929022d2cd14',
      paymentToken: 'pay_tok_SPECIMEN-000',
      customerEmail: '[email protected]',
      value: 100,
      customerName: 'John Smith',
      billingDetails: {
        'addressLine1': "623 Slade Street",
        'addressLine2': "Apartment 8",
        'postcode': "31313",
        'country': "US",
        'city': "Hinesville",
        'phone': {'number': "9125084652"}
      }
    };
  </script>
  <script async src="https://cdn.checkout.com/sandbox/js/checkout.js"></script>
</form>

📘
In a live environment, 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>.

Payment details

Data-key-attributes	JavaScript keys	Description	Default
`data-payment-mode`	`paymentMode`	Specifies the available payment methods: mixed = All enabled credit/debit cards and alternative/local payments. cards = All enabled credit/debit cards only. localpayments = All enabled alternative/local payments only.	mixed
`data-payment-provider-id`	`paymentProviderId`	Defines a single alternative payment method within the payment widget. For example, iDEAL: `lpp_9`.	n/a
`data-lp-code`	`lpCode`	Deprecated – please use `paymentProviderId` (above) instead.	n/a
`data-use-currency-code`	`useCurrencyCode`	Boolean value that displays ISO3 currency code (e.g., `GBP`) instead of the currency symbol (e.g., `£`). `true` = Display ISO3 currency code `false` = Display currency symbol	false
`data-geo-country-code`	`countryCode`	ISO2 country code (e.g., `CN` = China; `UK` = United Kingdom) that determines the order in which alternative payment methods are displayed in the payment widget and lightbox. Alternative payment methods supported in the country specified will be displayed first.	n/a

Widget options

📘
These are applicable when integrating via Checkout.configure(), as it does not display the payment widget.

Data-key-attributes	JavaScript keys	Description	Default
`data-widget-color`	`widgetColor`	HEX value of your chosen widget color.	`#000333`
`data-button-color`	`buttonColor`	HEX value of your chosen button color.	`#00b660`
`data-button-label-color`	`buttonLabelColor`	HEX value of your chosen button text color.	`#ffffff`
`data-button-label`	`buttonLabel`	String value that sets the text inside the widget button.	`Pay Now`
`data-pay-button-selector`	`payButtonSelector`	The .class or #id of the element acting as the parent for the widget button.	n/a
Sorry, not supported	`widgetContainerSelector`	The .class or #id of the element hosting the Checkout.js widget.	`<body>`
`data-icon-container-selector`	`iconContainerSelector`	The .class or #id of the element hosting the Checkout.js widget card icons.	Same element as Pay Now button
`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`

Lightbox options

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 logo (180 x 36 pixels) beginning with `https`.	Checkout.com's Logo
`data-theme-color`	`themeColor`	HEX value of your chosen theme color.	`#00b660`
Sorry, not supported.	`iconColor`	HEX value of your chosen icon color.	`#3075dd`
`data-form-button-label`	`formButtonLabel`	String value that sets the text inside the lightbox form's submit button.	`Checkout Now`
`data-force-redirect`	`forceRedirect`	Boolean value that forces redirect to the payment app instead of opening the payment app in an iframe. `true` = enable redirection `false` = disable redirection	`false`
`data-force-mobile-redirect`	`forceMobileRedirect`	Boolean value that forces mobile redirection instead of using tabs. `true` = enable mobile redirection `false` = disable mobile redirection	`false`
Sorry, not supported.	`redirectUrl`	The URL where a cardholder would be redirected once their card details are submitted via the payment app. If `forceRedirect` or `forceMobileRedirect` are enabled, a `redirectUrl` must be specified. If the redirect URL parameter is specified it will override the FORM action URL.	n/a
`data-enable-iframe-preloading`	`enableIframePreloading`	Boolean value that preloads lightbox. `true` = enable lightbox preload `false` = disable lightbox preload	true
`data-single-state`	`singleState`	Boolean value that locks the lightbox into a single state. `true` = enable single state `false` = disable single state	false
`data-theme`	`theme`	Sets the colour scheme of the lightbox. Available options include: `standard` = blue `light` = white	standard
Sorry, not supported.	`cardFormMode`	Enables payments with a card token. Please see Checkout.js for examples.	`Checkout.CardFormModes.CARD_CHARGE` or `cardTokenised` if Checkout.js is called asynchronously.
Sorry, not supported.	`useMobileLightbox`	Opens the payment app inside the merchant checkout screen on mobile devices.	false

Localization

Data-key-attributes JavaScript keys Description Default

Data-key-attributes	JavaScript keys	Description	Default
`data-localisation`	`localisation`	Defines language of the (supplied) text displayed in the payment widget and payment lightbox. Available options include: DE-DE = German EN-GB = English ES-ES = Spanish FR-FR = French IT-IT = Italian KR-KR = Korean NL-NL = Dutch

data-localisation

localisation

Defines language of the (supplied) text displayed in the payment widget and payment lightbox.

Available options include:

DE-DE = German
EN-GB = English
ES-ES = Spanish
FR-FR = French
IT-IT = Italian
KR-KR = Korean
NL-NL = Dutch

Advanced styling

You can define advanced styling and customization of Checkout.js using the Javascript API and setting the styling property in the configuration object.

// Method A

window.CKOConfig.styling = {
  formButtonColor: "#591459",
  overlayShade: "light"
};

// Method B

Checkout.render({
  ...
  styling: {
    formButtonColor: "#591459",
    overlayShade: "light"
  }
});

The available options for the styling object:

Data-key-attributes	Javascript keys	Description	Default
n/a	`formButtonColor`	HEX value of your chosen lightbox submit button color.	`#00b660`
n/a	`formButtonLabelColor`	HEX value of your chosen lightbox submit button label color.	`#ffffff`
n/a	`overlayShade`	Sets the color of the overlay behind the payment lightbox. Available options include: `dark` `light`	`dark`
n/a	`overlayOpacity`	Opacity of the overlay displayed behind the payment lightbox, expressed as a number between 0.8 and 1.	`0.9`
`data-show-mobile-icons`	`showMobileIcons`	Boolean value that displays widget icons on mobile. `true` = mobile icons enabled `false` = mobile icons disabled	`false`
`data-widget-icon-size`	`widgetIconSize`	Sets size of the payment widget icons. Available options include: `small` (40 x 22px) `medium` (50 x 28px) `large` (60 x 34px)	`small`

Handlers

With Checkout.js, we dispatch events which you can handle for various purposes. The table below provides the full list of events — use them to attach to one or more handlers.

Event name	Javascript constant	When
`ready`	`READY`	Triggered when Checkout.js is registered on the global namespace and is safe to use.
`cardTokenised`	`CARD_TOKENISED`	After tokenizing a card; it returns a card token and a card object containing the `paymentMethod` (e.g., VISA, AMEX, etc.) and bin (first six digits of the credit card number). For example, `{cardToken: "card_tok_111", card: {paymentMethod: 'VISA', bin: '424242'}}`
`cardTokenisationFailed`	`CARD_TOKENISATION_FAILED`	After card tokenization fails.
`paymentTokenExpired`	`PAYMENT_TOKEN_EXPIRED`	After paymentToken expires.
`lpCharged`	`LP_CHARGED`	After successful local payment charge (see sample code below).
`lpChargeFailed`	`LP_CHARGE_FAILED`	After a local payment fails; this event object will contain the payment URL and response code. For example, `{localPayment: {paymentUrl: "http://www..."}, responseCode: 20***}`.
`apiError`	`API_ERROR`	Failure to receive a correct response from the Checkout's Gateway API will result in an `apiError` event being dispatched.

Example: Using Configuration Options to Define lpCharged Options

Checkout.render({
  publicKey: '...',
  lpCharged: {
    callback: function(event) {
      console.log(event.data);
    },
    options: {
      removeOverlayOnRedirect: false,
      removeSpinnerOnRedirect: false,
      onRedirectMessage: "your message here..."
    }
  }
});

Localization events

Event name	Javascript constant	When
`localisationLoaded`	`LOCALISATION_LOADED`	When a language other than English is loaded.
`localisationLoadFailed`	`LOCALISATION_LOAD_FAILED`	When failing to load a requested language.

Widget and lightbox events

Event name	Javascript constant	When
`widgetRendered`	`WIDGET_RENDERED`	After the Checkout.js widget is rendered.
`lightboxActivated`	`LIGHTBOX_ACTIVATED`	After the Checkout.js lightbox opens.
`lightboxDeactivated`	`LIGHTBOX_DEACTIVATED`	After the Checkout.js lightbox closes automatically following the completion of a payment, or after the user closes the lightbox manually.
`lightboxCancelled`	`LIGHTBOX_CANCELLED`	If the user presses esc or cancel before the Checkout.js lightbox loads.
`lightboxLoadFailed`	`LIGHTBOX_LOAD_FAILED`	If the Checkout.js lightbox fails to load.
`invalidLightboxConfig`	`INVALID_LIGHTBOX_CONFIG`	If configuration parameters required by the Checkout.js lightbox (`publicKey`, `paymentToken`, `value`, `currency`) are missing or invalid.

Adding an event handler

There are two ways to add an event handler:

using the standard approach
using configuration options

Checkout.addEventHandler(Checkout.Events.<EVENT_CONSTANT>, handler, options);

Checkout.render({
  publicKey: '...',
  <event name>: handler
});

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].

Configuration options

Required

Optional

Customer details

Please note:

In a live environment, 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>.

Payment details

Widget options

Lightbox options

Localization

Advanced styling

Handlers

Example: Using Configuration Options to Define lpCharged Options

Localization events

Widget and lightbox events

Adding an event handler

Can we help?

In a live environment, 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>`.