<p align="center" style="text-align: center; padding-top: 15px">
    <a href="https://www.comgate.cz/en">
        <img src="https://static.comgate.cz/assets/images/logo/cg-horr.svg" width="200px" alt="Comgate logo"/>
    </a>
</p>
<p align="center" style="text-align: center; margin: 0; padding: 5px 0 15px;">
    <a href="https://www.comgate.cz/en"><b>Website</b></a> &nbsp;•&nbsp;
    <a href="https://apidoc.comgate.cz/en/"><b>Api Docs</b></a> &nbsp;•&nbsp;
    <a href="https://apidoc.comgate.cz/checkout/uvod"><b>Checkout Docs</b></a> &nbsp;•&nbsp;
    <a href="https://help.comgate.cz/v1/en"><b>Help</b></a>
</p>

# @comgate/checkout-js

![NPM version](https://img.shields.io/npm/v/@comgate/checkout-js.svg?style=flat) [![npm downloads](https://img.shields.io/npm/dm/@comgate/checkout-js.svg?style=flat-square)](https://npm-stat.com/charts.html?package=@comgate/checkout-js)

[`@comgate/checkout-js`](https://www.npmjs.com/package/@comgate/checkout-js) is the official JavaScript loader for [Comgate Checkout](https://apidoc.comgate.cz/checkout/uvod).  
It provides a **secure, promise-based API** for loading and working with the Comgate Checkout SDK directly in your web application.

- ✅ Asynchronous loading with built-in error handling
- ✅ Full TypeScript typings out of the box
- ✅ Preload and cache SDK scripts before use
- ✅ Compatible with all modern bundlers and frameworks

> The legacy package [`@comgate/checkout`](https://www.npmjs.com/package/@comgate/checkout) is **deprecated**. All functionality is now included in `@comgate/checkout-js`.

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Difference between `@comgate/checkout-js` and `@comgate/checkout`](#difference-between-comgatecheckout-js-and-comgatecheckout)
- [Why use `@comgate/checkout-js`](#why-use-comgatecheckout-js)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Resources](#resources)
- [License](#license)

## Overview

`@comgate/checkout-js` allows developers to seamlessly integrate **Comgate Checkout** into web applications without manually handling `<script>` tags.  
The library ensures a smooth developer experience with:

- **Automatic script management** – load only what is needed.
- **TypeScript support** – full type definitions included.
- **Framework compatibility** – works with React, Vue, Angular, Svelte, or plain JavaScript.
- **Error resilience** – built-in timeouts and error handling.

## Installation

Install the package using your preferred package manager:

```sh
npm install @comgate/checkout-js
# or
yarn add @comgate/checkout-js
```

## Quick Start

### 1. Install the package

```sh
npm install @comgate/checkout-js
```

### 2. Load the Comgate Checkout SDK

Use the provided loader function. The loader handles script injection, caching, and error management.

### 3. Create a Checkout instance

Provide your `checkoutId` and `transactionId` to initialise the Checkout instance.

### 4. Create Apple Pay and Google Pay instances

Optionally initialise additional modules such as **Apple Pay** or **Google Pay** using the same SDK.


👉 Detailed integration guides and code examples are available in the official documentation:  
[Comgate Checkout SDK – Examples](https://apidoc.comgate.cz/checkout/examples)


## Difference between `@comgate/checkout-js` and `@comgate/checkout`

The package `@comgate/checkout-js` is the **recommended** way to integrate Comgate Checkout.  
It replaces the older `@comgate/checkout` package and provides:

- **Loader functionality** – handles script injection, caching, and error management.
- **TypeScript support** – all types are bundled directly in the package.
- **Promise-based API** – cleaner asynchronous flow.
- **Future maintenance** – only this package is actively maintained.

> ⚠️ The package [`@comgate/checkout`](https://www.npmjs.com/package/@comgate/checkout) is **deprecated**.  
> All its functionality has been migrated to `@comgate/checkout-js`.

## Why use `@comgate/checkout-js`?

When integrating Comgate Checkout you could insert a `<script>` tag manually, wait for it to load, handle errors, and then work with the global SDK.  
`@comgate/checkout-js` simplifies this process and adds several benefits:

- **Automatic script management** – no need to handle `<script>` tags yourself.
- **Promise-based API** – consistent and modern async handling.
- **Preloading support** – load SDK into cache before it is needed.
- **Error handling & timeouts** – built-in safeguards against failed or slow loads.
- **TypeScript support** – strong typing for better developer experience.
- **Framework agnostic** – works with React, Vue, Angular, Svelte, or vanilla JavaScript.
- **Actively maintained** – this is the officially supported loader package.


## API Reference

Full API reference, including detailed options and return types, is available in our official documentation:

👉 [Comgate Checkout SDK – API Reference](https://apidoc.comgate.cz/checkout/loader)

Please refer to the link above for the latest and complete specification.


## Examples

Practical integration examples (NPM, CDN with `<script>` tag) are available in our official documentation:

👉 [Comgate Checkout SDK – Examples](https://apidoc.comgate.cz/checkout/examples)

## Resources

- 🌐 [Comgate Website](https://www.comgate.cz/en)
- 📘 [Comgate API Docs](https://apidoc.comgate.cz/en/uvod)
- 💳 [Checkout SDK Docs](https://apidoc.comgate.cz/checkout/uvod)
- ❓ [Help Centre](https://help.comgate.cz/v1/en)

## License

Copyright © 2024–present [Comgate a. s.](https://www.comgate.cz/en)  
Released under the [EULA](https://checkout.comgate.cz/sdk/LICENSE_EULA.txt).
