Checkout Browser SDK

Checkout Browser SDK lets you integrate commercetools Checkout both on regular websites and JavaScript web applications, either implemented in libraries or frameworks like React, Vue, or Angular.

Configuration properties

commercetools Checkout can be integrated either as a browser script or as an npm module. In both cases, you must provide a checkoutConfig object with the following properties.

In the documentation, we use placeholders for the property values (for example, {projectKey}). Replace placeholders with actual values.

Property	Value	Required	Description
`projectKey`	`{projectKey}`	Yes	The identifier of your Checkout entity and the `project_key` of your Project.
`sessionId`	`{sessionId}`	Yes	The identifier of the Checkout Session.
`region`	`{region}`	Yes	The Region where your Checkout application is hosted. For example, `europe-west1.gcp`.
`locale`	`{locale}`	No (default: `en`)	Your customer’s locale. If the provided locale is not found, English will be used.
`onInfo`	function	No	See onInfo, onWarn, and onError
`onWarn`	function	No	See onInfo, onWarn, and onError
`onError`	function	No	See onInfo, onWarn, and onError
`logInfo`	`true`/`false`	No (default: `false`)	See logInfo, logWarn, and logError
`logWarn`	`true`/`false`	No (default: `false`)	See logInfo, logWarn, and logError
`logError`	`true`/`false`	No (default: `false`)	See logInfo, logWarn, and logError
`styles`	`{styles}`	No	An object containing CSS variables to customize the style of Checkout.
`languageOverrides`	`{languageOverrides}`	No	An object containing properties to customize the texts and labels of Checkout.
`showTaxes`	`{showTaxes}`	No	Id set to `true`, tax information from Composable Commerce is displayed in the price summary of your checkout page.
`currencyLocale`	`{currencyLocale}`	No	The locale to set the currency formatting for prices. When it is not set, `locale` determines the price formatting as a default. If set, the locale for price formatting is overridden. For example, if `locale` is set to `fr`, Swiss prices are displayed as 10,00 CHF. If `currencyLocale` is set to `de-CH`, prices are displayed as CHF 10.00.

Browser script

To integrate Checkout as a browser script, add the following code between the opening and closing <head> tags of each page on which you want to activate the start of the checkout process.

Integrate Checkout as a browser scriptHTML

