Core modul

Core je základní vrstva Comgate Checkout SDK. Poskytuje infrastrukturu, kterou využívají všechny funkční moduly, jako například Apple Pay nebo Google Pay. Zajišťuje správu událostí, komunikaci s Comgate API a také řízení životního cyklu jednotlivých modulů.

Core modul je vždy načítán automaticky prostřednictvím Loaderu, proto jej není nutné uvádět při konfiguraci Loaderu (modules). Loader sám vyhodnotí, které funkční moduly Core vyžadují, a zajistí jeho načtení. Bez Core nelze používat závislé moduly (např. Apple Pay nebo Google Pay). Existují však i moduly, které Core nevyžadují – tato skutečnost je vždy uvedena v jejich dokumentaci.

Pro vývojáře představuje Core centrální místo, kde se provádí inicializace, nastavují parametry a získávají základní funkce pro práci s Checkoutem.

Výběr implementačního scénáře

Pro integraci Checkout SDK do košíku e-shopu lze zvolit dva základní přístupy: statický a dynamický. Výběr scénáře je kritický pro způsob, jakým bude modul Core instancován.

Statický – předem založená platba

Tento scénář představuje nejjednodušší formu implementace. Na stránce není nutné provádět žádné složitější akce a celý proces je pevně svázán s jednou konkrétní platbou.

Již při vytváření instance modulu Core je nutné znát identifikátor transakce Comgate (transactionId). Pokud se zákazník rozhodne změnit například způsob dopravy nebo jiný parametr, je nutné založit novou platbu s aktualizovanou částkou a provést znovunačtení celé stránky.

ℹ️ Identifikátor transakce je možné vložit do stránky například při renderování kódu na straně serveru.

Dynamický – založení platby v okamžiku potvrzení

Upozornění

Tento scénář zatím není implementován.

Dynamický přístup poskytuje větší flexibilitu a umožňuje stránce reagovat na změny uživatele až do poslední chvíle. Při vytváření instance Core není nutné znát transactionId. Platba se zakládá až v okamžiku, kdy zákazník klikne na tlačítko pro zaplacení a potvrdí, že je s objednávkou spokojen. Tím se eliminuje nutnost zbytečného přenačítání celé stránky při každé změně.

Tento scénář je složitější na implementaci, protože vyžaduje součinnost jak na straně frontendu (prohlížeč), tak na straně backendu (server). Umožňuje však dosáhnout dynamičtějšího a uživatelsky přívětivějšího chování při zpracování plateb.

Před vytvořením instance

Jakmile Loader úspěšně stáhne všechny moduly pomocí metody loadComgateCheckout() a je vrácen Promise v bloku .then(), lze využít v odpovědi namapované funkce k vytvoření instance modulu Core.

Z předchozí kapitoly již známe strukturu odpovědi metody loadComgateCheckout(). Díky tomu lze přímo využít namapované funkce response.core.create() a response.core.version().

create()

Vytvoří instanci třídy CheckoutCore a provede základní inicializaci. Načte konfiguraci ze serveru Comgate a připraví prostředí pro běh jednotlivých funkčních modulů.

Jakmile je vše připraveno, funkce vrací Promise s instancí třídy CheckoutCore.

• Přijímá objekt s konfiguračními parametry
• Vrací Promise s instancí třídy CheckoutCore

Použití

Statický scénář

response.core.create({
  checkoutId: "00000000-0000-0000-0000-000000000000",
  transactionId: "XXXX-XXXX-XXXX", // pouze pro statický scénář
  locale: "cs",
  onPaid: (payload) => { console.log("onPaid", payload); },
  onCancelled: (payload) => { console.log("onCancelled", payload); },
  onPending: (payload) => { console.log("onPending", payload); },
  onClick: (payload) => { console.log("onClick", payload); },
  onError: (payload) => { console.log("onError", payload); },
  debug: true, // *v produkci vypnout*
})
.then((instance: CheckoutCore) => {
  const instanceCore = instance;
  console.log("Comgate Checkout: instance CORE", instance);
})
.catch((error: unknown) => {
  console.error("Comgate Checkout: chyba při vytváření instance CORE", error);
});

