Skip to main content

Architecture and operation

The Web Checkout SDK architecture is designed to make the SDK fast, flexible and easy to extend. The basic principle lies in separating the core (the Core module) from individual functional modules (Apple Pay, Google Pay, ...). Thanks to this, it is possible to load only those parts that the e-shop actually needs, thereby minimizing both load and the risk of errors.

Basic concept​

The Checkout SDK is built as a multi-layered modular system whose goal is to separate individual parts and minimize dependencies. The basic concept is based on three layers: Loader, Core and functional modules. The Loader represents the entry point of the entire library, Core provides shared infrastructure, and functional modules implement specific functionalities.

Structure​

  1. Loader (@comgate/checkout-js) is the only entry point of the entire library. Its task is to verify parameters based on the provided configuration, download the necessary modules from the Comgate CDN, and ensure their loading into the DOM in the correct order. It also performs, for example, version management. It thus functions as a control layer and is available either as a package on NPM or via the Comgate CDN.

  2. Core forms the basic layer of the SDK. It provides infrastructure shared by all modules — it manages events, logging and communication with the Comgate API. This module is not published separately and its minified code is distributed exclusively via the Comgate CDN.

  3. Functional modules are located under Core and each of them implements a specific functionality. The modules are independent, they are loaded separately and generally do not require additional dependencies on other modules. Like Core, they are not publicly published and their minified codes are provided via the Comgate CDN.

SDK architecture diagram – light modeSDK architecture diagram – dark mode

Module structure diagram

Architectural principles​

The design of the Checkout SDK is based on several key principles that determine how it is used and maintained:

  1. Modularity – each part of the SDK is independent and can be used independently of the others. Thanks to this, only the components that are actually needed are loaded, which reduces the amount of transmitted code and speeds up loading.

  2. Isolation – individual modules are separated, so a failure in one will not affect the functioning of the others. This ensures higher stability and easier debugging and maintenance.

  3. Distribution via CDN – the developer does not need to build or manually update the modules. They always have the current and optimized version available, which significantly simplifies deployment and operation. Comgate can also continuously deliver fixes and new features without the need for intervention on the part of the e-shop.

  4. Versioning – the SDK is published in different versions via CDN, with the ability to precisely define the desired major version (e.g. @2). The integrator can thus choose a stable version for the production environment and at the same time test the latest builds elsewhere. This facilitates migrations and minimizes the risk of unexpected changes.

Overall, this architecture brings speed, stability and flexibility, which are key for modern e-shops. The higher demands on implementation represent a certain price for these advantages, however the benefits significantly outweigh them and ensure that the Checkout SDK integration is sustainable in the long term and ready for extension with additional payment methods and features.

Operation​

After the Loader is loaded, the configuration is validated and Core is downloaded. During this process, individual functional modules are also downloaded, but they are not yet loaded into the DOM. Once Core has been successfully downloaded and loaded into the DOM, the individual functional modules are gradually loaded. Each module is inserted into the DOM separately and, after completing its initialization, announces its readiness. After all modules have been loaded, the Loader hands control back to the e-shop and signals that the SDK is ready for use.

At this point, the e-shop takes over control. First, a Core instance is created, followed by individual functional modules, which are mounted into the frontend. This adds all the necessary functionality of the Web Checkout SDK to the e-shop interface.

The e-shop is shielded from the internal functionality of the SDK and only affects it via the provided configuration. The Checkout SDK then invokes various handlers (callbacks), through which the e-shop is informed about the progress and, if necessary, waits for further instructions. We will explain this issue in more detail in the implementation section.