Přeskočit na hlavní obsah

Implementace

Tato stránka vás provede kompletní integrací Checkout SDK do vašeho e-shopu. Jedno volání useCheckout() pokryje celý platební flow — od vykreslení formuláře až po zpracování Apple Pay nebo Google Pay a platby kartou.

Instalace​

Checkout SDK lze do projektu přidat dvěma způsoby — pomocí dependency manageru nebo načtením z Comgate CDN.

Dependency manager​

Použijte, pokud spravujete závislosti pomocí npm, yarn nebo pnpm a projekt sestavujete prostřednictvím bundleru (Vite, Webpack, Next.js, …).

Tip

Balíček @comgate/checkout-js obsahuje pouze zavaděč (loader) — samotné SDK se stahuje dynamicky za běhu. I přesto doporučujeme pravidelně kontrolovat dostupnost nových verzí a balíček aktualizovat, aby vám neunikly důležité opravy a vylepšení.

npm install @comgate/checkout-js

Comgate CDN​

Pokud nechcete využívat dependency managery, lze SDK načíst přímo z Comgate CDN. Po načtení je knihovna dostupná globálně jako window.comgateCheckoutJs.

<!DOCTYPE html>
<html lang="cs">
<head>
  <meta charset="UTF-8">
  <title>Comgate Checkout example - script in body</title>
  <!-- ... metas ... -->
</head>
<body>
<!-- ... content ... -->
<script src="https://checkout.comgate.cz/sdk/@3"></script>
<script>
  if (window.comgateCheckoutJs) {
    const comgateLoaderVersion = comgateCheckoutJs.getLoaderVersion();
    console.log(comgateLoaderVersion.version);
  }
</script>
</body>
</html>

Práce s verzemi​

Pro produkční nasazení doporučujeme používat fixní major verzi. Comgate garantuje zpětnou kompatibilitu v rámci stejné major verze, takže opravy a vylepšení se dostávají k uživatelům automaticky.

  • CDN: Použijte major verzi v URL (např. /sdk/@3)
  • NPM: Použijte parametr version v konfiguraci useCheckout(), preloadComgateCheckout() nebo prefetchComgateCheckout() — lze předat řetězec nebo importovanou konstantu.
<!-- Fixní major verze v URL — doporučeno pro produkci -->
<script src="https://checkout.comgate.cz/sdk/@3"></script>

<!-- Konkrétní patch verze — nedoporučujeme - vhodné pro testování/vývoj -->
<script src="https://checkout.comgate.cz/sdk/v/3.0.1"></script>

Uzamčení na konkrétní patch verzi (např. 3.0.1) důrazně nedoporučujeme.

Příprava HTML​

Po instalaci knihovny je dalším krokem příprava HTML struktury. Před voláním useCheckout() připravte na stránce kontejnerové elementy pro jednotlivé platební metody, které plánujete využívat.

Apple Pay a Google Pay​

Pro každou metodu připravte prázdný <div>, do kterého SDK vykreslí nativní tlačítko. Tlačítka se automaticky přizpůsobují rozměrům kontejneru — velikost tedy určujete vaším vlastním stylem elementu. Každému elementu přiřadte též unikátní ID.

Unikátní selektor

Každý mountPoint (Apple Pay, Google Pay i karta) musí odpovídat právě jednomu elementu v DOM. Pokud selektor najde více prvků, SDK vyhodí chybu. Používejte proto selektor s ID (např. '#cg-applepay-box') nebo předejte přímo referenci na konkrétní HTMLDivElement.

Element musí být v DOM v okamžiku volání useCheckout(). Ve frameworcích (Vue, React, Angular…) proto volejte useCheckout() vždy až po připojení komponenty do DOM — typicky uvnitř onMounted (Vue) nebo useEffect (React). SDK toleruje krátké zpoždění způsobené render cyklem frameworku, ale nespolehejte se na to jako na náhradu správné lifecycle integrace.