Parametry

Funkce vyžaduje jediný konfigurační parametr typu TCheckoutProps. Parametr je objekt, který podporuje následující atributy:

Atribut	Typ	Povinný	Default	Popis
checkoutId	string	Ano	–	Checkout ID přidělené při vytvoření platby. Musí být ve formátu UUID. Příklad: 00000000-0000-0000-0000-000000000000
transactionId	string	Ano	–	Interní Comgate ID existující platby. Příklad: XXXX-XXXX-XXXX
onPaid	TCheckoutOnPaidHandler	Ano	–	Callback vyvolaný při dosažení finálního stavu PAID nebo AUTHORIZED. Tento stav znamená, že platba byla plátcem úspěšně dokončena.
onCancelled	TCheckoutOnCancelledHandler	Ano	–	Callback vyvolaný při dosažení finálního stavu CANCELLED. Signalizuje, že byla celá platba zrušena.
onPending	TCheckoutOnPendingHandler	Ano	–	Callback vyvolaný v případě, že pokus o úhradu nebyl úspěšný. Umožňuje provést další pokus o platbu na stejné transakci.
onError	TCheckoutOnErrorHandler	Ano	–	Callback vyvolaný při závažné chybě, která brání pokračování ve zpracování platby.
onPaymentStarted	TCheckoutOnPaymentStartedHandler	Ne	–	Callback vyvolaný při zahájení pokusu o úhradu, např. po kliknutí na tlačítko Apple Pay nebo Google Pay. Lze využít pro úpravu prvků v UI.
onPaymentStopped	TCheckoutOnPaymentStoppedHandler	Ne	–	Callback vyvolaný při ukončení pokusu o úhradu, ať už úspěšného, nebo neúspěšného. Lze využít pro úpravu prvků v UI.
locale	TLanguage	Ne	cs	Jazyk uživatelského rozhraní služeb integrovaných prostřednictvím Checkout SDK. Některé služby mohou akceptovat jazyk pouze podle nastavení prohlížeče nebo operačního systému.
debug	boolean	Ne	false	Aktivuje podrobnější logování do konzole. Na produkci vždy ponechte false.

Popis jednotlivých typů handlerů:

Každý handler slouží k reakci na konkrétní stav nebo událost během zpracování platby. Níže jsou popsány jednotlivé typy a jejich význam:

Typ TCheckoutOnPaidHandler

Prostřednictvím handleru mapovaného atributem onPaid je e-shop informován o tom, že platba byla úspěšně přepnuta do stavu PAID nebo AUTHORIZED. Tento stav je pro plátce konečný a potvrzuje úspěšné uhrazení nebo autorizaci platby.

type TCheckoutOnPaidParams = {
  service: 'applepay' | 'googlepay' | 'core';
  transactionId: string;
  price: number;
  currency: 'CZK' | 'EUR' | 'PLN' | 'HUF' | 'USD' | 'GBP' | 'RON' | 'NOK' | 'SEK';
  status: 'PAID' | 'AUTHORIZED';
};

type TCheckoutOnPaidHandler = (data: TCheckoutOnPaidParams) => void;

Atributy TCheckoutOnPaidParams

Atribut	Typ	Popis
service	string	Identifikace modulu, který akci vyvolal (applepay, googlepay, nebo core).
status	string	Stav platby: PAID nebo AUTHORIZED.
transactionId	string	Interní Comgate ID zpracované platby.
price	number	Částka platby. Hodnota je vždy shodná s částkou nastavenou při vytvoření platby.
currency	string	Měna platby (např. CZK, EUR). Hodnota je vždy shodná s měnou nastavenou při založení platby.

Typ TCheckoutOnCancelledHandler

Prostřednictvím handleru mapovaného atributem onCancelled je e-shop informován o tom, že byla celá platba stornována a přepnuta do stavu CANCELLED. Tento stav je pro plátce konečný a oznamuje nemožnost pokračovat ve zpracování platby.

V tomto stavu je vhodné zobrazit chybovou/infomační stránku. Chce-li plátce platbu opakovat, je nutné založit novou platbu a...

