Standard Checkout

Make sure all of the steps from the initial checkout setup are completed before you start

Follow these steps to start the integration:

Web Component Integration
1. Loading the JavaScript bundle
2. Initialising the web component
Attributes
Methods
Configuration
Tracking
Loading Indicator
Events

Web Component Integration

How to integrate the checkout web component into your shop frontend

Begin by either creating a static page or modifying the existing start page of your shop application. Then, insert the following JavaScript snippet into the head element to load the Checkout bundle.

<script
  src="https://${tenant-space}.checkout.api.scayle.cloud/frontend/checkout-wc/js?appId=${shopId}"
  defer
></script>

This script registers the web component with the browser and loads necessary assets (CSS, images).

Initialising the web component

To initialise and display the web component, add the <scayle-checkout> tag at a desired place where the content needs to appear. Any additional element like a header or footer must be defined in the root document.

Example code how to set up the web component:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Your shop title</title>
  <script
    src="https://${tenant-space}.checkout.api.scayle.cloud/frontend/checkout-wc/js?appId=${shopId}"
    defer>
  </script>
</head>
<body>
<div id="header">...</div>
...
<scayle-checkout jwt="${jwt}" access-token="${accessToken}" origin="web" header-element="#header"></scayle-checkout>
...
</body>
</html>

Attributes


`jwt`	Contains `basketId`, etc. as encoded and signed parameter. Find out how to generate the token here. More details about the JWT .	required
`access-token`	The access token you receive after successful user authentication. Find out how to generate the token here.	required
`origin`	Defines where the user is coming from, can be `app` or `web`. Passing the correct value is mandatory, otherwise users might encounter problems with e.g. payment processing.	required
`header-element`	CSS selector pointing to the header element of the site (e.g. `#header`), used to display Checkout notifications with the correct top offset (under the header)	required
`has-cookie-consent`	Contains the value of the user's cookie consent. Only enabled when the value resolves to 'true'. It unlocks in-depth error tracking, A/B testing, etc. We strongly recommend adding it to the web component and passing in the correct cookie consent value.	required

Note: All these attributes need to be set on the web component from the very start. If you mount the component first and then set e.g. the basket-id attribute afterward, it will not be considered and not work correctly.

JWT attribute

To ensure integrity, you need to provide the jwt attribute containing an encoded JSON payload. The value of the jwt attribute has to be a common JWT (JSON web token) string. The payload of the JWT contains the properties likes basketId to initialise the checkout. The JWT is then signed with the shopSecret. Find the example here.

Name	Description	Type
`iss`	Identifies the principal that issued the token. It is typically a unique identifier or URL of the service responsible for generating the token. The recipient of the token can use this field to verify the authenticity of the issuer. See example.	optional
`aud`	Intended recipients of the token. It is used to ensure that the token is only accepted by the services or users that are authorized. The value is typically a unique identifier or URI representing the audience. See example.	optional
`iat`	issued at / current unix timestamp	required
`nbf`	not-valid-before unix timestamp	optional
`exp`	expiry unix timestamp	required
`basketId`	sets the current basket id of the active session	required
`rBasketId`	salted hash of basketId for rate-limiting purposes	optional
`customData`	sets order-level custom data, must be a JSON string	optional
`carrier`	sets preferred Carrier Group	optional
`campaignKey`	set an active campaign, so that corresponding price-reductions are displayed in the checkout cart	optional
`preferredCollectionPoint`	sets preferred collection point data as `object`	optional
`preferredCollectionPoint.id`	collection point id	optional
`preferredCollectionPoint.type`	collection point type. e.g. `dhl_packstation`	optional
`voucher`	sets an pre-applied voucher code	optional

If you require a more advanced configuration of your JWT parameters, please view the documentation.

Configuration

You can customise Checkout for your shops via the SCAYLE Panel. For details, follow the Configure & Customization section of this guide.

Tracking

Tracking events will be sent to the same Google Tag Manager (GTM) instance as the frontend application and the events will be attached to the same data layer object (window.dataLayer).

This section is important for the customers hosting their own storefront. For all other clients, this step is done by SCAYLE.

Your shop frontend is responsible for implementing the connection with the GTM (Google Tag Manager) and the corresponding data layer. It's crucial to ensure the correct data layer setup. To achieve this, insert the given code segment at the top of the page, just before initializing the checkout.

<script>
  window.dataLayer = window.dataLayer || [];