Ukázka kontejnerů pro Apple Pay a Google PayUkázka kontejnerů pro Apple Pay a Google Pay
<div id="cg-applepay-box" style="width: 240px; height: 45px;"></div>
<div id="cg-googlepay-box" style="width: 240px; height: 45px;"></div>

Doporučené rozměry​

Při implementaci obou metod volte sjednocené rozměry, které vyhoví oběma službám. Níže jsou minimální a doporučené velikosti — Google Pay má přísnější minima:

TypApple Pay min.Google Pay min.Doporučená
Desktopjen logo (plain)100 × 30 px140 × 40 px160 × 45 px
s textem140 × 30 px240 × 40 px240 × 45 px
Mobiljen logo (plain)100 × 30 px140 × 40 px160 × 50 px
s textem140 × 30 px240 × 40 px240 × 50 px
Tip

Nezapomeňte na viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1">.

Karetní formulář​

Pro platbu prostřednictví karetního formuláře potřebujete na stránce připravit kontejnerový element — <div> s libovolným ID, na který v konfiguraci odkážete pomocí mountPoint (CSS selektor, např. '#cg-card-box', nebo přímý odkaz na HTMLDivElement).

SDK z ID elementu automaticky hledá další elementy:

  • ${id}-ibox → sem SDK vloží zabezpečený iframe s poli karty (element je povinný a musí být vložený uvnitř hlavního div)
  • ${id}-button → wrapper pro <button>, SDK ho napojí na platbu (může být i mimo kontejner)
Informace

Vstupní pole karty běží v izolovaném iframe — citlivá data nikdy neopustí zabezpečené prostředí → PCI-DSS compliance.

Tlačítko může být umístěné uvnitř kontejneru, ideálně pod iframe s poli karty:

<div id="cg-card-box">
    <div id="cg-card-box-ibox"><!-- iframe s poli karty --></div>
    <div id="cg-card-box-button">
        <button type="button">Zaplatit kartou</button>
    </div>
</div>

CSS Styl​

SDK automaticky vkládá výchozí styly karetního kontejneru při mountování — není potřeba přidávat žádné vlastní CSS. Možnosti přizpůsobení jsou popsány v sekci Přizpůsobení vzhledu — Karetní formulář.

Loading stav (před načtením SDK)​

Do doby, než se SDK stihne načíst a spustit, se kontejner zobrazí jako prázdný prostor. Pokud chcete místo prázdného prostoru zobrazit loading spinner, je to možné — podrobnosti najdete níže v sekci Loading stav karetního formuláře.

Tip

Loading stav je volitelný — pokud vám prázdný prostor před načtením nevadí, není potřeba nic implementovat.

Nejdříve ale implementujte SDK a až poté přidejte vlastní styly nebo loading spinner.

Implementace​

Jakmile máte HTML elementy připravené, můžete přejít k samotné inicializaci SDK. Funkce useCheckout() je váš hlavní (a vlastně jediný) vstupní bod. Zavoláte ji s konfiguračním objektem, ona udělá vše potřebné — načte moduly, vykreslí UI — a vrátí vám Promise s instancemi jednotlivých modulů.

Zjednodušené flow procesu: Váš backend / cloud app založí platbu na Comgate Merchant API, které vám vrátí transId. Toto ID spolu s checkoutId (získáte v klientském portálu při aktivaci Checkout SDK) předáte na váš frontend do volání funkce useCheckout(). SDK inicializuje platební metody, vykreslí tlačítka a formuláře, a až zákazník zaplatí, zavolá váš callback.

Upozornění pro SPA

Modul Core je implementován jako singleton. Instance vzniká při prvním volání useCheckout() a zůstává aktivní až do ukončení / obnovení stránky.

Další volání useCheckout() nevytvářejí novou instanci modulu Core, ale pouze aktualizují předané callbacky (například onPaid nebo onCancelled). Dříve předané callbacky se tím nahradí a aktivní zůstávají vždy pouze callbacky předané při posledním volání useCheckout().

