Tutoriál - postup implementace

Krok 1: Vytvoření a konfigurace propojení obchodu v klientském portálu

Doporučujeme vytvořit nové propojení obchodu a používat jej výhradně pro platby zpracovávané prostřednictvím Comgate Checkout SDK.

Upozornění

Pro zpracování platby prostřednictvím Checkout SDK musí být použity údaje (Identifikátor Checkout SDK, např. 2042b190-0c31-4b34-8ce4-xxxxxxxxxxxx) ze stejného propojení obchodu, jakým byla platba založena v systému Comgate.

Zobrazení seznamu propojení obchodu

1. v klientském portálu vyberte v horním menu Integrace -> Nastevní obchodu a zvolte váš obchod
2. pod nadpisem stránky vyberte záložku Propojení obchodu

Vytvoření nového propojení obchodu

• pro více informací se podívejte do dokumentace

Aktivace Checkout SDK na propojení obchodu

1. vyberte Upravit propojení obchodu (symbol tužky vpravo)
2. Zaklikněte Povolit Checkout SDK
3. zaklikněte Apple Pay, pokud ho plánujete používat
4. zaklikněte Google Pay, pokud ho plánujete používat
5. klikněte na tlačítko Uložit
6. vyčkejte na uložení a zobrazení seznamu propojení obchodu
7. zobrazte detail uloženého propojení (symbol oka vpravo)
8. poznamenejte si hodnotu Identifikátor Checkout SDK, bude potřeba níže

Detail propojení obchodu by následně měl obsahovat i tyto informace:

Krok 2: Příprava domény pro Checkout SDK (pouze Apple Pay a Google Pay)

Informace

Tento krok je nepovinný a je vyžadován pouze v případě, že bude docházet k implementaci Google Pay nebo Apple Pay.

A) Ověření domény pro Apple Pay

K ověření domény pro Apple pay je potřeba stáhnout speciální verifikační soubor, zpřístupnit ho na konkrétní URL a na samotný závěr zkontrolovat správné náhrání onoho staženého souboru. Tím dojde k zahájení procesu automatické zaregistrace domény v Apple.

Před tím, než dojde k nahrání souboru na vaši doménu je potřeba rozhodnout, jakou metodou se budou zpracovávat karetní transakce. Pro Apple Pay poskytujeme 2 podporované metody: CARD_CZ_CSOB_2 a CARD_CZ_COMGATE. Tuto informaci je možné zjistit v Klientském portálu na stránce Nastavení obchodu v záložce Platební metody. V seznamu Povolené platební metody zkuste vyhledat všechny metody začínající na CARD_ a měla by být vždy zobrazena maximálně jedna z podporovaných. Pokud jich je zobrazeno více, použije se první dle tohoto pořadí: CSOB, COMGATE. Pokud ovšem narazíte pouze na CARD_CZ_BS a přesto chcete používat Google Pay a Apple Pay v košíku e-shopu, je nutné zvážit migraci na jednu z podporovaných karetních metod.

Pro metodu CARD_CZ_CSOB_2 stáhněte soubor:
https://payments.comgate.cz/data/apple-pay/csob/apple-developer-merchantid-domain-association

Pro metodu CARD_CZ_COMGATE stáhněte soubor:
https://payments.comgate.cz/data/apple-pay/comgate/apple-developer-merchantid-domain-association

Stažený soubor je potřeba zpřístupnit na adrese: https://www.vas-web.cz/.well-known/apple-developer-merchantid-domain-association.

Správné nahrání souboru je nutné si ověřit v Klientském portálu na detailu propojení obchodu, a to kliknutím na tlačítko "Zkontrolovat pro NAZEV_METODY". Ve chvíli, kdy dojde k zobrazení zelené potvrzovací hlášky, zadá se do našeho systému požadavek o registraci vaší domény v Apple. Zpracování probíhá zcela automaticky a je zpravidla dokončeno do 10 minut. V ojedinělých případech může trvat i několik hodin. Vyčkejte až 24 hodin a stav znovu zkontrolujte (je dostupný na detailu propojení obchodu).

Informace

Soubor apple-developer-merchantid-domain-association musí na doméně zůstat po celou dobu používání Apple Pay v košíku e-shopu. Při každé platbě si servery Apple sahají pro obsah souboru a validují ho.

