Skip to main content

Implementácia

Táto stránka vás prevedie kompletnou integráciou Checkout SDK do vášho e-shopu. Jedno volanie useCheckout() pokryje celý platobný flow — od vykreslenia formulára až po spracovanie Apple Pay alebo Google Pay a platby kartou.

Inštalácia​

Checkout SDK možno do projektu pridať dvoma spôsobmi — pomocou dependency manageru alebo načítaním z Comgate CDN.

Dependency manager​

Použite, ak spravujete závislosti pomocou npm, yarn alebo pnpm a projekt zostavujete prostredníctvom bundleru (Vite, Webpack, Next.js, …).

Tip

Balíček @comgate/checkout-js obsahuje iba zavádzač (loader) — samotné SDK sa sťahuje dynamicky za behu. Aj napriek tomu odporúčame pravidelne kontrolovať dostupnosť nových verzií a balíček aktualizovať, aby vám neunikli dôležité opravy a vylepšenia.

npm install @comgate/checkout-js

Comgate CDN​

Ak nechcete využívať dependency managery, možno SDK načítať priamo z Comgate CDN. Po načítaní je knižnica dostupná globálne ako 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áca s verziami​

Pre produkčné nasadenie odporúčame používať fixnú major verziu. Comgate garantuje spätnú kompatibilitu v rámci rovnakej major verzie, takže opravy a vylepšenia sa dostávajú k používateľom automaticky.

  • CDN: Použite major verziu v URL (napr. /sdk/@3)
  • NPM: Použite parameter version v konfigurácii useCheckout(), preloadComgateCheckout() alebo prefetchComgateCheckout() — možno odovzdať reťazec alebo importovanú konštantu.
<!-- Fixná major verzia v URL — odporúčané pre produkciu -->
<script src="https://checkout.comgate.cz/sdk/@3"></script>

<!-- Konkrétna patch verzia — neodporúčame - vhodné pre testovanie/vývoj -->
<script src="https://checkout.comgate.cz/sdk/v/3.0.1"></script>

Uzamknutie na konkrétnu patch verziu (napr. 3.0.1) dôrazne neodporúčame.

Príprava HTML​

Po inštalácii knižnice je ďalším krokom príprava HTML štruktúry. Pred volaním useCheckout() pripravte na stránke kontajnerové elementy pre jednotlivé platobné metódy, ktoré plánujete využívať.

Apple Pay a Google Pay​

Pre každú metódu pripravte prázdny <div>, do ktorého SDK vykreslí natívne tlačidlo. Tlačidlá sa automaticky prispôsobujú rozmerom kontajnera — veľkosť teda určujete vaším vlastným štýlom elementu. Každému elementu priraďte tiež unikátne ID.

Unikátny selektor

Každý mountPoint (Apple Pay, Google Pay aj karta) musí zodpovedať práve jednému elementu v DOM. Ak selektor nájde viac prvkov, SDK vyhodí chybu. Používajte preto selektor s ID (napr. '#cg-applepay-box') alebo odovzdajte priamo referenciu na konkrétny HTMLDivElement.

Element musí byť v DOM v okamihu volania useCheckout(). Vo frameworkoch (Vue, React, Angular…) preto volajte useCheckout() vždy až po pripojení komponenty do DOM — typicky vnútri onMounted (Vue) alebo useEffect (React). SDK toleruje krátke zdržanie spôsobené render cyklom frameworku, ale nespoliehajte sa na to ako na náhradu správnej lifecycle integrácie.

Ukážka kontajnerov pre Apple Pay a Google PayUkážka kontajnerov pre 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>

Odporúčané rozmery​

Pri implementácii oboch metód voľte zjednotené rozmery, ktoré vyhovejú obom službám. Nižšie sú minimálne a odporúčané veľkosti — Google Pay má prísnejšie minimá:

TypApple Pay min.Google Pay min.Odporúčaná
Desktopiba logo (plain)100 × 30 px140 × 40 px160 × 45 px
s textom140 × 30 px240 × 40 px240 × 45 px
Mobiliba logo (plain)100 × 30 px140 × 40 px160 × 50 px
s textom140 × 30 px240 × 40 px240 × 50 px
Tip

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

Karetný formulár​

Pre platbu prostredníctvom karetného formulára potrebujete na stránke pripraviť kontajnerový element — <div> s ľubovoľným ID, na ktorý v konfigurácii odkážete pomocou mountPoint (CSS selektor, napr. '#cg-card-box', alebo priamy odkaz na HTMLDivElement).

SDK z ID elementu automaticky hľadá ďalšie elementy:

  • ${id}-ibox → sem SDK vloží zabezpečený iframe s poľami karty (element je povinný a musí byť vložený vnútri hlavného div)
  • ${id}-button → wrapper pre <button>, SDK ho napojí na platbu (môže byť aj mimo kontajnera)
Informácie

Vstupné polia karty bežia v izolovanom iframe — citlivé dáta nikdy neopustia zabezpečené prostredie → PCI-DSS compliance.

Tlačidlo môže byť umiestnené vnútri kontajnera, ideálne pod iframe s poľami karty:

<div id="cg-card-box">
    <div id="cg-card-box-ibox"><!-- iframe s poľami karty --></div>
    <div id="cg-card-box-button">
        <button type="button">Zaplatiť kartou</button>
    </div>
</div>

CSS Štýl​

SDK automaticky vkladá predvolené štýly karetného kontajnera pri mountovaní — nie je potrebné pridávať žiadne vlastné CSS. Možnosti prispôsobenia sú popísané v sekcii Prispôsobenie vzhľadu — Karetný formulár.

Loading stav (pred načítaním SDK)​

Do času, než sa SDK stihne načítať a spustiť, sa kontajner zobrazí ako prázdny priestor. Ak chcete namiesto prázdneho priestoru zobraziť loading spinner, je to možné — podrobnosti nájdete nižšie v sekcii Loading stav karetného formulára.

Tip

Loading stav je voliteľný — ak vám prázdny priestor pred načítaním nevadí, nie je potrebné nič implementovať.

Najskôr ale implementujte SDK a až potom pridajte vlastné štýly alebo loading spinner.

Implementácia​

Akonáhle máte HTML elementy pripravené, môžete prejsť k samotnej inicializácii SDK. Funkcia useCheckout() je váš hlavný (a vlastne jediný) vstupný bod. Zavoláte ju s konfiguračným objektom, ona urobí všetko potrebné — načíta moduly, vykreslí UI — a vráti vám Promise s inštanciami jednotlivých modulov.

Zjednodušený flow procesu: Váš backend / cloud app založí platbu na Comgate Merchant API, ktoré vám vráti transId. Toto ID spolu s checkoutId (získate v klientskom portáli pri aktivácii Checkout SDK) odovzdáte na váš frontend do volania funkcie useCheckout(). SDK inicializuje platobné metódy, vykreslí tlačidlá a formuláre, a keď zákazník zaplatí, zavolá váš callback.

Upozornenie pre SPA

Modul Core je implementovaný ako singleton. Inštancia vzniká pri prvom volaní useCheckout() a zostáva aktívna až do ukončenia / obnovenia stránky.

Ďalšie volania useCheckout() nevytvárajú novú inštanciu modulu Core, ale iba aktualizujú odovzdané callbacky (napríklad onPaid alebo onCancelled). Predtým odovzdané callbacky sa tým nahradia a aktívne zostávajú vždy iba callbacky odovzdané pri poslednom volaní useCheckout().