Při opuštění platební stránky je nutné zavolat destroy() na instancích modulů Apple Pay, Google Pay a karty — jinak zůstanou aktivní v paměti a mohou způsobovat konflikty při dalších zpracováních plateb. Více informací je v sekci Úklid instancí.

import { useCheckout } from '@comgate/checkout-js';

const COMGATE_CHECKOUT_ID = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
const COMGATE_TRANSACTION_ID = 'XXXX-XXXX-XXXX';
const GOOGLE_PAY_MERCHANT_ID = 'BCR3D****ZEY1LKS';

const CHECKOUT_BOX_GOOGLE_PAY = '#cg-googlepay-box';
const CHECKOUT_BOX_APPLE_PAY = '#cg-applepay-box';
const CHECKOUT_BOX_CARD = '#cg-card-box';

useCheckout({
    checkoutId: COMGATE_CHECKOUT_ID,
    core: {
        transactionId: COMGATE_TRANSACTION_ID,
        locale: 'cs',
        onPaid:      (payload) => { console.log('Zaplaceno', payload); },
        onCancelled: (payload) => { console.log('Zrušeno', payload); },
        onPending:   (payload) => { console.warn('Opakujte platbu', payload); },
        onError:     (payload) => { console.error('Chyba', payload); },
        onPaymentStarted: () => { document.body.classList.add('loading'); },
        onPaymentStopped: () => { document.body.classList.remove('loading'); },
    },
    // pokud nechcete ApplePay, tento klíč vynechte
    applepay: {
        mountPoint: CHECKOUT_BOX_APPLE_PAY,
    },
    // pokud nechcete GooglePay, tento klíč vynechte
    googlepay: {
        mountPoint: CHECKOUT_BOX_GOOGLE_PAY,
        payment: {
            // Merchant ID, které vám přidělí Google po registraci u&nbsp;Google Pay Business Console.
            // Pro testování není potřeba, ale pro produkční nasazení je povinný.
            // DIY
            googlePayMerchantId: GOOGLE_PAY_MERCHANT_ID
        }
    },
    // pokud nechcete kartu, tento klíč vynechte
    card: {
        mountPoint: CHECKOUT_BOX_CARD,
    },
})
.then((result) => {
    console.log('Checkout result', result);

    if (result.applepay && !result.applepay.success) {
        document.querySelector(CHECKOUT_BOX_APPLE_PAY).style.display = 'none';
    }
    if (result.googlepay && !result.googlepay.success) {
        document.querySelector(CHECKOUT_BOX_GOOGLE_PAY).style.display = 'none';
    }
    if (result.card && !result.card.success) {
        document.querySelector(CHECKOUT_BOX_CARD).style.display = 'none';
    }
})
.catch((error) => {
    console.error('Unexpected error', error);
});

Výsledek inicializace​

Funkce useCheckout() vrací Promise<TUseCheckoutResult>. Výsledek obsahuje stav celé inicializace i jednotlivých modulů.

Struktura odpovědi​

interface TUseCheckoutResult {
    success: boolean;
    core:       TUseCheckoutModuleResult<CheckoutCore>;
    applepay?:  TUseCheckoutModuleResult<ModuleApplePay>;
    googlepay?: TUseCheckoutModuleResult<ModuleGooglePay>;
    card?:      TUseCheckoutModuleResult<ModuleCard>;
}

interface TUseCheckoutModuleResult<T> {
    success: boolean;
    error?: string;
    instance: T | null;
}

Jak interpretovat výsledek​

Po úspěšném vyřešení Promise vrátí useCheckout() objekt typu TUseCheckoutResult. Objekt obsahuje celkový příznak success a samostatný výsledek inicializace pro každý modul, který jste zahrnuli do konfigurace — tedy pro každý klíč (applepay, googlepay, card), který jste předali do useCheckout(). Moduly, které jste v konfiguraci vynechali, nebudou ve výsledku přítomny.