Společnost Apple vyžaduje dodržování pravidel pro použití tlačítka Apple Pay na vašem e-shopu. Pravidla lze nalézt na adrese: https://developer.apple.com/design/human-interface-guidelines/apple-pay/#Using-Apple-Pay-buttons

Při nedodržení těchto pravidel může být přístup k funkcím Comgate Checkout SDK - Apple Pay pozastaven, a to až do opravy použití v souladu s pravidly společnosti Apple.

Možné stavy registrace

Stav	Popis
Povoleno	registrace úspěšně provedena a funkce je zapnuta
Zakázáno	funkce je vypnuta
(čeká na registraci)	čeká na vyřízení, bude provedeno
(čeká na přeregistraci)	čeká na vyřízení, bude provedeno
(zakázáno pro celý obchod)	Apple Pay je zakázáno pro celý obchod, detaily se dozvíte na zákaznické podpoře
(chyba registrace)	při registraci vznikla chyba (Zkuste Apple Pay deaktivovat, změnu uložit a následně opět znovu aktivovat a uložit. Pokud tento postup nepomůže a žádost o (pře)registraci nebude zadána, kontaktujte zákaznickou podporu.)

B) Ověření domény pro Google Pay

Registraci vaší domény v Google Pay provádíme ručně. Ve chvíli, kdy aktivujete Google Pay pro Checkout SDK, budete vyzvání k zaslání screenshotů použití tlačítka Google Pay ve vašem e-shopu (viz informace níže) na adresu podpora@comgate.cz. Pokud již byla doména jednou zaregistrována s předchozím propojením, tak s vytvořením nového propojení obchodu již není potřeba tuto doménu znovu registrovat.

Upozornění

Pokud dojde k odstranění posledního propojení obchodu, u kterého bylo Google Pay pro Checkout SDK povoleno a je potřeba vytvořit nové propojení obchodu s aktivním Google Pay pro Checkout SDK, je potřeba kontaktovat zákaznickou podporu Comgate, která ověří, že je doména skutečně v Google Pay registrována a v návaznosti na to znovu aktivuje Google Pay pro Checkout SDK v novém propojení obchodu.

Pokud se chcete této komplikaci vyvarovat, založte nové propojení a aktivujte na něm Checkout SDK společně s Google Pay dříve, než odstraníte poslední propojení s aktivním Google Pay pro Checkout SDK.

Do e-mailu prosím napište informaci, že se jedná o aktivaci Google Pay pro Checkout SDK a uveďte CELOU URL obchodu, pro který chcete registraci provést.

Tyto obrázky vyžaduje společnost Google při registraci samotné domény. Registrace ze strany Google trvá několik dnů. V některých případech se může protáhnout i na několik týdnů.

V budoucnu plánujeme proces automatizovat.

Tip

Prosíme, připravte si sadu 5 obrázků, které budou ukazovat použití Google Pay tlačítka ve vašem webu.

Pro hladké schválení ze strany společnosti Google je potřeba dodržet všechny požadavky, které jsou dostupné na adrese: https://developers.google.com/pay/api/web/guides/brand-guidelines.

Připravte si prosím tyto obrázky (doporučujeme pořídit z počítače):

1. výběr produktu (když uživatel prohlíží produkt nebo službu),
2. obrazovka před nákupem (když je uživatel připraven provést nákup),
3. obrazovka platební metody (když uživatel vybere jako platební metodu Google Pay),
4. obrazovka platby Google Pay (když se uživateli zobrazí platební údaje, které si uložil do Google Pay
   Tip: Android vám nedovolí pořídit snímek obrazovky této obrazovky, takže vyfoťte obrazovku pomocí jiného zařízení.),
5. obrazovka po nákupu (když uživatel provedl úspěšný nákup)

Více na: https://developers.google.com/pay/api/web/guides/brand-guidelines#put-it-all-together

Každý screenshot může mít maximálně 1MB. Stejný screenshot se může v některých případech použít pro více kategorií.

Obrázek tlačítka pro případné zakomponování do stránky (pomocí GIMP/Photoshop) lze vygenerovat na adrese: https://developers.google.com/pay/api/web/guides/resources/customize