ℹ️ Při zachycení této události je nutné založit novou platbu.

Upozornění

TODO

type TCheckoutOnCancelledParams = {
  service: 'applepay' | 'googlepay' | 'core';
  status: 'CANCELLED';
  message: string;
  scope: string;
  detail?: any;
  params?: any;
  declineStatusCode?: string;
};

type TCheckoutOnCancelledHandler = (data: TCheckoutOnCancelledParams) => void;

Atributy TCheckoutOnCancelledParams

Atribut	Typ	Popis
service	string	Identifikace modulu, který akci vyvolal (applepay, googlepay, nebo core).
status	string	Stav platby: CANCELLED.
message	string	Debug info: interní vývojové detaily, proč byl tento handler vyvolán.
scope	string	Debug info: identifikuje oblast SDK, ve které došlo k vygenerování události.
detail	any | undefined	Debug info: doprovodné detaily pomáhající s identifikací případného problému.
params	any | undefined	Debug info: doprovodné detaily pomáhající s identifikací případného problému.
declineStatusCode	string | undefined	Pokud byla platba zamítnuta při zpracování, obsahuje identifikátor důvodu zamítnutí.

Typ TCheckoutOnPendingHandler

Prostřednictvím handleru mapovaného atributem onPending je e-shop informován o nezdařeném pokusu o platbu. Událost signalizuje, že pokus o zpracování byl ukončen, avšak celá platba zůstala otevřena ve stavu PENDING.

Tento stav je výhodný, protože není nutné zakládat novou platbu – stačí umožnit plátci spustit nový platební pokus, například kliknutím na tlačítko Apple Pay. Systém automaticky založí nový pokus a pokusí se jej zpracovat. Výsledkem může být volání onPaid, onCancelled nebo opět onPending.

ℹ️ Při zachycení této události není vhodné zakládat novou platbu.

type TCheckoutOnPendingParams = {
  service: 'applepay' | 'googlepay' | 'core';
  status: 'PENDING';
  message: string;
  scope: string;
  detail?: any;
  params?: any;
  declineStatusCode?: string;
};

type TCheckoutOnPendingHandler = (data: TCheckoutOnPendingParams) => void;

Atributy TCheckoutOnPendingParams

Atribut	Typ	Popis
service	string	Identifikace modulu, který akci vyvolal (applepay, googlepay, nebo core).
status	string	Stav platby: PENDING.
message	string	Debug info: interní vývojové detaily, proč byl tento handler vyvolán.
scope	string	Debug info: identifikuje oblast SDK, ve které došlo k vygenerování události.
detail	any | undefined	Debug info: doprovodné detaily pomáhající s identifikací případného problému.
params	any | undefined	Debug info: doprovodné detaily pomáhající s identifikací případného problému.
declineStatusCode	string | undefined	Pokud byla platba zamítnuta při zpracování, obsahuje identifikátor důvodu zamítnutí.

Typ TCheckoutOnErrorHandler

Prostřednictvím handleru mapovaného atributem onError je e-shop informován o závažné chybě v průběhu zpracování platby. Pokud dojde k vyvolání tohoto handleru, není možné v platbě pokračovat a je nutné plátci zobrazit chybové hlášení.

ℹ️ Při zachycení této události je vhodné provést tvrdý refresh stránky a zkusit nový pokus o platbu. Pokud selhání přetrvává, doporučuje se plátci nabídnout alternativní platební metody, například přesměrováním na platební bránu.

type TCheckoutOnErrorParams = {
  service: 'applepay' | 'googlepay' | 'core';
  message: string;
  scope: string;
  detail?: any;
  params?: any;
  declineStatusCode?: string;
  error?: any;
  critical: boolean;
  canRepeat?: boolean;
};

  type TCheckoutOnErrorHandler = (data: TCheckoutOnErrorParams) => void;

Atributy TCheckoutOnErrorParams