Situaceresult.successresult.[modul].successCo dělat
Vše OKtruetrue u všechPlatební metody jsou připraveny, není potřeba nic řešit.
Některý modul selhal (AP/GP/karta nedostupná, element nenalezen…)falsefalse u dotčeného moduluPromise se splní. Zkontrolujte result.[modul].error — zjistíte příčinu. Skryjte nebo deaktivujte nedostupnou platební metodu.
Kritická chyba (neplatné checkoutId, Core selhal, síťový problém)––Promise se zamítne — výsledný objekt nevznikne vůbec. Zpracujte v bloku catch.
Tip

Klíč modulu (applepay, googlepay, card) je ve výsledku přítomen pouze tehdy, pokud jste daný modul zahrnuli do konfigurace. Pokud jste např. nepředali klíč applepay, bude result.applepay rovno undefined.

Vlastnosti výsledku modulu​

Každý modul vrací objekt TUseCheckoutModuleResult<T> se třemi vlastnostmi:

VlastnostTypPopis
successbooleantrue — modul byl načten, zařízení jej podporuje a UI bylo vykresleno do zadaného mount pointu. false — inicializace selhala, viz error.
errorstring | undefinedPopis příčiny selhání, přítomen pouze při success: false. Příklady: "Apple Pay is not available on this device", "Element \"#cg-applepay-box\" not found", ...
instanceT | nullReference na instanci modulu. Při success: true obsahuje aktivní instanci. Při success: false může být null (modul se ani nevytvořil) nebo obsahovat částečně inicializovanou instanci.

Příklad zpracování​

import { useCheckout } from '@comgate/checkout-js';

try {
    const result = await useCheckout({
        checkoutId: COMGATE_CHECKOUT_ID,
        core: { transactionId: COMGATE_TRANSACTION_ID, onPaid, onCancelled, onPending, onError },
        applepay:  { mountPoint: '#cg-applepay-box' },
        googlepay: { mountPoint: '#cg-googlepay-box', payment: { googlePayMerchantId: GP_MERCHANT_ID } },
        card:      { mountPoint: '#cg-card-box' },
    });

    // Core je vždy úspěšný, pokud Promise neskončil výjimkou
    console.log('Core inicializován', result.core.instance);

    // Zkontrolujte result.success pro rychlý přehled, zda vše proběhlo v pořádku
    if (!result.success) {
        console.warn('Některý modul se nepodařilo inicializovat');
    }

    // Apple Pay — může být nedostupný na zařízení
    if (result.applepay?.success) {
        console.log('Apple Pay připraven');
    } else if (result.applepay) {
        console.warn('Apple Pay nedostupné:', result.applepay.error);
        document.getElementById('cg-applepay-box').style.display = 'none';
    }

    // Google Pay — může být nedostupný na zařízení
    if (result.googlepay?.success) {
        console.log('Google Pay připraven');
    } else if (result.googlepay) {
        console.warn('Google Pay nedostupné:', result.googlepay.error);
        document.getElementById('cg-googlepay-box').style.display = 'none';
    }

    // Karetní formulář
    if (result.card?.success) {
        console.log('Karetní formulář vykreslen');
    } else if (result.card) {
        console.warn('Karetní formulář nedostupný:', result.card.error);
    }
} catch (error) {
    // Kritická chyba — SDK se nepodařilo inicializovat
    console.error('Checkout inicializace selhala:', error);
}

Úklid instancí​

Povinné pro SPA

Pokud vaše aplikace používá client-side routing (Vue Router, React Router, Next.js App Router apod.), musíte při opuštění platební stránky zavolat destroy() na všech modulech. Bez toho zůstávají staré instance Apple Pay, Google Pay a karetního formuláře v paměti, mohou reagovat na budoucí události a způsobovat konflikty při dalším zpracování plateb.

Metoda destroy() odstraní vykreslené UI (iframe, tlačítka), odpojí event listenery a uvolní prostředky modulu. Je dostupná na instancích modulů applepay, googlepay a card. Na instanci Core se destroy() nevolá — Core je singleton a jeho životní cyklus řídí SDK samo.

const result = await useCheckout({ /* ... */ });

