Požadavky

Před zahájením integrace je nutné se seznámit s požadavky na integraci Web Checkout SDK. Součástí těchto požadavků je rovněž dodržení pravidel pro používání značky a vizuálních prvků podle oficiálních brand manuálů a integračních pokynů všech dotčených platforem (Google Pay a Apple Pay).

Upozornění

Splnění uvedených podmínek je nezbytné pro bezproblémové fungování plateb.

Obecné požadavky

1. Aktivní účet v klientském portálu Comgate:
   • aktivní smlouva,
   • aktivované platební metody (CARD_CZ_COMGATE nebo CARD_CZ_CSOB_2),
   • registrovaný obchod – doména v portálu musí přesně odpovídat doméně, na které bude Checkout provozován (včetně subdomén).
2. HTTPS na doméně, kde poběží Checkout.
3. Přístup do Google Pay Console (případně možnost jeho zřízení) s oprávněním Admin:
   • správa platebního profilu a registrace domény obchodu,
   • nahrání podkladů pro brand/UI kontrolu.
4. Zkušenost s vývojem webových aplikací za použití pokročilého JavaScriptu.

Technické požadavky

1. Checkout nesmí být používán v iframe ani ve WebView.
   • V těchto prostředích nelze zaručit správnou funkčnost a může docházet k nepředvídatelnému chování.
2. Content Security Policy (CSP)
   • Povolené skripty a styly z CDN; správně nastavené direktivy.
   • Assety SDK se stahují z: https://checkout.comgate.cz/sdk/* (i při použití balíčku z NPM).
   • Síťové požadavky (XHR/fetch) směřují na: https://payments.comgate.cz/*.
   • Obecná doporučení pro CSP:
     • default-src zahrnují https://payments.comgate.cz, https://checkout.comgate.cz,
     • script-src zahrnují https://checkout.comgate.cz,
     • style-src zahrnují https://checkout.comgate.cz, https://fonts.googleapis.com,
     • style-src-elem zahrnují https://checkout.comgate.cz, https://*.gstatic.com https://fonts.googleapis.com,
     • img-src zahrnuje https://checkout.comgate.cz,
     • connect-src zahrnuje https://payments.comgate.cz.
   • Google Pay:
     • script-src zahrnují https://pay.google.com, https://*.gstatic.com
     • frame-src zahrnují https://pay.google.com, https://*.gstatic.com
     • img-src zahrnují https://pay.google.com, https://*.gstatic.com, https://*.googleusercontent.com, data:
     • font-src zahrnují https://*.gstatic.com
     • connect-src zahrnují https://pay.google.com, https://google.com/pay, https://*.gstatic.com, https://*.google.com
   • Apple Pay:
     • script-src zahrnují https://applepay.cdn-apple.com
     • font-src zahrnují https://applepay.cdn-apple.com