Při nedodržení těchto pravidel může být přístup k funkcím Comgate Checkout SDK - Google Pay pozastaven, a to až do opravy použití v souladu s pravidly společnosti Google.

Možné stavy registrace

Stav	Popis
Povoleno	registrace úspěšně provedena a funkce je zapnuta
Zakázáno	funkce je vypnuta
(čeká na obrázky pro registraci)	čeká na dodání obrázků pro registraci domény
(čeká na registraci)	čeká na vyřízení, bude provedeno
(čeká na potvrzení registrace v Google)	čeká na schválení společností Google
(zakázáno pro celý obchod)	Google Pay je zakázáno pro celý obchod, detaily se dozvíte na zákaznické podpoře
(chyba registrace)	při registraci vznikla chyba, detaily se dozvíte na zákaznické podpoře

Krok 3: Příprava vývojového prostředí na localhostu

Informace

Tento krok je nepovinný a není potřeba ke správnému fungování Checkout SDK na produkci. Při vývoji na localhostu bez tohoto kroku není možné spustit platební rozhraní služeb Apple Pay a Google Pay a otestovat si celý proces placení - a to ani pro testovací platby. Samotná tlačítka budou na webu zobrazena vždy.

Pokud chcete při vývoji funkce lokálně testovat, je potřeba upravit soubor hosts ve vašem operačním systému. Vývoj přes adresu localhost nebo přímo přes IP adresu není možný pro testování Apple Pay a Google Pay. Na localhostu dojde pouze k zobrazení tlačítek obou služeb.

V klientském portálu si prosím zjistěte, jakého providera používáte pro zpracování karetních transakcí. Podporované hodnoty jsou CARD_CZ_CSOB_2 a CARD_CZ_COMGATE. V případě, že používáte CARD_CZ_COMGATE, tak jsou příklady konfigurace pro hosts soubor shodné a není třeba je měnit. Pokud však používáte CARD_CZ_CSOB_2, tak je potřeba v souboru hosts použít doménu checkout2.comgate.dev.

Nakonfigurujte váš vývojový server (nginx, Apache, ...), tak aby aby vašemu projektu přiřadil doménu 'checkout1.comgate.dev' a upravte hosts soubor, aby tato doména odkazovala na váš vývojový stroj.

Linux - změna hosts souboru

• otevřete terminál
• vytvořte zálohu souboru hosts pro případ chybné úpravy zadáním příkazu sudo cp /etc/hosts /etc/hosts.bak
• otevřete soubor hosts v textovém editoru zadáním příkazu sudo nano /etc/hosts
• na konec souboru přidejte řádek 127.0.0.1 checkout1.comgate.dev
• pokud vyvíjíte vzdáleně na jiném než lokálním stroji, tak zadejte místo 127.0.0.1 IP adresu serveru (dockeru, ...)
• uložte soubor

Mac - změna hosts souboru

• otevřete aplikaci Terminál
• vytvořte zálohu souboru hosts pro případ chybné úpravy zadáním příkazu sudo cp /etc/hosts /etc/hosts.bak
• otevřete soubor hosts v textovém editoru zadáním příkazu sudo nano /etc/hosts
• na konec souboru přidejte řádek 127.0.0.1 checkout1.comgate.dev
• pokud vyvíjíte vzdáleně na jiném než lokálním stroji, tak zadejte místo 127.0.0.1 IP adresu serveru (dockeru, ...)
• uložte soubor

Windows - změna hosts souboru

• v adresáři C:\windows\system32\drivers\etc nalezněte soubor hosts, který zkopírujte na plochu
• vytvořte si zálohu souboru hosts pro případ chybné úpravy
• otevřete soubor (nikoliv ten záložní) v textovém editoru
• na konec souboru přidejte řádek 127.0.0.1 checkout1.comgate.dev
• pokud vyvíjíte vzdáleně na jiném než lokálním stroji, tak zadejte místo 127.0.0.1 IP adresu serveru (dockeru, ...)
• uložte soubor a překopírujte ho zpět do původního adresáře (je vyžadováno oprávnění administrátora)

Nyní by měla adresa https://checkout1.comgate.dev/ odkazovat na váš vývojový stroj. Apply Pay a Google Pay by měly být připraveny k testování.

Krok 4: Vložení Checkout SDK do zdrojového kódu obchodu