// Při opuštění platební stránky zavolejte destroy na všech modulech:
function cleanup() {
    result.applepay?.instance?.destroy();
    result.googlepay?.instance?.destroy();
    result.card?.instance?.destroy();
    // => na CORE se destroy nevolá
}

// Vue 3
onUnmounted(() => cleanup());

// React
useEffect(() => {
    return () => cleanup();
}, []);

Po zavolání destroy() nelze instanci modulu znovu použít — pro novou platbu je nutné zavolat useCheckout() znovu.

Upozornění

Používejte pouze funkce a metody popsané v této dokumentaci. SDK obsahuje interní prvky, které nejsou určeny pro veřejné použití. Jejich využití není podporováno a může vést k nefunkčnosti SDK.

Další funkce​

Některé funkce SDK pracují automaticky na pozadí, jiné lze volitelně ovládat. Níže jsou popsány ty nejdůležitější.

3D Secure​

Při platbě kartou může banka zákazníka vyžadovat dodatečné ověření pomocí 3D Secure. 3D Secure je zcela v režii SDK — není potřeba žádná dodatečná implementace.

Pokud banka vyžaduje dodatečné ověření (3D Secure), SDK automaticky zvolí nejvhodnější metodu zobrazení:

  1. iframe modal — pokud je ověřovací stránka banky zobrazitelná v iframe, SDK ji zobrazí přímo na stránce. Pokud se iframe nepodaří načíst, SDK přejde na přesměrování.
  2. Nové okno (popup) — pokud banka neumožňuje zobrazení v iframe, SDK otevře nové okno. Pokud je popup zablokován prohlížečem, SDK přejde na přesměrování.
  3. Přesměrování — záložní metoda pro oba scénáře výše. Zákazník je přesměrován na stránku banky.

V případě přesměrování je zákazník po dokončení ověření vrácen na jednu z URL nastavených v klientském portálu:

  • URL zaplacený — platba úspěšná,
  • URL zrušený — platba zrušena,
  • URL nevyřízený — zákazník může platbu zopakovat.

Click to Pay​

Informace

Na podpoře Click to Pay se intenzivně pracuje. Funkce bude dostupná v jedné z budoucích verzí SDK.

Click to Pay umožní zákazníkům platit uloženou kartou bez nutnosti zadávat číslo karty znovu. Po implementaci bude automatickou součástí karetního formuláře — bez nutnosti dodatečné konfigurace.

Debug mode​

Předáním debug: true v konfiguraci aktivujete rozšířené logování do konzole prohlížeče. SDK vypisuje barevně označené zprávy s prefixem [ComgateCheckout], které pomáhají při diagnostice problémů.

useCheckout({
    checkoutId: COMGATE_CHECKOUT_ID,
    debug: true, // zapne rozšířené logování
    core: { /* ... */ },
    card: { mountPoint: '#cg-card-box' },
});
Upozornění

Debug mode nepoužívejte v produkci — výpisy mohou obsahovat citlivé informace o průběhu inicializace.

Informace o verzi​

Pro diagnostiku a logování lze zjistit verzi loaderu i jednotlivých načtených modulů.

Verze loaderu je dostupná přes exportovanou funkci getLoaderVersion():

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

const { version, revision } = getLoaderVersion();
console.log('Loader:', version, revision);

Verze jednotlivých modulů jsou dostupné přes globální objekt window.comgate.checkout po dokončení inicializace. Každý modul (Core, Apple Pay, Google Pay, Card) vystavuje metodu version():

// Verze modulů jsou dostupné po vyřešení useCheckout()
await useCheckout({ /* ... */ });

const checkout = window.comgate?.checkout;
console.log('Core version:      ', checkout?.core?.version());
console.log('Apple Pay version: ', checkout?.applepay?.version());
console.log('Google Pay version:', checkout?.googlepay?.version());
console.log('Card version:      ', checkout?.card?.version());
Tip

Hodnoty version() modulů jsou dostupné pouze tehdy, pokud byl daný modul úspěšně načten. Pokud modul nebyl zahrnut do konfigurace nebo selhalo jeho načítání, příslušná vlastnost (checkout.applepay apod.) nebude přítomna.

