Website  • 
Api Docs  • 
Checkout Docs  • 
Help

@comgate/checkout-js

!NPM version 

@comgate/checkout-js is a JavaScript library for easily implement Comgate payment methods directly into the online store cart. It allows you to create a clean, non-disruptive design, including the payment processing directly in the online store.

The library is designed to be used in modern web applications and is compatible with most popular frontend frameworks and build tools.

$3

@comgate/checkout-js is loading wrapper and TypeScript types for @comgate/checkout.

> The @comgate/checkout package is currently deprecated, and all its functionality has been moved to this package.

Comgate Checkout SDK documentation

Comprehensive API documentation can be found on our website. It is used for custom implementation of online store connection to API. It contains CURL, PHP, JAVA, Python and C# examples.

The complete documentation for Comgate Checkout is available in our API documentation, in the '_Checkout SDK_' section.

Why use @comgate/checkout-js?

In the standard case, you have to insert the script into the page, wait for it to load, catch any errors, and then start using the available functions.

Whereas @comgate/checkout-js is a simple and secure way to asynchronously load the Comgate Checkout SDK. It provides a promise-based API for creating an instance of Comgate Checkout.

> 💡 If you still want to use direct script loading method, the example code that also handles potential script loading errors is available below in the section Using a CDN.

Installation

To get started, install @comgate/checkout-js with npm.

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

Usage

Import the loadComgateCheckout function for asynchronously loading the Comgate Checkout. Then it is possible to create an instance of Comgate Checkout by general documentation for this library.

$3

Prefetches the Comgate Checkout SDK script and returns a Promise that resolves when the script is successfully prefetched. Otherwise, it will reject the Promise with an error detail.

- Accepts an object with options
- Returns a Promise that resolves when the Comgate Checkout SDK script is prefetched

> ⚠️ Prefetching the Comgate Checkout SDK does not execute the script. It only loads the script into the browser cache. For executing the script, use the loadComgateCheckout function.

#### Promises

`javascript
import { prefetchComgateCheckout, MODULE_APPLEPAY, MODULE_GOOGLEPAY, /TPrefetchComgateCheckoutConfig, TPrefetchComgateCheckoutResult/ } from '@comgate/checkout-js';

const config /: TPrefetchComgateCheckoutConfig / = {
checkoutId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
modules: [MODULE_APPLEPAY, MODULE_GOOGLEPAY],
version: '@2', // fix only major version, not specific version
// callback after prefetch, the payload is same as return
// onPrefetch: (payload /: TPrefetchComgateCheckoutResult /) => {} value
};

prefetchComgateCheckout(config)
.then((res /: TPrefetchComgateCheckoutResult /) => {
if (res) {
// Comgate Checkout SDK prefetched
}
});
// never reject promise - only resolve with boolean (success)
`

#### Passing options

The prefetchComgateCheckout function takes an object as a configuration. The following options are available:

| Parameter | Type | Required | Default | Description |
|--------------|--------------------|----------|-------------|-------------------------------------------------------------------------------------------------------------|
| checkoutId | string | yes | | Comgate Checkout ID as UUID
_Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_ |
| modules | TModuleType[] | no | [] | Prefetche modules source. The core module is always preloaded. |
| version | TCheckoutVersion | no | "@2" | Comgate Checkout SDK version |
| timeout | number | no | 10000 | Maximum time in miliseconds for waiting to script prefetch
min: 500; max: 30000 |
| onPrefetch | Function | no | undefined | Alternative to resolved promise as a return value. Type (payload: TPrefetchComgateCheckoutResult) => void |

#### Return Promise

The prefetchComgateCheckout function always returns a Promise that resolves prefetching status.
Promise value is type of TPrefetchComgateCheckoutResult which is an object with the following properties:

| Parameter | Type | Required | Description |
|--------------|--------------------------------------------|----------|----------------------------------------------------------------------------------|
| checkoutId | string | yes | The value of the Comgate Checkout ID from the prefetchComgateCheckout options. |
| success | boolean | yes | Prefetch result status. |
| prefetched | TModuleType[] | yes | Successfully loaded modules |
| error | { [key in TModuleTypeExtended]?: Error } | no | Error details for each module. |

> ℹ️ TModuleTypeExtended is a union of TModuleType ('applepay', 'googlepay', 'core') and 'loader' string.

$3

#### Success
`json
{
"checkoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"prefetched": ["core", "applepay", "googlepay"],
"success": true
}
`
#### Error example
`json
{
"checkoutId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"prefetched": [],
"success": false,
"error": {
"core": {},
"applepay": {},
"googlepay": {}
}
}
`