Vložte následující JavaScript soubor do své stránky. Vhodné umístění je na před koncem prvku HEAD.

<!-- Comgate Checkout SDK version 1.x.y -->
<script src="https://static.comgate.cz/checkout/@1" async></script>

[Kód na GitHubu]

Tento kód zajistí načtení nejnovější verze naší Checkout SDK. Nemusíte se obávat, všechny majoritní verze 1 budou zpětně kompatibilní. V případě, že byste chtěli trvale používat konkrétní verzi, můžete použít její celý název, který získáte po přístupu na adresu https://static.comgate.cz/checkout/@1. Tento postup ale není doporučen, neboť byste se připravili o průběžně dodávané kompatibilní opravy a aktualizace.

Informace

Lze také použít defer místo async: <script src="..." defer></script>. Je však potřeba správně rozhodnout (viz přiložený odkaz níže), která z možností je nejvíce vyhovující vašim požadavkům.

Jak správně vložit skript do stránky

• https://www.vzhurudolu.cz/prirucka/js-async-defer-module
• https://www.growingwiththeweb.com/2014/02/async-vs-defer-attributes.html

Krok 5: Získání konfiguračních parametrů pro Checkout SDK

Veškeré konfigurační údaje pro vytvoření první instance Checkout SDK lze získat z klientského portálu z detailu propojení obchodu, které bylo pro tento účel nakonfigurováno v prvním kroce.

V současné době je 'Identifikátor Checkout SDK' jediný parametr jehož hodnotu potřebujete v Klientském portále získat. Slouží jako statický parametr pro inicializaci instance třídy ComgateCheckout. Parametr se v kódu jmenuje checkoutId.

Více informací o parametrech v sekci Definice API komponent.

Krok 6: Volba vhodného přístupu implementace

V současné době existují dva možné přístupy k implementaci Checkout SDK do košíku e-shopu:

A) Zpracování předem založené platby

Jedná se o základní a nejjednodušší implementační přístup. Na stránce není nutné provádět žádné složitější akce.

Informace

Při vytváření instance třídy ComgateCheckout je nutné znát Comgate ID transakce. To znamená, pokud se zákazník rozhodne změnit například způsob dopravy, tak je potřeba založit novou platbu s aktualizovanou cenou a následně přenačíst celou stránku.

Comgate ID transakce je do stránky možné vložit například při generování kódu na straně serveru.

Pokud je zvolen tento přístup, pokračujte krokem 7 A.

B) Dynamické založení a zpracování platby

Tento přístup umožňuje dosáhnout více dynamického chování vaší stránky.

Informace

Při vytváření instance třídy ComgateCheckout není nutné znát Comgate ID transakce. To znamená, pokud se zákazník rozhodne bezprostředně před zaplacením změnit například způsob dopravy, není to žádný problém. K založení samotné platby dojde až na samotný závěr, kdy klikne na tlačítko k provedení platby a potvrdí, že je již s parametry objednávky plně spokojen. Nemusí tak dojít ke zbytečnému přenačtení celé stránku.

Tento náročnější přístup vyžaduje implementaci části funkcionality jak na frontendu (strana prohlížeče), tak na backendu (strana serveru). Umožňuje však dosáhnout dynamičtějšího chování stránky při zpracování plateb.

Pokud je zvolen tento přístup, pokračujte krokem 7 B.

Detailní scénář zpracování platby

Když jsou zobrazena tlačítka Apple Pay a Google Pay není nutné mít založenou platbu v systému Comgate. Ve chvíli, kdy chce plátce zaplatit a klikne na libovolné tlačítko, dojde k ověření, zda již bylo specifikováno Comgate ID platby, či nikoliv. V případě že ano a ID je stále validní, tak placení probíhá automaticky dále.

V situaci, kdy nebylo ID platby specifikováno nebo již není validní (invalidatePayment()), tak dojde k volání callbacku onRequirePayment(...). V tomto callbacku je nutné odeslat request na váš server (backend), kde dojde k založení platby v systému Comgate pomocí tajných přihlašovacích údajů z propojení obchodu. Pro snadné odesílání requestů jsme v Comgate Checkout SDK připravili pomocnou metodu eshopRequest(...). Po založení platby by mělo být ID transakce vráceno zpět klientovi, který ho předepsaným způsobem předá ComgateCheckout instanci a ta pokračuje ve zpracování platby.