Přednačtení SDK​

Kdy použít kterou funkci?
FunkcePrioritaPoužití
prefetchComgateCheckout()Nízká (prefetch)Zákazník možná bude platit — košík, produktová stránka.
preloadComgateCheckout()Vysoká (preload)Zákazník určitě bude platit — souhrn objednávky, platební krok.

preloadComgateCheckout()​

Předběžně načte skripty SDK do cache prohlížeče prostřednictvím <link rel="preload">. Skripty se nespustí — jen se uloží, aby následné volání useCheckout() bylo rychlejší.

Vhodné pro stránky, kde víte, že zákazník brzy přejde na platební krok (např. shrnutí objednávky).

import {
    preloadComgateCheckout,
    MODULE_APPLEPAY,
    MODULE_GOOGLEPAY,
    MODULE_CARD
} from '@comgate/checkout-js';

preloadComgateCheckout({
    checkoutId: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',
    modules: [MODULE_APPLEPAY, MODULE_GOOGLEPAY, MODULE_CARD],
    version: '3',
    onPreload: (result) => {
        console.log('Preload dokončen:', result.preloaded);
    },
})
.then((result) => {
    if (result.success) {
        console.log('Všechny moduly předem načteny:', result.preloaded);
    }
});

Parametry​

ParametrTypPovinnýDefaultPopis
checkoutIdstringAno–UUID v4 přidělené Comgatem. Identifikuje váš e-shop. Formát: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
modulesTModuleType[]Ano–Moduly k předběžnému načtení. Povolené hodnoty: MODULE_APPLEPAY ('applepay'), MODULE_GOOGLEPAY ('googlepay'), MODULE_CARD ('card'), MODULE_CORE ('core'). Musí obsahovat alespoň jeden modul (kromě core). Core je vždy zahrnut automaticky.
versionstringNe'3'Verze SDK. Doporučujeme fixní major verzi (např. '3'). Povolené hodnoty: '2', '3', nebo konkrétní semver ('2.x.x', '3.x.x'). Verze 1 není podporována.
debugbooleanNefalseZapne rozšířené logování do konzole prohlížeče.
onPreload(payload: TPreloadComgateCheckoutResult) => voidNeundefinedAlternativní callback volaný po dokončení přednačtení. Payload je shodný s návratovou hodnotou Promise.
Tip

Parametr onPreload je alternativou ke zpracování výsledku přes .then(). Obě varianty lze kombinovat — callback je zavolán vždy jako první.

AtributTypPopis
checkoutIdstringPředané checkoutId.
successbooleantrue pokud byly všechny požadované moduly úspěšně načteny do cache.
preloadedTModuleType[]Pole názvů úspěšně předem načtených modulů (např. ['core', 'applepay', 'googlepay']).
error{ [key in TModuleTypeExtended]?: Error }Detaily chyb pro jednotlivé moduly. Klíč je název modulu ('core', 'applepay', 'googlepay', 'card', 'loader'), hodnota je instance Error. Přítomen pouze pokud některý modul selhal.

Chybové stavy​

Promise se zamítne (reject) pokud:

  • checkoutId není validní UUID v4
  • modules není pole nebo neobsahuje žádný modul (mimo core)
  • Některý z požadovaných modulů se nepodařilo předem načíst

V případě zamítnutí je payload totožný s TPreloadComgateCheckoutResult, ale success je false a pole error obsahuje detaily.

prefetchComgateCheckout()​

Vloží do stránky <link rel="prefetch"> pro skripty SDK. Prohlížeč je stáhne s nízkou prioritou ve volném čase — na rozdíl od preloadComgateCheckout() nebude stahování blokovat aktuální rendering ani soutěžit s kritickými zdroji.

Vhodné pro stránky, kde zákazník možná přejde na platbu, ale zatím není jisté (např. produktová stránka, košík před souhrnem).

import {
    prefetchComgateCheckout,
    MODULE_APPLEPAY,
    MODULE_GOOGLEPAY,
    MODULE_CARD
} from '@comgate/checkout-js';

