This version of our Documentation is for the eyes of employees and select merchants only.
Guides
API Reference

Our reference library for integrating with our API

Classic Docs

Documentation for our Classic API

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.

Checkout.js is a legacy solution. Upgrade to Hosted Payments Page—our easiest integration method.

Configuration options

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

Required

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 attributeJavaScript keyDescription
data-public-keypublicKeyYour public key. You can find it in the Hub.
data-payment-tokenpaymentTokenYour payment token. This is only required when creating an alternative payment charge with payment token.
data-customer-emailcustomerEmailThe customer's email address.
data-valuevalueThe payment value displayed in the payment lightbox.
data-currencycurrencyThe payment currency displayed in the payment lightbox.
data-payment-modepaymentMode

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 payment methods only

This is a required field for card payments and must be set to either cards or mixed.

data-card-form-modecardFormMode

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

Data-key attributeJavaScript keyDescriptionDefault
data-debug-modedebugModeSet to true to view console messages.N/A
data-namespacenamespaceUse to customize the default Checkout namespace.N/A

Customer details

billingDetails is the only way to send customer details when using Checkout.js.

Data-key attributeJavaScript keyDescriptionDefault
data-customer-namecustomerNameThe name of the customer.N/A
Not supportedbillingDetails

Payment billing details:
{addressLine1, addressLine2, postcode, country, city, phone{number}}

N/A

Example billing details

<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: 'user@email.com',
      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 attributeJavaScript keyDescriptionDefault
data-payment-modepaymentMode

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-idpaymentProviderIdDefines a single alternative payment method within the payment widget. For example, iDEAL: lpp_9.N/A
data-lp-codelpCodeDeprecated. Please use paymentProviderId (above) instead.N/A
data-use-currency-codeuseCurrencyCode

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-codecountryCodeISO2 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 attributeJavaScript keyDescriptionDefault
data-widget-colorwidgetColorHEX value of your chosen widget color.#000333
data-button-colorbuttonColorHEX value of your chosen button color.#00B660
data-button-label-colorbuttonLabelColorHEX value of your chosen button text color.#FFFFFF
data-button-labelbuttonLabelString value that sets the text inside the widget button.Pay Now
data-pay-button-selectorpayButtonSelectorThe .class or #id of the element acting as the parent for the widget button.N/A
Not supportedwidgetContainerSelectorThe .class or #id of the element hosting the Checkout.js widget.<body>
data-icon-container-selectoriconContainerSelectorThe .class or #id of the element hosting the Checkout.js widget card icons.Same element as Pay Now button.
data-render-moderenderMode
  • 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 attributeJavaScript keyDescriptionDefault
data-titletitleThe title of your payment form.N/A
data-subtitlesubtitleThe subtitle of your payment form.N/A
data-logo-urllogoUrlThe URL of your logo (180 x 36 pixels), beginning with https.The Checkout.com logo
data-theme-colorthemeColorHEX value of your chosen theme color.#00b660
Not supportediconColorHEX value of your chosen icon color.#3075dd
data-form-button-labelformButtonLabelString value that sets the text inside the lightbox form's submit button.Checkout Now
data-force-redirectforceRedirect

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

Boolean value that forces mobile redirection instead of using tabs.

  • true: enable mobile redirection
  • false: disable mobile redirection
false
Not supportedredirectUrl

The URL where a cardholder would be redirected once their card details are submitted via the payment app. If forceRedirect or forceMobileRedirect is 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-preloadingenableIframePreloading

Boolean value that preloads lightbox.

  • true: enable lightbox preload
  • false: disable lightbox preload
true
data-single-statesingleState

Boolean value that locks the lightbox into a single state.

  • true: enable single state
  • false: disable single state
false
data-themetheme

Sets the colour scheme of the lightbox. Available options include:

  • standard: blue
  • light: white
standard
Not supportedcardFormMode

Enables payments with a card token.

Please see Checkout.js for examples.

Checkout.CardFormModes.CARD_CHARGE
or cardTokenised if Checkout.js is called asynchronously.

Not supporteduseMobileLightboxOpens the payment app inside the merchant checkout screen on mobile devices.false

Localization

Data-key attributeJavaScript keyDescription
data-localisationlocalisation

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 are:

Data-key attributeJavaScript keyDescriptionDefault
N/AformButtonColorHEX value of your chosen lightbox submit button color#00B660
N/AformButtonLabelColorHEX value of your chosen lightbox submit button label color.#FFFFFF
N/AoverlayShade

Sets the color of the overlay behind the payment lightbox.

Available options include:

  • dark
  • light
dark
N/AoverlayOpacityOpacity of the overlay displayed behind the payment lightbox, expressed as a number between 0.8 and 1.0.9
data-show-mobile-iconsshowMobileIcons

Boolean value that displays widget icons on mobile.

  • true: mobile icons enabled
  • false: mobile icons disabled
false
data-widget-icon-sizewidgetIconSize

Sets size of the payment widget icons. Available options include:

  • small (40 x 22px)
  • medium (50 x 28px)
  • large (60 x 34px)

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 nameJavaScript constantDescription
readyREADYTriggered when Checkout.js is registered on the global namespace and is safe to use.
cardTokenisedCARD_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'}}

cardTokenisationFailedCARD_TOKENISATION_FAILEDAfter card tokenization fails.
paymentTokenExpiredPAYMENT_TOKEN_EXPIREDAfter paymentToken expires.
lpChargedLP_CHARGEDAfter successful local payment charge (see sample code below).
lpChargeFailedLP_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***}.

apiErrorAPI_ERRORFailure 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 nameJavaScript constantDescription
localisationLoadedLOCALISATION_LOADEDWhen a language other than English is loaded.
localisationLoadFailedLOCALISATION_LOAD_FAILEDWhen failing to load a requested language.

Widget and lightbox events

Event nameJavaScript constantDescription
widgetRenderedWIDGET_RENDEREDAfter the Checkout.js widget is rendered.
lightboxActivatedLIGHTBOX_ACTIVATEDAfter the Checkout.js lightbox opens.
lightboxDeactivatedLIGHTBOX_DEACTIVATEDAfter the Checkout.js lightbox closes automatically following the completion of a payment, or after the user closes the lightbox manually.
lightboxCancelledLIGHTBOX_CANCELLEDIf the user presses esc or cancel before the Checkout.js lightbox loads.
lightboxLoadFailedLIGHTBOX_LOAD_FAILEDIf the Checkout.js lightbox fails to load.
invalidLightboxConfigINVALID_LIGHTBOX_CONFIGIf 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., handler, options);
Checkout.render({
  publicKey: '...',
  : handler
});