<script>
  (function (w, d, s) {
    if (w.ctc) {
      return;
    }
    var js,
      fjs = d.getElementsByTagName(s)[0];
    var q = [];
    w.ctc =
      w.ctc ||
      function () {
        q.push(arguments);
      };
    w.ctc.q = q;
    js = d.createElement(s);
    js.type = 'text/javascript';
    js.async = true;
    js.src =
      'https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js';
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, 'script');
  ctc('init', {
    checkoutConfig: {
      projectKey: '{projectKey}',
      region: '{region}',
      sessionId: '{sessionId}',
    },
  });
</script>

Calling the init method is optional. For further information, see init and checkout methods.

Versioning

The versioning of Checkout Browser SDK is handled through npm and follows the principles of semantic versioning.

When you load the script using https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js, @latest serves as an alias indicating that the latest version should be loaded.

For information on the available versions of Checkout Browser SDK, see this page.

npm module

Prerequisites

Node v12.22.7 (or later)
Either npm v6 (or later) or yarn v1.22.17 (or later)

Install the SDK package

To install the SDK package, run one of the following commands:

npm install @commercetools/checkout-browser-sdk
yarn add @commercetools/checkout-browser-sdk

npm script

Integrate Checkout as an npm moduleJavaScript

import { init } from '@commercetools/checkout-browser-sdk';

init({
  checkoutConfig: {
    projectKey: '{projectKey}',
    region: '{region}',
    sessionId: '{sessionId}',
  },
});

Calling the init method is optional. For further information, see init and checkout methods.

init and checkout methods

The init method lets you specify the configuration options that remain constant throughout the customer's website session, such as the region, projectKey, and sessionId. Additionally, it lets you subscribe to the Messages sent by Checkout. Since calling this method is optional and doesn't start the checkout process, any configuration parameters within the checkoutConfig object can be modified later, when calling the checkout method.
For the onInfo, onWarn, and onError handlers and the logInfo, logWarn, and logError functions, you must use the init method.

The checkout method is used to start the checkout process. At this stage, you must provide any missing information from the checkoutConfig object that wasn't previously provided with the init method. With the checkout method you can update the information you previously provided with the init method, but you cannot subscribe to the Messages sent by Checkout.

Call the 'checkout' method with the missing 'locale' parameterJavaScript

import { checkout } from '@commercetools/checkout-browser-sdk';

checkout({
  locale: '{locale}',
});

When calling the checkout method, the Checkout UI component for the specified sessionId opens. If the customer quits the checkout process before completing it, you can call this method again with the same sessionId, while it is still valid. If the session has expired, you can refresh it and open the Checkout UI component again by getting a new sessionId.

By default, when calling the checkout method, the Checkout UI component appears full screen in an absolutely positioned <div> element that hides other content on your page. The Checkout UI component renders a header with your preconfigured logo, the input fields, and the Leave checkout button. By clicking the Leave checkout button, the Checkout UI component disappears and the content of your page becomes visible again.

Otherwise, you can display the Checkout UI component inline with your content by using a <div> or <span> element with the data-ctc attribute in it (for example, <div data-ctc />). By doing so, the header and the Leave checkout button do not appear, and you can render any other content around the Checkout UI component, such as a custom header or footer.

Return URL

Some payment methods may require a redirection from your website to one of the payment service providers (PSP) to get information about the customer. In such cases, when you install a payment Connector, you must set a return URL to take the customer back to your website after the information has been retrieved. We recommend using the same URL as the one where the checkout process started; however, this is not mandatory.

You can only set one return URL per payment Connector. If you want to use the same payment Connector with multiple domains, you must create different Applications in the Merchant Center and override the return URL.

When information has been retrieved, the paymentReference parameter is added to the return URL with the id of the Payment as its value, and the customer returns to your website. Now, you must call the checkout method again by providing the same configuration parameters as before and the paymentReference.

Call the 'checkout' method with the 'paymentReference' parameterJavaScript

import { checkout } from '@commercetools/checkout-browser-sdk';

checkout({
  region: '{region}',
  projectKey: '{projectKey}',
  sessionId: '{sessionId}',
  locale: '{locale}',
  paymentReference: '{paymentReference}',
});

When calling the checkout method again, the Checkout UI component appears and displays a loading status while the payment is verified. If the payment is successful, the checkout process is complete. Otherwise, the customer is prompted to either quit the checkout process or try again by editing the entered information.

Checkout completion

Once the customer completes the checkout process successfully, the SDK closes Checkout and the CheckoutCompleted Message is generated. After this happens, you can determine how the checkout flow should continue by reacting to the Message.

You can react to the Message to display feedback for the customer on your website (for example, a message or a dialog). You can also use this Message to redirect the customer to a different URL (for example, a Thank you page).

React to CheckoutCompleted Message and redirect to Thank you pageJavaScript

import { subscribe } from '@commercetools/checkout-browser-sdk';

subscribe('info:app:status', (message) => {
  if (message.code === 'checkout_completed') {
    window.location.href = '/thank-you';
  }
});

React to Messages

The Messages from Checkout can be of three severity levels: info, warn, or error.

To react to these Messages, you can use:

The onInfo, onWarn, and onError handlers
The logInfo, logWarn, and logError methods
The subscribe method

onInfo, onWarn, and onError

You can subscribe to the info, warn, or error Messages by passing the optional onInfo, onWarn, or onError message handlers in the checkoutConfig object in the init method. The handlers will receive the message as a parameter.

In the following examples, we subscribe to all info Messages and log into the console a Received note followed by the message code.

Use 'onInfo' with the npm module to subscribe to info MessagesJavaScript

import { init } from '@commercetools/checkout-browser-sdk';

init({
  onInfo: (message) => {
    console.error('Received: ' + message.code);
  },
});

Use 'onInfo' with the browser script to subscribe to info MessagesHTML

<script>
  (function (w, d, s) {
    if (w.ctc) {
      return;
    }
    var js,
      fjs = d.getElementsByTagName(s)[0];
    var q = [];
    w.ctc =
      w.ctc ||
      function () {
        q.push(arguments);
      };
    w.ctc.q = q;
    js = d.createElement(s);
    js.type = 'text/javascript';
    js.async = true;
    js.src =
      'https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js';
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, 'script');

  ctc('init', {
    onInfo: function (message) {
      console.error('Received: ' + message.code);
    },
  });
</script>

logInfo, logWarn, and logError

You can use the logInfo, logWarn, and logError methods to log Messages in the console for debugging purposes. We recommend not enabling them in production since, usually, these logs are not useful for end users.

In the following examples, we log all the info and error Messages, but not the warn ones.

Use 'logInfo' and 'logError' with the npm module to log info and error MessagesJavaScript

import { init } from '@commercetools/checkout-browser-sdk';

init({
  logInfo: true,
  logWarn: false,
  logError: true,
});

Use 'logInfo' and 'logError' with the browser script to log info and error MessagesHTML

<script>
  (function (w, d, s) {
    if (w.ctc) {
      return;
    }
    var js,
      fjs = d.getElementsByTagName(s)[0];
    var q = [];
    w.ctc =
      w.ctc ||
      function () {
        q.push(arguments);
      };
    w.ctc.q = q;
    js = d.createElement(s);
    js.type = 'text/javascript';
    js.async = true;
    js.src =
      'https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js';
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, 'script');

  ctc('init', {
    logInfo: true,
    logWarn: false,
    logError: true,
  });
</script>

The SDK exposes a subscribe method that lets you pass a pattern matching a Message type and a handler function that will receive the Messages as a parameter if they match the specified pattern. You can add as many subscriptions as you want.

Following are the patterns that you can pass to subscribe to Messages.

Pattern	Description
`*`	Subscribe to all Messages.
`{level}:*`	Subscribe to all Messages of a specific level. For example, `info:`, `warn:`, or `error:*`.
`{level}:{entity}:*`	Subscribe to all Messages of a specific level and entity. For example, `error:init:*`.
`{level}:{entity}:{type}`	Subscribe to all Messages of a specific level, entity, and type. For example, `error:init:bad_config`.

In the following examples, we subscribe to all error Messages and define that an error consisting of the keyword Received and the Message code is displayed in the console when an error Message is received.

Use subscribe with the npm module to subscribe to all error MessagesJavaScript

import { subscribe } from '@commercetools/checkout-browser-sdk';

subscribe('error:*', (message) => {
  console.error('Received: ' + message.code);
});

Use subscribe with the browser script to subscribe to all error MessagesHTML

<script>
  (function (w, d, s) {
    if (w.ctc) {
      return;
    }
    var js,
      fjs = d.getElementsByTagName(s)[0];
    var q = [];
    w.ctc =
      w.ctc ||
      function () {
        q.push(arguments);
      };
    w.ctc.q = q;
    js = d.createElement(s);
    js.type = 'text/javascript';
    js.async = true;
    js.src =
      'https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js';
    fjs.parentNode.insertBefore(js, fjs);
  })(window, document, 'script');

  ctc('subscribe', 'error:*', function (message) {
    console.error('Received: ' + message.code);
  });
</script>