prefetchComgateCheckout({
    checkoutId: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',
    modules: [MODULE_APPLEPAY, MODULE_GOOGLEPAY, MODULE_CARD],
    version: '3',
    onPrefetch: (result) => {
        console.log('Prefetch dokončen:', result.prefetched);
    },
})
.then((result) => {
    if (result.success) {
        console.log('Všechny moduly prefetchnuty:', result.prefetched);
    }
});

Parametry​

ParametrTypPovinnýDefaultPopis
checkoutIdstringAno–UUID v4 přidělené Comgatem. Identifikuje váš e-shop. Formát: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
modulesTModuleType[]Ano–Moduly k prefetchnutí. Povolené hodnoty: MODULE_APPLEPAY ('applepay'), MODULE_GOOGLEPAY ('googlepay'), MODULE_CARD ('card'), MODULE_CORE ('core'). Musí obsahovat alespoň jeden modul (kromě core). Core je vždy zahrnut automaticky.
versionstringNe'3'Verze SDK. Doporučujeme fixní major verzi (např. '3'). Povolené hodnoty: '2', '3', nebo konkrétní semver ('2.x.x', '3.x.x'). Verze 1 není podporována.
debugbooleanNefalseZapne rozšířené logování do konzole prohlížeče.
onPrefetch(payload: TPrefetchComgateCheckoutResult) => voidNeundefinedCallback volaný po dokončení prefetche. Payload je shodný s návratovou hodnotou Promise.
Tip

Parametr onPrefetch je alternativou ke zpracování výsledku přes .then(). Obě varianty lze kombinovat — callback je zavolán vždy jako první.

AtributTypPopis
checkoutIdstringPředané checkoutId.
successbooleantrue pokud byly všechny požadované moduly úspěšně prefetchnuty.
prefetchedTModuleType[]Pole názvů úspěšně prefetchnutých modulů (např. ['core', 'applepay', 'googlepay']).
error{ [key in TModuleTypeExtended]?: Error }Detaily chyb pro jednotlivé moduly. Přítomen pouze pokud některý modul selhal.

Konfigurační reference​

Kompletní přehled všech konfiguračních parametrů, které lze předat do useCheckout(). Každá platební metoda má vlastní sadu nastavení — povinný je pouze checkoutId a objekt core.

TUseCheckoutConfig​

AtributTypPovinnýPopis
checkoutIdstringAnoUUID v4 přidělené Comgatem. Identifikuje váš e-shop.
versionstringNeVerze SDK. Default '3'. Doporučujeme fixní major verzi (např. '3'). Povolené hodnoty: '2', '3', nebo konkrétní semver ('3.x.x'). Verze 1 není podporována.
coreTUseCheckoutCoreAnoKonfigurace jádra SDK — callbacky, ID transakce, lokalizace.
applepayTUseCheckoutApplePayNeZapne modul Apple Pay. Pokud klíč chybí, modul se nenačte.
googlepayTUseCheckoutGooglePayNeZapne modul Google Pay. Pokud klíč chybí, modul se nenačte.
cardTUseCheckoutCardNeZapne modul karetního formuláře. Pokud klíč chybí, modul se nenačte.

TUseCheckoutCore​

AtributTypPovinnýDefaultPopis
transactionIdstringAno–ID platby ve formátu XXXX-XXXX-XXXX. Získáte při založení platby přes API.
localestringNe'en'Jazyk textů SDK. Podporované hodnoty: cs, sk, en, de, es, fr, hr, hu, it, no, pl, ro, si, sl, sv, bg, da, el, et, lt, lv, nl, pt, fi, vi, uk, ru.
redirectModestringNe'top'Cíl přesměrování při 3D Secure fallbacku: 'self' (aktuální okno), 'parent' (rodičovský frame), 'top' (hlavní okno).
onPaid(payload) => voidAno–Voláno po úspěšné platbě. Viz Payload onPaid.
onCancelled(payload) => voidAno–Voláno po zrušení platby. Viz Payload onCancelled.
onPending(payload) => voidAno–Voláno po neúspěšném pokusu; platba zůstává aktivní. Viz Payload onPending.
onError(payload) => voidAno–Voláno při neočekávané chybě SDK. Viz Payload onError.
onPaymentStarted() => voidNe–Voláno při zahájení zpracování platby (zobrazení loaderu).
onPaymentStopped() => voidNe–Voláno po dokončení zpracování platby (skrytí loaderu).
Tip