Pri opustení platobnej stránky je potrebné zavolať destroy() na inštanciách modulov Apple Pay, Google Pay a karty — inak zostanú aktívne v pamäti a môžu spôsobovať konflikty pri ďalších spracovaniach platieb. Viac informácií je v sekcii Úklid inštancií.

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: 'sk',
        onPaid:      (payload) => { console.log('Zaplatené', payload); },
        onCancelled: (payload) => { console.log('Zrušené', 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'); },
    },
    // ak nechcete ApplePay, tento kľúč vynechajte
    applepay: {
        mountPoint: CHECKOUT_BOX_APPLE_PAY,
    },
    // ak nechcete GooglePay, tento kľúč vynechajte
    googlepay: {
        mountPoint: CHECKOUT_BOX_GOOGLE_PAY,
        payment: {
            // Merchant ID, ktoré vám pridelí Google po registrácii u&nbsp;Google Pay Business Console.
            // Pre testovanie nie je potrebné, ale pre produkčné nasadenie je povinný.
            // DIY
            googlePayMerchantId: GOOGLE_PAY_MERCHANT_ID
        }
    },
    // ak nechcete kartu, tento kľúč vynechajte
    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ýsledok inicializácie​

Funkcia useCheckout() vracia Promise<TUseCheckoutResult>. Výsledok obsahuje stav celej inicializácie aj jednotlivých modulov.

Štruktúra odpovede​

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;
}

Ako interpretovať výsledok​

Po úspešnom vyriešení Promise vráti useCheckout() objekt typu TUseCheckoutResult. Objekt obsahuje celkový príznak success a samostatný výsledok inicializácie pre každý modul, ktorý ste zahrnuli do konfigurácie — teda pre každý kľúč (applepay, googlepay, card), ktorý ste odovzdali do useCheckout(). Moduly, ktoré ste v konfigurácii vynechali, nebudú vo výsledku prítomné.

Situáciaresult.successresult.[modul].successČo robiť
Všetko OKtruetrue u všetkýchPlatobné metódy sú pripravené, nie je potrebné nič riešiť.
Niektorý modul zlyhal (AP/GP/karta nedostupná, element nenájdený…)falsefalse u dotknutého moduluPromise sa splní. Skontrolujte result.[modul].error — zistíte príčinu. Skryte alebo deaktivujte nedostupnú platobnú metódu.
Kritická chyba (neplatné checkoutId, Core zlyhal, sieťový problém)––Promise sa zamietne — výsledný objekt nevznikne vôbec. Spracujte v bloku catch.
Tip

Kľúč modulu (applepay, googlepay, card) je vo výsledku prítomný iba vtedy, ak ste daný modul zahrnuli do konfigurácie. Ak ste napr. neodovzdali kľúč applepay, bude result.applepay rovné undefined.

Vlastnosti výsledku modulu​

Každý modul vracia objekt TUseCheckoutModuleResult<T> s troma vlastnosťami:

VlastnosťTypPopis
successbooleantrue — modul bol načítaný, zariadenie ho podporuje a UI bolo vykreslené do zadaného mount pointu. false — inicializácia zlyhala, viď error.
errorstring | undefinedPopis príčiny zlyhania, prítomný iba pri success: false. Príklady: "Apple Pay is not available on this device", "Element \"#cg-applepay-box\" not found", ...
instanceT | nullReferencia na inštanciu modulu. Pri success: true obsahuje aktívnu inštanciu. Pri success: false môže byť null (modul sa ani nevytvoril) alebo obsahovať čiastočne inicializovanú inštanciu.

Príklad spracovania​

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 úspešný, ak Promise neskončil výnimkou
    console.log('Core inicializovaný', result.core.instance);

    // Skontrolujte result.success pre rýchly prehľad, či všetko prebehlo v poriadku
    if (!result.success) {
        console.warn('Niektorý modul sa nepodarilo inicializovať');
    }

    // Apple Pay — môže byť nedostupný na zariadení
    if (result.applepay?.success) {
        console.log('Apple Pay pripravený');
    } else if (result.applepay) {
        console.warn('Apple Pay nedostupné:', result.applepay.error);
        document.getElementById('cg-applepay-box').style.display = 'none';
    }

    // Google Pay — môže byť nedostupný na zariadení
    if (result.googlepay?.success) {
        console.log('Google Pay pripravený');
    } else if (result.googlepay) {
        console.warn('Google Pay nedostupné:', result.googlepay.error);
        document.getElementById('cg-googlepay-box').style.display = 'none';
    }

    // Karetný formulár
    if (result.card?.success) {
        console.log('Karetný formulár vykreslený');
    } else if (result.card) {
        console.warn('Karetný formulár nedostupný:', result.card.error);
    }
} catch (error) {
    // Kritická chyba — SDK sa nepodarilo inicializovať
    console.error('Checkout inicializácia zlyhala:', error);
}