V případě, že plátce platbu v průběhu zastaví, a vrátí se do dynamického košíku, je možné již dříve dodané ID transakce zneplatnit voláním metody invalidatePayment(). Proces se zakládáním nové platby se tak opakuje. V opačném případě je použito ID transakce z předchozího pokusu.

Krok 7: Vytvoření instance Comgate Checkout SDK

Pro použití ComgateCheckout funkcí (např. Apple Pay, Google Pay) je nutné vytvořit instanci této třídy s konfiguračními parametry. Tato instance se následně stává centrálním bodem pro ovládání celé funkcionality.

Upozornění

V současné chvíli je možné na stránce používat pouze jednu instanci třídy ComgateCheckout. Při vytvoření druhé instance může dojít k neočekávanému chování aplikace.

A) Zpracování předem založené platby [Kód na GitHubu]

<script>
    // počkat na načtení Comgate Checkout SDK
    document.addEventListener("ComgateCheckoutReady", function () {
        // vytvoření ComgateCheckout instance
        window
                .ComgateCheckout({
                    checkoutId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // (povinné) získáno v kroku 5
                    locale: "cs", // (volitelné, výchozí: cs) jazyk rozhraní
                    debug: true, // (volitelné, výchozí: false) detailní vývojové informace do konzole !!! NEPOUŽÍVAT 'true' NA PRODUKCI !!!

                    // v seznamu uvádějte pouze služby, které chcete opravdu používat
                    prefetch: ['googlepay'] // (volitelné) přednačíst script pro GooglePay (ApplePay je vždy přednačteno)

                    transactionId: "XXXX-XXXX-XXXX", // (povinné) Comgate ID transakce získané po volání /v1.0/create

                    onPaid: (payload) => { // (povinné) platba byla zaplacena
                        /* TODO DIY */
                    },
                    onCancelled: (payload) => { // (povinné) platba byla zrušena, nebo expirovala
                        /* TODO DIY */
                    },
                    onPending: (payload) => { // (volitelné) v případě, že se pokus o platbu nezdařil, platba může pokračovat
                        /* TODO DIY nebo nedefinovat */
                        // pokud není vykonána žádná akce, tak je vhodné callback nedefinovat
                    },
                    onClick: (payload) => { // (volitelné) voláno po kliknutí na tlačítko, před zahájením zpracování platby [vyžadováno potvrzení]
                        /* TODO DIY nebo nedefinovat */
                        // pokud není vykonána žádná akce, tak je vhodné callback nedefinovat

                        // na konci definovaného callbacku je nutné zavolat
                        //    payload.resolve() - pokračovat v platbě
                        //    payload.reject() - zrušit akci a nepokračovat
                        // jinak dojde k uváznutí čekání
                        if ("resolve" in payload) {
                            payload.resolve();
                        }
                    },
                    onError: (payload) => { // (povinné) detaily o chybě v průběhu zpracování
                        /* TODO DIY */
                        // Podstatná část zpracování platby probíhá asynchronně a proto ji nelze navázat na standardní try-catch blok.
                        // v případě, že dojde k volání tohoto callbacku, platba již nepokračuje, Comgate ID transakce je možné využít znovu
                        // většina chyb je automaticky reportována společnosti Comgate pro jejich lazeních a případnou opravu
                        // chyby vzniklé nesprávnou implementací developera opraveny nebudou
                    }
                })
                .then((checkoutInstance) => {
                    // ComgateCheckout instance připravena pro konfiguraci konkrétních služeb
                    /* TODO DIY implementace vybraných funkcionalit */
                })
                .catch((error) => {
                    /* TODO DIY */
                    // při vytváření instance ComgateCheckout došlo k neočekávané chybě a platby nemohou být zprocesovány
                    // tyto chyby nejsou společností Comgate automatizovaně zaznamenávány a vznikají převážně nesprávnou implemtnací ComgateCheckout SDK
                    console.error("ComgateCheckout Init ERROR: ", error);
                });
    });
</script>

B) Dynamické založení a zpracování platby [Kód na GitHubu]