$3

Loads the Comgate Checkout SDK asynchronously and returns a Promise that resolves when the Comgate Checkout SDK is successfully loaded. Otherwise, it will reject the Promise with an error.

- Accepts an object with options
- Returns a Promise that resolves when the Comgate Checkout SDK is loaded

#### Promises

`javascript
import loadComgateCheckout from '@comgate/checkout-js';

const checkoutId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

loadComgateCheckout({ checkoutId /, version, async, defer/ })
.then((res /: TComgateCheckoutLoadResult/) => {
// Comgate Checkout SDK loaded
})
.catch((error) => {
console.error('Comgate Checkout SDK loading error', error);
});
`

#### Async/Await snippet

#### Passing options

The loadComgateCheckout function takes an object as a configuration. The following options are available:

| Parameter | Type | Required | Default | Description |
| ------------ | --------- | -------- | ------- | ------------------------------------------------------------------------------- |
| checkoutId | string | yes | | Comgate Checkout ID as UUID
_Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_ |
| version | string | no | "@1" | Comgate Checkout SDK version |
| async | boolean | no | true | Load script asynchronously |
| defer | boolean | no | false | Load script deferred |
| timeout | number | no | 10000 | Maximum time in miliseconds for waiting to script load
min: 500; max: 30000 |

#### Return object

The loadComgateCheckout function returns a Promise that resolves to an object with the following properties:

| Parameter | Type | Required | Description |
| --------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| checkoutId | string | yes | The value of the Comgate Checkout ID from the loadComgateCheckout options. |
| ComgateCheckout | Function | yes | Function to create Comgate Checkout instance. Same function as window.COMGATE_SDK(). More information docs. |
| ComgateCheckoutMethodList | Function | yes | Create method list component instance without Comgate Checkout. Same function as window.COMGATE_SDK_METHOD_LIST() |
| ComgateCheckoutVersion | Function | yes | Get Comgate Checkout version. Same function as window.COMGATE_SDK_VERSION() |

$3

> ⚠️ Returns the @comgate/checkout-js version, not the Comgate Checkout SDK version.

Returns the version of the Comgate Checkout SDK loader.

- Returns an object with the version

`javascript
import { getLoaderVersion } from '@comgate/checkout-js';

const { version, revision } = getLoaderVersion();

console.log(Version is ${version}#${revision});
`

#### Return object

The getLoaderVersion function returns an object with the following properties:

| Parameter | Type | Required | Description |
| ---------- | -------- | -------- | --------------------------------- |
| version | string | yes | Version of @comgate/checkout-js |
| revision | string | no | Optional revision identifier. |

$3

Constant with available version shortcuts of the Comgate Checkout SDK.

`javascript
import { checkoutVersions } from '@comgate/checkout-js';

console.log(Available versions: , checkoutVersions);
// Available versions: [ '@1' ]
`

#### Variable structure

The constant checkoutVersions is an array of strings that indicate the available versions of the Comgate Checkout SDK.

Full example - import module

This snippet shows how to load the Comgate Checkout SDK and create an instance of Comgate Checkout.

`javascript
import loadComgateCheckout from '@comgate/checkout-js';

const checkoutId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
let checkoutInstanceRef;

loadComgateCheckout({ checkoutId /, version, async, defer / })
.then((res /: TComgateCheckoutLoadResult/) => {
// create Comgate Checkout instance
res.ComgateCheckout({
checkoutId: res.checkoutId,
locale: 'en', // (optional, default: cs) UI language
debug: true, // (optional, default: false) enable debug mode
transactionId: 'XXXX-XXXX-XXXX', // (req) Transaction ID
// ...
})
.then((checkoutInstance) => {
checkoutInstanceRef = checkoutInstance;
// instance ready
// TODO DIY
})
.catch((error) => {
// error during instance creation
// TODO DIY
});
})
.catch((error) => {
console.error('Comgate Checkout SDK loading error', error);
});
`

Using a CDN

The Comgate Checkout SDK is also available on a CDN. You can use it by adding the following script tag to your HTML file.

$3

This example is a simple solution that loads the script and waits for the ComgateCheckoutReady event.

> ⚠️ This solution does not handle potential script loading errors. We recommend using the safe & full-featured solution in production environments.

`html




`

$3

This example is a more complex solution that handles potential script loading errors. It also includes a timeout for the maximum time between the script load.

✅ We recommend using this solution in production environments.

`html




``

License

Copyright © Since 2024, Comgate a. s. Released under the EULA.