Úklid inštancií​

Povinné pre SPA

Ak vaša aplikácia používa client-side routing (Vue Router, React Router, Next.js App Router apod.), musíte pri opustení platobnej stránky zavolať destroy() na všetkých moduloch. Bez toho zostávajú staré inštancie Apple Pay, Google Pay a karetného formulára v pamäti, môžu reagovať na budúce udalosti a spôsobovať konflikty pri ďalšom spracovaní platieb.

Metóda destroy() odstráni vykreslené UI (iframe, tlačidlá), odpojí event listenery a uvoľní prostriedky modulu. Je dostupná na inštanciách modulov applepay, googlepay a card. Na inštanciu Core sa destroy() nevolá — Core je singleton a jeho životný cyklus riadi SDK samo.

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

// Pri opustení platobnej stránky zavolajte destroy na všetkých moduloch:
function cleanup() {
    result.applepay?.instance?.destroy();
    result.googlepay?.instance?.destroy();
    result.card?.instance?.destroy();
    // => na CORE sa destroy nevolá
}

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

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

Po zavolaní destroy() nemožno inštanciu modulu znovu použiť — pre novú platbu je potrebné zavolať useCheckout() znovu.

Upozornenie

Používajte iba funkcie a metódy popísané v tejto dokumentácii. SDK obsahuje interné prvky, ktoré nie sú určené na verejné použitie. Ich využitie nie je podporované a môže viesť k nefunkčnosti SDK.

Ďalšie funkcie​

Niektoré funkcie SDK pracujú automaticky na pozadí, iné možno voliteľne ovládať. Nižšie sú popísané tie najdôležitejšie.

3D Secure​

Pri platbe kartou môže banka zákazníka vyžadovať dodatočné overenie pomocou 3D Secure. 3D Secure je úplne v réžii SDK — nie je potrebná žiadna dodatočná implementácia.

Ak banka vyžaduje dodatočné overenie (3D Secure), SDK automaticky zvolí najvhodnejšiu metódu zobrazenia:

  1. iframe modal — ak je overovacia stránka banky zobraziteľná v iframe, SDK ju zobrazí priamo na stránke. Ak sa iframe nepodarí načítať, SDK prejde na presmerovanie.
  2. Nové okno (popup) — ak banka neumožňuje zobrazenie v iframe, SDK otvorí nové okno. Ak je popup zablokovaný prehliadačom, SDK prejde na presmerovanie.
  3. Presmerovanie — záložná metóda pre oba scenáre vyššie. Zákazník je presmerovaný na stránku banky.

V prípade presmerovania je zákazník po dokončení overenia vrátený na jednu z URL nastavených v klientskom portáli:

  • URL zaplatený — platba úspešná,
  • URL zrušený — platba zrušená,
  • URL nevybavený — zákazník môže platbu zopakovať.

Click to Pay​

Informácie

Na podpore Click to Pay sa intenzívne pracuje. Funkcia bude dostupná v jednej z budúcich verzií SDK.

Click to Pay umožní zákazníkom platiť uloženou kartou bez nutnosti zadávať číslo karty znovu. Po implementácii bude automatickou súčasťou karetného formulára — bez nutnosti dodatočnej konfigurácie.

Debug mode​

Odovzdaním debug: true v konfigurácii aktivujete rozšírené logovanie do konzoly prehliadača. SDK vypisuje farebne označené správy s prefixom [ComgateCheckout], ktoré pomáhajú pri diagnostike problémov.