Atribut	Typ	Popis
service	string	Identifikace modulu, který akci vyvolal (applepay, googlepay, nebo core).
message	string	Debug info: interní vývojové detaily, proč byl tento handler vyvolán.
scope	string	Debug info: identifikuje oblast SDK, ve které došlo k vygenerování události.
detail	any | undefined	Debug info: doprovodné detaily pomáhající s identifikací případného problému.
params	any | undefined	Debug info: doprovodné parametry související s událostí.
declineStatusCode	string | undefined	Pokud byla platba zamítnuta, obsahuje identifikátor důvodu zamítnutí.
error	any | undefined	Detail vzniklé chyby.
critical	boolean	Příznak, zda se jedná o kritickou chybu.
canRepeat	boolean | undefined	Určuje, zda je vhodné umožnit opakovaný pokus o platbu. Po druhém opakování již pokus neopakovat.

Typ TCheckoutOnPaymentStartedHandler

Prostřednictvím handleru mapovaného atributem onPaymentStarted je e-shop informován o zahájení pokusu o placení. Událost nastává například po kliknutí na tlačítko Apple Pay nebo Google Pay a slouží k navázání logiky v uživatelském rozhraní (např. zobrazení loaderu či blokace tlačítek).

type TCheckoutOnPaymentStartedHandler = () => void;

Typ TCheckoutOnPaymentStoppedHandler

Prostřednictvím handleru mapovaného atributem onPaymentStopped je e-shop informován o ukončení pokusu o placení. Událost nastává po dokončení nebo přerušení platebního pokusu a lze ji využít například k resetování prvků uživatelského rozhraní (skrytí loaderu, opětovné povolení tlačítek apod.).

Událost může být – a často je – emitována současně s dalšími handlery jako onPaid, onPending nebo onError.

type TCheckoutOnPaymentStoppedHandler = () => void;

Typ TLanguage

Typ TLanguage určuje jazykové kódy, které lze použít pro nastavení lokalizace rozhraní Checkout SDK. Některé služby však nepodporují všechny jazyky ze seznamu – v takových případech jsou tyto jazyky automaticky mapovány na češtinu.

type TLanguage = 'cs' | 'de' | 'en' | 'es' | 'fr' | 'hr' | 'hu' | 'it' | 'no' |
                 'pl' | 'ro' | 'si' | 'sl' | 'sk' | 'sv' | 'bg' | 'da' | 'el' |
                 'et' | 'lt' | 'lv' | 'nl' | 'pt' ;

Návratová hodnota

Funkce vždy vrací objekt typu Promise<CheckoutCore>.

• V případě úspěchu je Promise vyřešen s instancí typu CheckoutCore.
• V případě chyby je Promise odmítnut (catch) s objektem typu Error. V TypeScriptu se doporučuje anotovat chyby v bloku catch jako unknown, protože není zaručeno, že půjde vždy o Error.

Podrobný popis typu CheckoutCore je uveden v samostatné sekci Použití instance Core.

Příklady

Úspěch

V případě úspěšného vytvoření instance modulu Core je vrácen objekt třídy CheckoutCore. Jeho metody a použití jsou popsány v sekci Použití instance Core.

Chyba

V případě, že se instanci třídy modulu Core nepodaří vytvořit, je prostřednictvím catch vrácen objekt typu Error. V prostředí TypeScript se doporučuje anotovat chyby v bloku catch jako unknown.

version()

Vrací verzi staženého modulu Core jako string.

⚠️ Vrací verzi modulu Core, nikoli verzi celého Comgate Checkout SDK.

Použití

const coreVersion = response.core.version();
console.log(coreVersion) // vypíše např. 2.0.12

Parametry

Funkce nepřijímá žádné parametry.

Návratová hodnota

Návratovou hodnotou je vždy string obsahující verzi ve formátu major.minor.patch.

Příklady

Ukázka struktury odpovědi:

"1.0.12"

Instance Core

Instance modulu Core představuje centrální prvek Checkout SDK a funguje jako orchestrátor pro ostatní moduly. Jeho hlavním účelem je sjednocení a propojení logiky celého řešení. Samotný Core se většinou nepoužívá přímo ze strany vývojáře, ale předává se jako referenční objekt dalším modulům (např. ApplePay, GooglePay).