</script>

Add the following into your code to forward the events:

import { find } from 'lodash-es';

window.addEventListener('message', function receiveMessage(message) {
  const event = message.data.event;
  // avoid duplicate tracking of events
  if (message.data.type === 'tracking' && !find(window.dataLayer, event)) {
    // forward CHECKOUT tracking events to GTM
    window.dataLayer.push(event);
  }
}, false);

For more details and available events see the tracking overview.

Loading Indicator

You can optionally improve the UX for customers with slow internet connection by implementing a custom loading indication on the page that renders the checkout application, within the <body> tag.

SCAYLE does not provide a custom loading animation, so it's up to you to design and implement the loading-indicator. Below, we only show how a sample implementation could look like.

Example HTML Code:

<!DOCTYPE html>
<html>
 <head>
  <!--  all the resources your checkout rendering page needs -->
 </head>
 <body>
  <header id="sampleHeader"> <!-- A header id we pass to the 'header' attribute of scayle-checkout with # sign, in order to properly position notifications and modals -->
   <a href="#">Sample link</a>
  </header>
  <div class="sample-checkout-wrapper"> <!--Just an example container -->
   <!-- Your custom loading animation goes here -->
   <div class="loading-indicator" id="loading-indicator">...</div> <!-- Your custom loading indicator, you may want to add some css to showcase some animations -->
    <!-- Your custom loading animation ends here -->
   <scayle-checkout jwt="${jwt}" origin="web" header="#sampleHeader" style="display: none;"></scayle-checkout>
 </div>
 </body>
</html>

Example JS Code

The code below does two things:

It listens for the load event emitted by the checkout application upon successful initialization, while also monitoring for the error event in case anything goes wrong during app bootstrap.
It sets the display CSS property of both <scayle-checkout> and #loading-indicator elements to show the checkout and hide custom loading indicator.

The script below can be added at the bottom of your body tag:

<!DOCTYPE html>
<html>
 <head>
 
 </head>
 <body>
   <!--- All the HTHL described above, <scayle-checkout>, loading-indicator etc -->
   
   <!--- Start of the script -->
   <script>
    const loadingIndicator = document.getElementById('loading-indicator');
    const checkoutWebComponent = document.getElementsByTagName('scayle-checkout')[0];
    const onLoad = () => {
      loadingIndicator.style.display = 'none';
      checkoutWebComponent.style.display = 'block';
    };
    checkoutWebComponent.addEventListener('load', onLoad);
    checkoutWebComponent.addEventListener('error', () => {
      console.error('Checkout web  component is experiencing difficulties...');
      onLoad();
    });
   </script>
   <!--- End of the script -->
 </body>
</html>

Methods

The Checkout web component provides a method to update the used basket ID (string) via setBasketId:

const checkoutWebComponent = document.getElementsByTagName('scayle-checkout')[0];
// Update the basket ID of the current Webcomponent instance
checkoutWebComponent.setBasketId('${newBasketId}');

Events

The Checkout web component can notify the parent shop frontend about specific events or user actions. Your application can subscribe to these events by adding a listener, as shown in the below example:

const checkoutWebComponent = document.getElementsByTagName('scayle-checkout')[0];

checkoutWebComponent.addEventListener('authenticate', e => {
  // evt.detail property contains payload data
  // Use it to provide feedback to users, update app state
...
});

The event listener needs to be added within the page where you load your Checkout bundle.

You can find the event details in the table below. The list of event types may be extended in the future.

Event Name	Description	Trigger
`load`	Use this if you want to show your own loading indicator until the component is ready	Checkout has loaded all data for initial render
`error`	An error state will be rendered by the Webcomponent. The load event will not be triggered in this case	Checkout has loaded all data for initial render, but there was an unrecoverable error
`intentConfirmation`	Customer has made the decision to buy / intents to confirm the order	Customer clicks the "Pay Now" button
`invalid-access-token`	When this event is sent, the storefront should refresh the access token and replace the access-token attribute on the web component with the new one. The checkout will then retry the failed request with the newly injected token.	The access token used to authenticate the user is expired
`authenticate`	Deprecated This event is fired to inform the shop frontend that a user has logged in or registered during checkout	User logs in or signs up via Checkout

	Example/default
Checkout	`/checkout`
Order Success Page (OSP)	`/order/success`
Example URL	`https://<shopName.domain>/order/success?cbd=<base64EncodedToken>`