useCheckout({
    checkoutId: COMGATE_CHECKOUT_ID,
    debug: true, // zapne rozšírené logovanie
    core: { /* ... */ },
    card: { mountPoint: '#cg-card-box' },
});
Upozornenie

Debug mode nepoužívajte v produkcii — výpisy môžu obsahovať citlivé informácie o priebehu inicializácie.

Informácie o verzii​

Pre diagnostiku a logovanie možno zistiť verziu loaderu aj jednotlivých načítaných modulov.

Verzia loaderu je dostupná cez exportovanú funkciu getLoaderVersion():

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

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

Verzie jednotlivých modulov sú dostupné cez globálny objekt window.comgate.checkout po dokončení inicializácie. Každý modul (Core, Apple Pay, Google Pay, Card) vystavuje metódu version():

// Verzie modulov sú dostupné po vyrieš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() modulov sú dostupné iba vtedy, ak bol daný modul úspešne načítaný. Ak modul nebol zahrnutý do konfigurácie alebo zlyhalo jeho načítanie, príslušná vlastnosť (checkout.applepay apod.) nebude prítomná.

Prednačítanie SDK​

Kedy použiť ktorú funkciu?
FunkciaPrioritaPoužitie
prefetchComgateCheckout()Nízka (prefetch)Zákazník možno bude platiť — košík, produktová stránka.
preloadComgateCheckout()Vysoká (preload)Zákazník určite bude platiť — súhrn objednávky, platobný krok.

preloadComgateCheckout()​

Predbežne načíta skripty SDK do cache prehliadača prostredníctvom <link rel="preload">. Skripty sa nespustia — len sa uložia, aby následné volanie useCheckout() bolo rýchlejšie.

Vhodné pre stránky, kde viete, že zákazník čoskoro prejde na platobný krok (napr. zhrnutie 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šetky moduly vopred načítané:', result.preloaded);
    }
});

Parametre​

ParameterTypPovinnýDefaultPopis
checkoutIdstringÁno–UUID v4 pridelené Comgatom. Identifikuje váš e-shop. Formát: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
modulesTModuleType[]Áno–Moduly na predbežné načítanie. Povolené hodnoty: MODULE_APPLEPAY ('applepay'), MODULE_GOOGLEPAY ('googlepay'), MODULE_CARD ('card'), MODULE_CORE ('core'). Musí obsahovať aspoň jeden modul (okrem core). Core je vždy zahrnutý automaticky.
versionstringNie'3'Verzia SDK. Odporúčame fixnú major verziu (napr. '3'). Povolené hodnoty: '2', '3', alebo konkrétny semver ('2.x.x', '3.x.x'). Verzia 1 nie je podporovaná.
debugbooleanNiefalseZapne rozšírené logovanie do konzoly prehliadača.
onPreload(payload: TPreloadComgateCheckoutResult) => voidNieundefinedAlternatívny callback volaný po dokončení prednačítania. Payload je zhodný s návratovou hodnotou Promise.
Tip

Parameter onPreload je alternatívou k spracovaniu výsledku cez .then(). Obe varianty možno kombinovať — callback je zavolaný vždy ako prvý.

AtribútTypPopis
checkoutIdstringOdovzdané checkoutId.
successbooleantrue ak boli všetky požadované moduly úspešne načítané do cache.
preloadedTModuleType[]Pole názvov úspešne vopred načítaných modulov (napr. ['core', 'applepay', 'googlepay']).
error{ [key in TModuleTypeExtended]?: Error }Detaily chýb pre jednotlivé moduly. Kľúč je názov modulu ('core', 'applepay', 'googlepay', 'card', 'loader'), hodnota je inštancia Error. Prítomný iba ak niektorý modul zlyhal.

Chybové stavy​

Promise sa zamietne (reject) ak:

  • checkoutId nie je validné UUID v4
  • modules nie je pole alebo neobsahuje žiadny modul (mimo core)
  • Niektorý z požadovaných modulov sa nepodarilo vopred načítať