3. Možnost implementovat vlastní procesy na backendu a vytvářet vlastní endpointy (např. založení platby, získání stavu, obsluha notifikací).
4. Doména a hosting musí umožňovat publikaci statických souborů v adresáři /.well-known/ (např. https://vas-obchod.cz/.well-known/apple-developer-merchantid-domain-association).

Nebezpečí

Použití nonce ani hash pro skripty Checkout SDK není v současné době podporováno. Příčinou je průběžné vydávání aktualizací modulů a dynamické stahování assetů ze CDN podle aktuálně publikované verze, což neumožňuje stabilní udržení odpovídajících hodnot hash.

Podpora této funkcionality je plánována do budoucích verzí; konkrétní termín zatím není stanoven.

Požadavky platby

E-mail plátce

Přestože platební brána Comgate neoficiálně umožňuje založit platbu bez e-mailu plátce a tento údaj si následně vyžádá sama v průběhu procesu, Checkout SDK touto funkcionalitou nedisponuje – pokud e-mail chybí, integrace nebude fungovat správně. Proto vždy zajistěte, aby byl při založení platby uveden platný e-mail plátce.

Testovací prostředí a zařízení

Apple Pay

Je nutné ověřit i testovací doménu umístěním souboru /.well-known/apple-developer-merchantid-domain-association a doménu mít registrovanou v klientském portálu Comgate jako testovací obchod.

Zařízení

Pro testování plateb Apple Pay je nutné mít k dispozici některé z fyzických zařízení iPhone nebo iPad se zapnutou Apple Wallet.

Google Pay

Registrace testovací domény v Google Pay Console není vyžadována; provádí se až před produkčním nasazením. Stejně tak není nutné mít registrovaný testovací obchod v portálu Comgate.

Zařízení

Pro testování plateb Google Pay není nutné vlastnit fyzické zařízení, postačí účet Google s aktivní Google Wallet a přidaným platebním prostředkem.

Integraci je na zařízení Android vždy vhodné otestovat.

Poznámka

Na localhostu lze tlačítka zobrazit, za splnění specifických podmínek.

Integrační podmínky

Dodržení níže uvedených podmínek je nezbytné pro správné fungování SDK, zachování bezpečnosti plateb a soulad s pravidly platebních sítí.

Závaznost

Porušení některých níže uvedených podmínek může vést k omezení nebo ukončení poskytování služby Checkout SDK ze strany Comgate.

Integrita platebního formuláře

Zobrazení všech prvků

Všechny prvky karetního formuláře — včetně polí pro číslo karty, expiraci, CVV a platebního tlačítka — musí zůstat viditelné, dostupné a plně funkční.

Je zakázáno:

• Skrývat části formuláře pomocí display: none, visibility: hidden, opacity: 0 nebo jiných technik.
• Překrývat formulář jinými elementy.
• Deaktivovat nebo znefunkčnit platební tlačítko mimo logiku SDK.
• Odstraňovat elementy formuláře z DOM po inicializaci.

Zákaz manipulace s SDK

Je zakázáno:

• Upravovat, dekompilovat nebo provádět reverse engineering zdrojového kódu SDK.
• Volat interní (nedokumentované) metody nebo přistupovat k interním datovým strukturám.
• Přepisovat nebo monkey-patchovat funkce SDK.
• Zachytávat nebo modifikovat síťovou komunikaci SDK s platebním serverem.

Upozornění

Používejte výhradně veřejné API popsané v dokumentaci implementace. Veškeré ostatní rozhraní jsou interní, nepodporovaná a mohou se bez upozornění změnit.

Zpracování plateb

Povinné callbacky

Integrátor musí implementovat všechny povinné callbacky předávané do konfigurace Core:

Callback	Povinnost	Účel
onPaid	Ano	Zpracování úspěšné platby
onCancelled	Ano	Zpracování zrušené platby
onPending	Ano	Zpracování neúspěšného pokusu (platba zůstává aktivní)
onError	Ano	Zpracování kritické chyby SDK

Zákazník musí být vždy informován o výsledku platby — ať už úspěšném, neúspěšném nebo zrušeném.

E-mail plátce

Při zakládání platby prostřednictvím Comgate Merchant API musí být vždy uveden platný e-mail plátce. Bez e-mailu nelze platbu zpracovat prostřednictvím Checkout SDK.

Ověření platby na backendu

Callback onPaid slouží pro vylepšení uživatelského zážitku (okamžité přesměrování na děkovnou stránku). Nikdy se nespoléhejte výhradně na frontendový callback pro potvrzení platby. Skutečný stav platby vždy ověřte na svém backendu pomocí Comgate Merchant API.

Platební metody — pravidla sítí

Apple Pay

• Musí být dodrženy Marketing Guidelines a Human Interface Guidelines.
• Doména musí být ověřena prostřednictvím souboru /.well-known/apple-developer-merchantid-domain-association.
• Tlačítko Apple Pay nesmí být vizuálně modifikováno nad rámec povolených konfigurací (type, color, style).

Google Pay

• Musí být dodrženy Brand Guidelines a UX best practices.
• Doména musí být schválena v Google Pay Console.
• Pro produkční provoz musí být uveden platný googlePayMerchantId.
• Tlačítko Google Pay nesmí být vizuálně modifikováno nad rámec povolených konfigurací (type, color).

Provozní požadavky

Testování před nasazením

Před produkčním nasazením musí integrátor ověřit:

• Úspěšnou platbu každou implementovanou metodou.
• Správné zpracování neúspěšné platby a zrušení.
• Správné chování 3D Secure flow.
• Korektní zobrazení na mobilních zařízeních.

Viz Integrační checklist pro kompletní seznam testovacích scénářů.

Aktualizace loaderu SDK

Integrátor by měl pravidelně kontrolovat dostupnost nových verzí SDK (primárně NPM loaderu) a aktualizovat ho na nejnovější verzi v rámci používané major verze. Comgate garantuje zpětnou kompatibilitu v rámci major verze.

Odpovědnost

• Comgate neodpovídá za chyby vzniklé porušením integračních podmínek, použitím nedokumentovaných API nebo provozem v nepodporovaném prostředí.