Díky tomu všechny funkční moduly sdílejí jednotnou konfiguraci prostřednictvím Core, společný stav a dokážou reagovat konzistentně na průběh platby.

Co je myšleno tím, že Core vystupuje jako orchestrátor?

Je tím míněno, že se chová podobně jako dirigent orchestru:

• Nehraje na jednotlivé nástroje (Apple Pay, Google Pay, …) – ty mají vlastní logiku.
• Řídí jejich souhru – zajišťuje, aby všechny moduly měly správné vstupy, sdílely stav platby a jejich výstupy (události) byly směrovány do příslušných callbacků.
• Hlídá časování a pořadí – například pokud Apple Pay vrátí chybu, Core rozhodne, jak se s ní naloží (emitne onError, ponechá platbu ve stavu PENDING apod.).

Jinými slovy: Core neřeší detailní práci jednotlivých platebních metod, ale zajišťuje, že všechny části SDK spolupracují konzistentně a podle jedné logiky.

Nicméně i Core obsahuje určité metody, jejichž volání je v konkrétních situacích žádoucí, případně dokonce nutné.

checkEnvironmentSecurity()

Ověří, zda běhové prostředí splňuje minimální bezpečnostní a technické požadavky pro provoz Checkout SDK. Kontroluje mimo jiné HTTPS / secure context, běh v top-level kontextu (mimo iframe) a případně další podmínky ovlivňující spolehlivost integrace.

Použití

const securityCheckResult = instanceCore.checkEnvironmentSecurity();

if (securityCheckResult !== true) {
  console.error('Security check failed:', securityCheckResult);
}

Parametry

Metoda nepřijímá žádné parametry.

Návratová hodnota

Po provedení kontrol metoda vrací:

• true, pokud je vše v pořádku,
• pole stringů s popisem identifikovaných problémů, pokud dojde ke zjištění problému.

Příklady

Úspěch

true

Chyba

[
  "The website must be served over HTTPS.",
  "The website must not be loaded inside an iframe."
]

updatePayment()

Metoda updatePayment umožňuje aktualizovat údaje o platbě u již existující instance Core. Používá se například v situacích, kdy platba expiruje nebo je stornována. Důvodem je, že checkout ve svém základním scénáři neumožňuje vytvoření druhé instance s novou platbou.

• Přijímá jediný parametr transactionId.
• Vrací objekt Promise<void>.

Upozornění

Tuto metodu je možné používat pouze při statickém scénáři.

Použití

instanceCore.updatePayment('XXXX-XXXX-XXXX')
.then(() => {
  console.log('Comgate Checkout: Platba změněna');
})
.catch((error: unknown) => {
   // nepodařilo se změnit kód platby
   console.error('Comgate Checkout:', changeResult.reason);
});

Parametry

Metoda přijímá jediný parametr typu string. Hodnota parametru musí odpovídat formátu kódu platby: XXXX-XXXX-XXXX.

Návratová hodnota

Návratovou hodnotou je objekt typu Promise<void>, který oznamuje výsledek změny kódu platby:

• then – je voláno v případě úspěšné změny,
• catch – pokud dojde k chybě.

Příklady

Úspěch

void

Chyba

Error('Unknown error')

updateLocale()

Metoda updateLocale umožňuje změnit jazyk rozhraní u již existující instance Core. Nový jazyk je předán jako parametr a musí odpovídat výčtu TLanguage. Změna se projeví i ve všech modulech, které jsou na Core napojeny.

• přijímá jediný parametr local, který musí nabývat hodnoty z výčtu TLanguage.
• Vrací objekt typu TUpdateValueResponse.

Použití

const changeResult = instanceCore.updateLocale('cs');
if (!changeResult.ok) {
   // nepodařilo se změnit jazyk
   console.error('Comgate Checkout:', changeResult.reason);
}

Parametry

Metoda přijímá jedinný parametr, který je typu TLanguage.

Návratová hodnota

Návratová hodnota je objekt typu TUpdateValueResponse a oznamuje stav změny jazyka.

Typ TUpdateValueResponse

Atribut	Typ	Povinný	Popis
ok	boolean	Ano	Vrací true, pokud se změna jazyka zdařila, jinak false.
reason	string	Ne	Pokud změna jazyka selže, obsahuje detailní popis příčiny problému.