V prípade zamietnutia je payload totožný s TPreloadComgateCheckoutResult, ale success je false a pole error obsahuje detaily.

prefetchComgateCheckout()​

Vloží do stránky <link rel="prefetch"> pre skripty SDK. Prehliadač ich stiahne s nízkou prioritou vo voľnom čase — na rozdiel od preloadComgateCheckout() nebude sťahovanie blokovať aktuálny rendering ani súťažiť s kritickými zdrojmi.

Vhodné pre stránky, kde zákazník možno prejde na platbu, ale zatiaľ to nie je isté (napr. produktová stránka, košík pred súhrnom).

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šetky moduly prefetchnuté:', result.prefetched);
    }
});

Parametre​

ParameterTypPovinnýDefaultPopis
checkoutIdstringÁno–UUID v4 pridelené Comgatom. Identifikuje váš e-shop. Formát: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
modulesTModuleType[]Áno–Moduly na prefetchnutie. Povolené hodnoty: MODULE_APPLEPAY ('applepay'), MODULE_GOOGLEPAY ('googlepay'), MODULE_CARD ('card'), MODULE_CORE ('core'). Musí obsahovať aspoň jeden modul (okrem core). Core je vždy zahrnutý automaticky.
versionstringNie'3'Verzia SDK. Odporúčame fixnú major verziu (napr. '3'). Povolené hodnoty: '2', '3', alebo konkrétny semver ('2.x.x', '3.x.x'). Verzia 1 nie je podporovaná.
debugbooleanNiefalseZapne rozšírené logovanie do konzoly prehliadača.
onPrefetch(payload: TPrefetchComgateCheckoutResult) => voidNieundefinedCallback volaný po dokončení prefetche. Payload je zhodný s návratovou hodnotou Promise.
Tip

Parameter onPrefetch je alternatívou k spracovaniu výsledku cez .then(). Obe varianty možno kombinovať — callback je zavolaný vždy ako prvý.

AtribútTypPopis
checkoutIdstringOdovzdané checkoutId.
successbooleantrue ak boli všetky požadované moduly úspešne prefetchnuté.
prefetchedTModuleType[]Pole názvov úspešne prefetchnutých modulov (napr. ['core', 'applepay', 'googlepay']).
error{ [key in TModuleTypeExtended]?: Error }Detaily chýb pre jednotlivé moduly. Prítomný iba ak niektorý modul zlyhal.

Konfiguračná referencia​

Kompletný prehľad všetkých konfiguračných parametrov, ktoré možno odovzdať do useCheckout(). Každá platobná metóda má vlastnú sadu nastavení — povinný je iba checkoutId a objekt core.

TUseCheckoutConfig​

AtribútTypPovinnýPopis
checkoutIdstringÁnoUUID v4 pridelené Comgatom. Identifikuje váš e-shop.
versionstringNieVerzia SDK. Default '3'. Odporúčame fixnú major verziu (napr. '3'). Povolené hodnoty: '2', '3', alebo konkrétny semver ('3.x.x'). Verzia 1 nie je podporovaná.
coreTUseCheckoutCoreÁnoKonfigurácia jadra SDK — callbacky, ID transakcie, lokalizácia.
applepayTUseCheckoutApplePayNieZapne modul Apple Pay. Ak kľúč chýba, modul sa nenačíta.
googlepayTUseCheckoutGooglePayNieZapne modul Google Pay. Ak kľúč chýba, modul sa nenačíta.
cardTUseCheckoutCardNieZapne modul karetného formulára. Ak kľúč chýba, modul sa nenačíta.

TUseCheckoutCore​