Při onPaymentStarted neodstraňujte HTML elementy ze stránky — použijte CSS (display: none nebo overlay).

Callbacky — payload reference​

Všechny callbacky přijímají objekt payload. Každý payload obsahuje atribut service ('card' | 'applepay' | 'googlepay'), který identifikuje platební metodu.

onPaid(payload)​
AtributTypPopis
transactionIdstringID transakce
pricenumberZaplacená částka
currencystringMěna (ISO 4217, např. CZK, EUR)
status'PAID' | 'AUTHORIZED'Stav platby
servicestringPlatební metoda
onCancelled(payload)​
AtributTypPopis
status'CANCELLED'Stav platby
messagestringDůvod zrušení
scopestringOblast chyby
servicestringPlatební metoda
declineStatusCodestring?Kód zamítnutí (volitelný)
onPending(payload)​
AtributTypPopis
status'PENDING'Stav platby
messagestringPopis chyby
scopestringOblast chyby
servicestringPlatební metoda
declineStatusCodestring?Kód zamítnutí (volitelný)
Upozornění

onPending neznamená definitivní selhání — pouze neúspěšný pokus. Platba zůstává aktivní a zákazník může operaci opakovat.

onError(payload)​
AtributTypPopis
messagestringPopis chyby
scopestringOblast chyby
criticalbooleantrue = kritická chyba, SDK nelze dále používat
canRepeatboolean?true = zákazník může platbu opakovat
servicestringPlatební metoda
declineStatusCodestring?Kód zamítnutí (volitelný)

Rozlišení platební metody​

onPaid: (payload) => {
    switch (payload.service) {
        case 'card':     console.log('Platba kartou'); break;
        case 'applepay': console.log('Platba Apple Pay'); break;
        case 'googlepay': console.log('Platba Google Pay'); break;
    }
}

TUseCheckoutApplePay​

AtributTypPovinnýPopis
mountPointstringAnoCSS selektor kontejneru pro tlačítko (např. '#cg-applepay-box').
uiobjectNeVizuální nastavení tlačítka — podrobnosti viz Apple Pay.
actionsobjectNe{ onButtonClick } — viz onButtonClickHandler.
paymentobjectNe{ provider, providerId } — podrobnosti viz Apple Pay.

TUseCheckoutGooglePay​

AtributTypPovinnýPopis
mountPointstringAnoCSS selektor kontejneru pro tlačítko (např. '#cg-googlepay-box').
uiobjectNeVizuální nastavení tlačítka — podrobnosti viz Google Pay.
actionsobjectNe{ onButtonClick } — viz onButtonClickHandler.
paymentobjectNe{ googlePayMerchantId, provider, providerId } — podrobnosti viz Google Pay.

TUseCheckoutCard​

AtributTypPovinnýPopis
mountPointstring | HTMLDivElementAnoCSS selektor nebo přímý odkaz na DOM element (musí být <div> s neprazdným id). SDK z id odvodí selektory pro sub-elementy (#${id}-ibox, #${id}-button).
actionsobjectNe{ onButtonClick } — viz onButtonClickHandler.
appearanceobjectNePřizpůsobení vzhledu polí uvnitř iframe — podrobnosti viz Karetní formulář.

Chování SDK na základě přítomnosti elementů v kontejneru:

  • Najde #{id}-ibox → vloží iframe s poli karty.
  • Najde #{id}-button → napojí tlačítko na platební flow.
  • Nenajde #{id}-button → platbu lze spustit ručně voláním process() na instanci modulu.