Požiadavky

Pred začatím integrácie je potrebné oboznámiť sa s požiadavkami na integráciu Web Checkout SDK. Súčasťou týchto požiadaviek je tiež dodržanie pravidiel pre používanie značky a vizuálnych prvkov podľa oficiálnych brand manuálov a integračných pokynov všetkých dotknutých platforiem (Google Pay a Apple Pay).

Upozornenie

Splnenie uvedených podmienok je nevyhnutné pre bezproblémové fungovanie platieb.

Všeobecné požiadavky

1. Aktívny účet v klientskom portáli Comgate:
   • aktívna zmluva,
   • aktivované platobné metódy (CARD_CZ_COMGATE alebo CARD_CZ_CSOB_2),
   • registrovaný obchod – doména v portáli musí presne zodpovedať doméne, na ktorej bude Checkout prevádzkovaný (vrátane subdomén).
2. HTTPS na doméne, kde pobeží Checkout.
3. Prístup do Google Pay Console (prípadne možnosť jeho zriadenia) s oprávnením Admin:
   • správa platobného profilu a registrácia domény obchodu,
   • nahranie podkladov pre brand/UI kontrolu.
4. Skúsenosť s vývojom webových aplikácií za použitia pokročilého JavaScriptu.

Technické požiadavky

1. Checkout nesmie byť používaný v iframe ani vo WebView.
   • V týchto prostrediach nie je možné zaručiť správnu funkčnosť a môže dochádzať k nepredvídateľnému správaniu.
2. Content Security Policy (CSP)
   • Povolené skripty a štýly z CDN; správne nastavené direktívy.
   • Assety SDK sa sťahujú z: https://checkout.comgate.cz/sdk/* (aj pri použití balíčka z NPM).
   • Sieťové požiadavky (XHR/fetch) smerujú na: https://payments.comgate.cz/*.
   • Všeobecné odporúčania pre CSP:
     • default-src zahŕňajú https://payments.comgate.cz, https://checkout.comgate.cz,
     • script-src zahŕňajú https://checkout.comgate.cz,
     • style-src zahŕňajú https://checkout.comgate.cz, https://fonts.googleapis.com,
     • style-src-elem zahŕňajú https://checkout.comgate.cz, https://*.gstatic.com https://fonts.googleapis.com,
     • img-src zahŕňa https://checkout.comgate.cz,
     • connect-src zahŕňa https://payments.comgate.cz.
   • Google Pay:
     • script-src zahŕňajú https://pay.google.com, https://*.gstatic.com
     • frame-src zahŕňajú https://pay.google.com, https://*.gstatic.com
     • img-src zahŕňajú https://pay.google.com, https://*.gstatic.com, https://*.googleusercontent.com, data:
     • font-src zahŕňajú https://*.gstatic.com
     • connect-src zahŕňajú https://pay.google.com, https://google.com/pay, https://*.gstatic.com, https://*.google.com
   • Apple Pay:
     • script-src zahŕňajú https://applepay.cdn-apple.com
     • font-src zahŕňajú https://applepay.cdn-apple.com