Příklady

Úspěch

{
  ok: true
}

Chyba

{
  ok: false,
  reason: "Invalid locale: 'cze'. Allowed: [...]."
}

getLocale()

Metoda getLocale vrací aktuálně nastavený jazyk rozhraní používaný instancí Core a ostatními moduly Checkout SDK. Hodnota odpovídá dvoupísmennému kódu jazyka definovanému typem TLanguage.

• Nepřijímá žádné parametry.
• Vrací string (hodnota z výčtu TLanguage).

Použití

const coreLocale = instanceCore.getLocale();
console.log('Jazyk:', coreLocale); // vypíše například 'Jazyk: cs'

Parametry

Metoda nepřijímá žádné parametry.

Návratová hodnota

Návratová hodnota je typu string a může nabývat možností definovaných ve výčtu TLanguage.

Příklady

"cs"

version()

Vrací verzi modulu Core.

• Funkce vrací objekt s verzí a případně i revizí.

Použití

const coreInstanceVersion = instanceCore.version();
console.log('Loader version:', coreInstanceVersion.version); // vypíše 2.0.12
console.log('Loader revision:', coreInstanceVersion.revision); // vypíše 2025-08-25

Parametry

Funkce nepřijímá žádné parametry.

Návratová hodnota

Návratovou hodnotou je vždy objekt typu TCheckoutVersion.

TCheckoutVersion

Atribut	Typ	Povinný	Popis
version	string	Ano	Verze modulu ve formátu major.minor.patch.
revision	string	Ano	Identifikátor revize - datum sestavení.

Příklady

Ukázka struktury odpovědi:

{
  "version": "1.0.12",
  "revision": "2025-08-25",
}

Funkční moduly

Po úspěšné implementaci modulu Core lze integraci rozšířit o další funkční moduly, například:

• ModuleApplePay pro platby prostřednictvím Apple Pay,
• ModulGooglePay pro platby prostřednictvím Google Pay.

Tyto moduly využívají instanci Core jako referenční objekt a sdílejí s ní jednotnou konfiguraci i stav platby.

Implementační ukázka

Níže uvedená ukázka předvádí plnou implementaci modulu Core a jeho použití v e-shopu.

Statický scénář

Použití Loaderu a volání funkce createCoreInstance najdete v předchozím příkladu.

function onPaidHandler(payload: TCheckoutOnPaidParams) {
  console.log("onPaid", payload);
  // DIY: vistory screen - platba zaplacena
}

function onCancelledHandler(payload: TCheckoutOnCancelledParams) {
  console.log("onCancelled", payload);
  // DIY: defeat screen - platba byla zrušena
}

function onPendingHandler(payload: TCheckoutOnPendingParams) {
  console.log("onPending", payload);
  // DIY: retry payment screen - pokus se nezdařil, zkusit znovu
}

function onErrorHandler(payload: TCheckoutOnErrorParams) {
  console.log("onError", payload);
  // DIY: failure screen - vznikla chyba, opakuje poději
  // refresh stránky?
}

function onPaymentStartedHandler() {
  console.log("onPaymentStarted");
  // DIY: zobrazit animaci zpracování platby
}

function onPaymentStoppedHandler() {
  console.log("onPaymentStopped");
  // DIY: skrýt animaci zpracování platby
}

async function createCoreInstance(mappedCore: TModuleMountCore): CheckoutCore | null {
  return mappedCore.create({
    checkoutId,
    transactionId, // pouze pro statický scénář
    locale: "cs",
    onPaid: onPaidHandler,
    onCancelled: onCancelledHandler,
    onPending: onPendingHandler,
    onError: onErrorHandler,
    onPaymentStarted: onPaymentStartedHandler,
    onPaymentStopped: onPaymentStoppedHandler,
    debug: true, // v produkci vypnout
  })
  .then((instance: CheckoutCore) => {
    return instance;
  })
  .catch((error: unknown) => {
    console.error("Comgate Checkout: chyba při vytváření instance CORE", error);
    return null;
  });
}