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.
<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
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.
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
.
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).
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:
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.
import { init } from '@commercetools/checkout-browser-sdk';init({onInfo: (message) => {console.error('Received: ' + message.code);},});
<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.
import { init } from '@commercetools/checkout-browser-sdk';init({logInfo: true,logWarn: false,logError: true,});
<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>
subscribe
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.
import { subscribe } from '@commercetools/checkout-browser-sdk';subscribe('error:*', (message) => {console.error('Received: ' + message.code);});
<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>