3. Možnosť implementovať vlastné procesy na backende a vytvárať vlastné endpointy (napr. založenie platby, získanie stavu, obsluha notifikácií).
4. Doména a hosting musia umožňovať publikáciu statických súborov v adresári /.well-known/ (napr. https://vas-obchod.sk/.well-known/apple-developer-merchantid-domain-association).

Nebezpečenstvo

Použitie nonce ani hash pre skripty Checkout SDK nie je v súčasnosti podporované. Príčinou je priebežné vydávanie aktualizácií modulov a dynamické sťahovanie assetov zo CDN podľa aktuálne publikovanej verzie, čo neumožňuje stabilné udržanie zodpovedajúcich hodnôt hash.

Podpora tejto funkcionality je plánovaná do budúcich verzií; konkrétny termín zatiaľ nie je stanovený.

Požiadavky platby

E-mail platiteľa

Hoci platobná brána Comgate neoficiálne umožňuje založiť platbu bez e-mailu platiteľa a tento údaj si následne vyžiada sama v priebehu procesu, Checkout SDK touto funkcionalitou nedisponuje – ak e-mail chýba, integrácia nebude fungovať správne. Preto vždy zaistite, aby bol pri založení platby uvedený platný e-mail platiteľa.

Testovacie prostredie a zariadenia

Apple Pay

Je potrebné overiť aj testovaciu doménu umiestnením súboru /.well-known/apple-developer-merchantid-domain-association a doménu mať registrovanú v klientskom portáli Comgate ako testovací obchod.

Zariadenie

Pre testovanie platieb Apple Pay je potrebné mať k dispozícii niektoré z fyzických zariadení iPhone alebo iPad so zapnutou Apple Wallet.

Google Pay

Registrácia testovacej domény v Google Pay Console nie je vyžadovaná; vykonáva sa až pred produkčným nasadením. Rovnako tak nie je potrebné mať registrovaný testovací obchod v portáli Comgate.

Zariadenie

Pre testovanie platieb Google Pay nie je potrebné vlastniť fyzické zariadenie, postačí účet Google s aktívnou Google Wallet a pridaným platobným prostriedkom.

Integráciu je na zariadení Android vždy vhodné otestovať.

Poznámka

Na localhoste možno tlačidlá zobraziť, za splnenia špecifických podmienok.

Integračné podmienky

Dodržanie nižšie uvedených podmienok je nevyhnutné pre správne fungovanie SDK, zachovanie bezpečnosti platieb a súlad s pravidlami platobných sietí.

Záväznosť

Porušenie niektorých nižšie uvedených podmienok môže viesť k obmedzeniu alebo ukončeniu poskytovania služby Checkout SDK zo strany Comgate.

Integrita platobného formulára

Zobrazenie všetkých prvkov

Všetky prvky karetného formulára — vrátane polí pre číslo karty, expiráciu, CVV a platobného tlačidla — musia zostať viditeľné, dostupné a plne funkčné.

Je zakázané:

• Skrývať časti formulára pomocou display: none, visibility: hidden, opacity: 0 alebo iných techník.
• Prekrývať formulár inými elementmi.
• Deaktivovať alebo znefunkčniť platobné tlačidlo mimo logiky SDK.
• Odstraňovať elementy formulára z DOM po inicializácii.

Zákaz manipulácie s SDK

Je zakázané:

• Upravovať, dekompilovať alebo vykonávať reverse engineering zdrojového kódu SDK.
• Volať interné (nedokumentované) metódy alebo pristupovať k interným dátovým štruktúram.
• Prepisovať alebo monkey-patchovať funkcie SDK.
• Zachytávať alebo modifikovať sieťovú komunikáciu SDK s platobným serverom.

Upozornenie

Používajte výhradne verejné API popísané v dokumentácii implementácie. Všetky ostatné rozhrania sú interné, nepodporované a môžu sa bez upozornenia zmeniť.

Spracovanie platieb

Povinné callbacky

Integrátor musí implementovať všetky povinné callbacky odovzdávané do konfigurácie Core:

Callback	Povinnosť	Účel
onPaid	Áno	Spracovanie úspešnej platby
onCancelled	Áno	Spracovanie zrušenej platby
onPending	Áno	Spracovanie neúspešného pokusu (platba zostáva aktívna)
onError	Áno	Spracovanie kritickej chyby SDK

Zákazník musí byť vždy informovaný o výsledku platby — či už úspešnom, neúspešnom alebo zrušenom.

E-mail platiteľa

Pri zakladaní platby prostredníctvom Comgate Merchant API musí byť vždy uvedený platný e-mail platiteľa. Bez e-mailu nemožno platbu spracovať prostredníctvom Checkout SDK.

Overenie platby na backende

Callback onPaid slúži na vylepšenie používateľského zážitku (okamžité presmerovanie na ďakovnú stránku). Nikdy sa nespoliehajte výhradne na frontendový callback pre potvrdenie platby. Skutočný stav platby vždy overte na svojom backende pomocou Comgate Merchant API.

Platobné metódy — pravidlá sietí

Apple Pay

• Musia byť dodržané Marketing Guidelines a Human Interface Guidelines.
• Doména musí byť overená prostredníctvom súboru /.well-known/apple-developer-merchantid-domain-association.
• Tlačidlo Apple Pay nesmie byť vizuálne modifikované nad rámec povolených konfigurácií (type, color, style).

Google Pay

• Musia byť dodržané Brand Guidelines a UX best practices.
• Doména musí byť schválená v Google Pay Console.
• Pre produkčnú prevádzku musí byť uvedený platný googlePayMerchantId.
• Tlačidlo Google Pay nesmie byť vizuálne modifikované nad rámec povolených konfigurácií (type, color).

Prevádzkové požiadavky

Testovanie pred nasadením

Pred produkčným nasadením musí integrátor overiť:

• Úspešnú platbu každou implementovanou metódou.
• Správne spracovanie neúspešnej platby a zrušenia.
• Správne správanie 3D Secure flow.
• Korektné zobrazenie na mobilných zariadeniach.

Viď Integračný checklist pre kompletný zoznam testovacích scenárov.

Aktualizácia loaderu SDK

Integrátor by mal pravidelne kontrolovať dostupnosť nových verzií SDK (primárne NPM loaderu) a aktualizovať ho na najnovšiu verziu v rámci používanej major verzie. Comgate garantuje spätnú kompatibilitu v rámci major verzie.

Zodpovednosť

• Comgate nezodpovedá za chyby vzniknuté porušením integračných podmienok, použitím nedokumentovaných API alebo prevádzkou v nepodporovanom prostredí.