<script>
    // počkat na načtení Comgate Checkout SDK
    document.addEventListener("ComgateCheckoutReady", function () {
        // proměnná pro referenci na instanci ComgateCheckout
        let checkoutInstanceRef = null;

        // vytvoření ComgateCheckout instance
        window
                .ComgateCheckout({
                    checkoutId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // (povinné) získáno v kroku 5
                    locale: "cs", // (volitelné, výchozí: cs) jazyk rozhraní
                    debug: true, // (volitelné, výchozí: false) detailní vývojové informace do konzole !!! NEPOUŽÍVAT 'true' NA PRODUKCI !!!

                    // v seznamu uvádějte pouze služby, které chcete opravdu používat
                    prefetch: ['googlepay'] // (volitelné) přednačíst script pro GooglePay (ApplePay je vždy přednačteno)

                    onRequirePayment: (payload) => { // (povinné) je vyžádáno založení a dodání Comgate ID transakce
                        /* TODO DIY */
                        // při volání callbacku je potřeba provolat API e-shopu a založit novou platbu a vrátit Comgate ID transakce
                        // věškeré údaje o ceně, měně a dalších parametrech je bezpečné načítat na straně serveru a nezasílat si je ve volání zde,
                        // mohlo by totiž dojít k jejich podvržení.
                        // lze využít pomocnou metodu dodanou v payload pro odesílání requestů na váš server payload.eshopRequest(/*...*/)
                        // nebo pomocí uložení ComgateCheckout instance do proměnné checkoutInstance.eshopRequest(/*...*/)
                    },
                    onPaid: (payload) => { // (povinné) platba byla zaplacena
                        /* TODO DIY */
                    },
                    onCancelled: (payload) => { // (povinné) platba byla zrušena, nebo expirovala
                        /* TODO DIY */
                    },
                    onPending: (payload) => { // (volitelné) v případě, že se pokus o platbu nezdařil, platba může pokračovat
                        /* TODO DIY nebo nedefinovat */
                        // pokud není vykonána žádná akce, tak je vhodné callback nedefinovat
                    },
                    onClick: (payload) => { // (volitelné) voláno po kliknutí na tlačítko, před zahájením zpracování platby [vyžadováno potvrzení]
                        /* TODO DIY nebo nedefinovat */
                        // pokud není vykonána žádná akce, tak je vhodné callback nedefinovat

                        // na konci definovaného callbacku je nutné zavolat
                        //    payload.resolve() - pokračovat v platbě
                        //    payload.reject() - zrušit akci a nepokračovat
                        // jinak dojde k uváznutí čekání
                        payload.resolve();
                    },
                    onError: (payload) => { // (povinné) detaily o chybě v průběhu zpracování
                        /* TODO DIY */
                        // Podstatná část zpracování platby probíhá asynchronně a proto ji nelze navázat na standardní try-catch blok.
                        // v případě, že dojde k volání tohoto callbacku, platba již nepokračuje, Comgate ID transakce je možné využít znovu
                        // většina chyb je automaticky reportována společnosti Comgate pro jejich lazeních a případnou opravu
                        // chyby vzniklé nesprávnou implementací developera opraveny nebudou
                    }
                })
                .then((checkoutInstance) => {
                    checkoutInstanceRef = checkoutInstance;
                    // ComgateCheckout instance připravena pro konfiguraci konkrétních služeb
                    /* TODO DIY implementace vybraných funkcionalit */
                })
                .catch((error) => {
                    /* TODO DIY */
                    // při vytváření instance ComgateCheckout došlo k neočekávané chybě a platby nemohou být zprocesovány
                    // tyto chyby nejsou společností Comgate automatizovaně zaznamenávány a vznikají převážně nesprávnou implemtnací ComgateCheckout SDK
                    console.error("ComgateCheckout Init ERROR: ", error);
                });
    });
</script>

Krok 8: Nastavení zvolené funkcionality

Ve chvíli, kdy je vytvořena instance třídy ComgateCheckout, je možné prostřednictvím jejich připravených metod začít sestavovat konkrétní potřebnou funkcionalitu.

Návod implementace vybrané funkcionality je dostupný níže:

• Postup implementace tlačítka Apple Pay
• Postup implementace tlačítka Google Pay
• Zasílání požadavků na server
• Ukázky kompletní implementace