AtribútTypPovinnýDefaultPopis
transactionIdstringÁno–ID platby vo formáte XXXX-XXXX-XXXX. Získate pri založení platby cez API.
localestringNie'en'Jazyk textov 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.
redirectModestringNie'top'Cieľ presmerovania pri 3D Secure fallbacku: 'self' (aktuálne okno), 'parent' (rodičovský frame), 'top' (hlavné okno).
onPaid(payload) => voidÁno–Volané po úspešnej platbe. Viď Payload onPaid.
onCancelled(payload) => voidÁno–Volané po zrušení platby. Viď Payload onCancelled.
onPending(payload) => voidÁno–Volané po neúspešnom pokuse; platba zostáva aktívna. Viď Payload onPending.
onError(payload) => voidÁno–Volané pri neočakávanej chybe SDK. Viď Payload onError.
onPaymentStarted() => voidNie–Volané pri zahájení spracovania platby (zobrazenie loaderu).
onPaymentStopped() => voidNie–Volané po dokončení spracovania platby (skrytie loaderu).
Tip

Pri onPaymentStarted neodstraňujte HTML elementy zo stránky — použite CSS (display: none alebo overlay).

Callbacky — payload referencia​

Všetky callbacky prijímajú objekt payload. Každý payload obsahuje atribút service ('card' | 'applepay' | 'googlepay'), ktorý identifikuje platobnú metódu.

onPaid(payload)​
AtribútTypPopis
transactionIdstringID transakcie
pricenumberZaplatená suma
currencystringMena (ISO 4217, napr. CZK, EUR)
status'PAID' | 'AUTHORIZED'Stav platby
servicestringPlatobná metóda
onCancelled(payload)​
AtribútTypPopis
status'CANCELLED'Stav platby
messagestringDôvod zrušenia
scopestringOblasť chyby
servicestringPlatobná metóda
declineStatusCodestring?Kód zamietnutia (voliteľný)
onPending(payload)​
AtribútTypPopis
status'PENDING'Stav platby
messagestringPopis chyby
scopestringOblasť chyby
servicestringPlatobná metóda
declineStatusCodestring?Kód zamietnutia (voliteľný)
Upozornenie

onPending neznamená definitívne zlyhanie — iba neúspešný pokus. Platba zostáva aktívna a zákazník môže operáciu opakovať.

onError(payload)​
AtribútTypPopis
messagestringPopis chyby
scopestringOblasť chyby
criticalbooleantrue = kritická chyba, SDK nemožno ďalej používať
canRepeatboolean?true = zákazník môže platbu opakovať
servicestringPlatobná metóda
declineStatusCodestring?Kód zamietnutia (voliteľný)

Rozlíšenie platobnej metódy​

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​

AtribútTypPovinnýPopis
mountPointstringÁnoCSS selektor kontajnera pre tlačidlo (napr. '#cg-applepay-box').
uiobjectNieVizuálne nastavenie tlačidla — podrobnosti viď Apple Pay.
actionsobjectNie{ onButtonClick } — viď onButtonClickHandler.
paymentobjectNie{ provider, providerId } — podrobnosti viď Apple Pay.

TUseCheckoutGooglePay​

AtribútTypPovinnýPopis
mountPointstringÁnoCSS selektor kontajnera pre tlačidlo (napr. '#cg-googlepay-box').
uiobjectNieVizuálne nastavenie tlačidla — podrobnosti viď Google Pay.
actionsobjectNie{ onButtonClick } — viď onButtonClickHandler.
paymentobjectNie{ googlePayMerchantId, provider, providerId } — podrobnosti viď Google Pay.

TUseCheckoutCard​

AtribútTypPovinnýPopis
mountPointstring | HTMLDivElementÁnoCSS selektor alebo priamy odkaz na DOM element (musí byť <div> s neprázdnym id). SDK z id odvodí selektory pre sub-elementy (#${id}-ibox, #${id}-button).
actionsobjectNie{ onButtonClick } — viď onButtonClickHandler.
appearanceobjectNiePrispôsobenie vzhľadu polí vnútri iframe — podrobnosti viď Karetný formulár.

Správanie SDK na základe prítomnosti elementov v kontajneri:

  • Nájde #{id}-ibox → vloží iframe s poľami karty.
  • Nájde #{id}-button → napojí tlačidlo na platobný flow.
  • Nenájde #{id}-button → platbu možno spustiť ručne volaním process() na inštancii modulu.