Konfigurace
Pro správnou funkci Checkout SDK je nutné nakonfigurovat obchod v systému Comgate a ověřit domény pro jednotlivé platební metody. Propojení obchodu, prostřednictvím něhož se platby zakládají a zpracovávají, musí být rovněž řádně nastaveno.
Před zahájením konfigurace je nutné si důkladně rozmyslet, jaké služby budou přes Checkout provozovány.
V současné chvíli jsou k dispozici pouze služby:
- Apple Pay
- Google Pay
Sekce tutoriálu, které se týkají nevyžadovaných služeb, je vhodné při integraci přeskočit.
Založení obchodu
S podpisem smlouvy o poskytování platebních služeb a se založením obchodu vám ochotně pomůže naše zákaznická podpora.
Konfigurace v klientském portálu
Pro zahájení konfigurace obchodu se přihlašte do klientského portálu Comgate pod profilem, který má dostatečná oprávnění pro správu integrace obchodu, na kterém bude Checkout SDK implementován.
Aktivace Checkout SDK
Aktivace je velice jednoduchá, stačí postupovat podle návodu:
- V horním menu vyberte Integrace a v části Nastavení obchodů vyberte obchod, pro který chcete Checkout SDK aktivovat.
- V horní části stránky vyberte kartu Propojení obchodu a následně ze seznamu vyberte propojení, přes které chcete Checkotu SDK provozovat.
Doporučujeme pro každou integraci založit nové propojení obchodu. Ověření domény Google Pay a Apple Pay probíhá pouze při první aktivaci Checkout SDK na daném obchodě. jakákoliv další propojení přebírají konfiguraci z obchodu.
- Najděte položku Checkout SDK a zaklikněte ji.
- Dojde k rozbalení dalších nastavení pro Checkout SDK. V této části povolte všechny služby, které chcete prostřednictvím Checkout SDK provozovat.
- Do pole Povolené originy vyplňte všechny originy, na kterých bude Checkout SDK provozováno – včetně vývojových a testovacích. Každý origin se uvádí na samostatném řádku. Řádky začínající znakem
#jsou považovány za komentáře a jsou ignorovány.
Příklad:
# produkce
https://www.vas-eshop.cz
# nebo lze mít komentář i na stejném řádku za originem
# (oddělen je první mezerou)
https://test.vas-eshop.cz testovací prostředí
Checkout SDK bude fungovat pouze na originech uvedených v tomto poli. Pokud origin chybí, platební rozhraní se nenačte.
- Klikněte na tlačítko Uložit.
Tím je konfigurace dokončena a připravena k případnému ověření domén, pokud již ověření nebylo pro daný obchod provedeno v rámci jiného propojení.
Získání checkoutId
Pro využití Checkout SDK je nutné získat hodnotu checkoutId, která slouží k jednoznačné identifikaci propojení obchodu:
- přejděte na seznam propojení obchodu, viz kroky 1 a 2 výše v části Aktivace Checkout SDK.
- V seznamu propojení obchodu najděte požadované propojení a klikněte na symbol oka pro zobrazení detailu.
- Na stránce detailu sjeďte dolů a najděte položku Identifikátor Checkout SDK (bude ve formátu UUIDv4).
Hodnota Identifikátor Checkout SDK by měla být zaznamenána pro další použití (případně je nutné vědět, kde ji lze znovu nalézt).
Ověření domény
Každá služba zpracovávající platební data vyžaduje ověření domény, na níž je provozována. Podmínky tohoto ověření jsou určovány poskytovatelem služby a společnost Comgate je nemůže jakkoliv ovlivnit.
Ověření proveďte pouze pro služby, které mají být používány. V případě, že ověření neprovedete nyní, je možné ho provést kdykoliv později. Bez ověření nebude daná služba funkční na produkci.
Apple Pay
Pro správnou funkci Apple Pay je vyžadováno ověření domény, na níž je služba provozována. Toto ověření je povinné i pro vývojové a testovací prostředí, což je určitý problém.
Specifické chování mimo produkci
Apple Pay má skvělou podporu u platebních bran, ale samotný Apple komplikuje lokální vývoj.
Pro zobrazení rozhraní Apple Pay musí web běžet přes HTTPS a doména musí být ověřena u Apple pomocí well-known souboru a registrace. V produkci to není problém – HTTPS je standardem a ověřovací soubor se nahraje během chvilky.
Při vývoji je situace složitější. Lokální server na localhost Apple Pay nepodporuje a pokus o registraci localhost:8080 selže. Tlačítko se sice po spuštění přes HTTPS zobrazí, ale platbu – ani testovací – není možné provést. Doména musí být vždy registrována u Apple.
Zdroj: https://medium.com
V současnosti není možné Apple Pay na localhostu plnohodnotně testovat. Cílovým bodem integrace Web Checkout SDK je pouze dosažení zobrazení tlačítka; samotný platební tok lze otestovat až v produkčním prostředí.
Ověření produkční domény
Apple vyžaduje pro ověření domény speciální soubor apple-developer-merchantid-domain-association. Tento soubor musí být umístěn do souborové struktury webu a zpřístupněn na přesně určené URL.
Verifikační soubor je možné stáhnout prostřednictvím Merchant API z endpointu
/v2.0/appleDomainAssociation. Pro přístup na API použijte přihlašovací údaje merchant a secret z propojení, u něhož bylo v předchozích krocích povoleno Checkout SDK.
Co dělat pokud mi endpint appleDomainAssociation ohlásí chybu "Only one card method is allowed."?
K této situaci dochází pouze tehdy, pokud jsou u obchodu aktivovány dvě různé karetní metody současně. Systém v takovém případě nedokáže určit, který validační soubor má vrátit, a označí stav jako kolizi.
Jde o velmi specifický a ojedinělý scénář, pro který není zatím účelné připravovat univerzální návod. Je efektivnější jej řešit individuálně prostřednictvím podpory.
V případě výskytu je nutné obrátit se na podporu. Ta zajistí buď přímé vyřešení problému, nebo předání na odpovědné specialisty.
Validační soubor
Po stažení validačního souboru je nutné jej nahrát na vaši doménu nebo subdoménu. Aby bylo ověření funkční, musí být soubor dostupný například na adrese:
https://www.vas-eshop.cz/.well-known/apple-developer-merchantid-domain-association. Díky tomu bude možné provozovat Apple Pay na https://www.vas-eshop.cz/.
Pokud má být Apple Pay dostupné i na dalších subdoménách, je nutné provést stejný postup pro každou z nich zvlášť a zpřístupnit tak validační soubor například na subdoméně https://checkout.vas-eshop.cz/.well-known/apple-developer-merchantid-domain-association
V odpovědi endpointu je vrácen pouze obsah souboru. Stažený obsah musí být uložen do výše jmenovaného souboru na disk a nahrán na server beze změny. Soubor nesmí obsahovat zalomení řádku na konci! obsah je tvořen pouze jedném řádkem. Kódování souboru musí být ASCII nebo UTF-8.
Jakákoliv nekonzistence s požadavky na vlastnosti souboru povede k odmítnutí souboru ze strany systémů Apple.
Obsah souboru se v určitých intervalech mění. Přestože ke změnám nedochází často, doporučuje se implementovat mechanismus automatické výměny. Aktualizace by měla probíhat alespoň jednou denně, ideálně v ranních hodinách před začátkem špičky objednávek, aby se předešlo případným problémům s placením.
⚠️ Společnost Comgate nenese odpovědnost za nemožnost provádění plateb v případě, že validační soubor na doméně obchodníka nebude včas aktualizován.
Správné nahrání souboru je nutné ověřit v klientském portálu v detailu propojení obchodu kliknutím na tlačítko "Zkontrolovat pro NAZEV_METODY". Po zobrazení zelené potvrzovací hlášky je do systému zadán požadavek na registraci domény u Apple. Zpracování probíhá automaticky a standardně je dokončeno do 10 minut. Ve výjimečných případech může trvat několik hodin, proto se doporučuje vyčkat alespoň 24 hodin.
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 Apple Pay sahá pro obsah souboru.
Stavy registrace
Po provedení kontroly validity v portálu je zahájena automatická registrace domény, která může nabývat následujících stavů:
| Stav | Popis |
|---|---|
| Povoleno | Registrace byla úspěšně dokončena a služba je aktivní. |
| Zakázáno | Služba je vypnuta. |
| (čeká na registraci) | Doména čeká na zpracování registrace, které bude provedeno automaticky. |
| (čeká na přeregistraci) | Doména čeká na zpracování přeregistrace, které bude provedeno automaticky. |
| (zakázáno pro celý obchod) | Apple Pay je zakázáno pro celý obchod; detaily je možné získat prostřednictvím podpory. |
| (chyba registrace) | Při registraci došlo k chybě. Doporučený postup: deaktivujte Apple Pay, uložte změnu, následně jej znovu aktivujte a uložte. Pokud problém přetrvává a žádost o (pře)registraci není zpracována, obraťte se na zákaznickou podporu. |
Google Pay
Na rozdíl od Apple je proces u Google jednodušší. Během vývoje lze integraci provozovat v testovacím režimu (podrobnosti viz dále) a teprve při nasazení do produkce je nutné provést schválení domény a přepnout konfiguraci na produkční režim.
Google Pay nevyžaduje umístění validačního souboru na doménu, vyžaduje však její schválení v portálu Google Pay Console. Postup je popsán v oficiální dokumentaci. Pro tuto fázi postačí zřízení přístupu do portálu. V rámci implementace Google Pay se k tomuto kroku vrátíte, abyste provedli ověření domény a aktivaci produkční implementace.
Google Pay Merchant ID
Při implementaci Web Checkout SDK do vlastního e-shopu je nezbytné v rámci vytvoření profilu v Google Pay Console zaznamenat příslušné Merchant ID. Tento identifikátor se následně uvádí v parametru payment.googlePayMerchantId při konfiguraci modulu Google Pay.
Hodnotu Merchant ID naleznete v pravém horním rohu hlavičky stránky Google Pay Console. Identifikátor je uveden ve formátu BCR2AN9TWDNZ7G2L či v obdobném tvaru.
Ověření produkční domény
Pro ověření produkční domény je nutné mít účet v Google Pay Console. Po přihlášení zvolte v levém menu položku „Rozhraní API služby Google Pay“ a v sekci „Integrate with your website“ klikněte na „+ Add website“.
Vyplňte URL (včetně subdomény), jako typ integrace zvolte „Brána“ a nahrajte pět snímků obrazovky znázorňujících průběh procesu placení prostřednictvím Google Pay. Tyto snímky slouží ke schválení ze strany Google a musí odpovídat brand guidelines. Bez jejich splnění nebude integrace schválena.
Návrh tlačítka lze vygenerovat v simulátoru, avšak tyto návrhy nedoporučujeme používat pro účely schvalování.
Uvedené screenshoty doporučujeme pořídit z počítače:
- výběr produktu – uživatel si prohlíží produkt nebo službu,
- obrazovka před nákupem – uživatel je připraven provést nákup,
- výběr platební metody – uživatel zvolí Google Pay,
- obrazovka platby Google Pay – uživateli se zobrazí uložené platební údaje. (Poznámka: Android neumožňuje pořídit screenshot této obrazovky, použijte proto jiné zařízení k jejímu vyfocení),
- obrazovka po nákupu – uživatel úspěšně dokončil platbu.
Na screenshoty jsou kladeny také určité požadavky:
- Každý snímek může mít maximální velikost 1 MB.
- Jeden screenshot lze použít pro více kategorií, pokud odpovídá procesu.
Po vyplnění formuláře klikněte v pravém dolním rohu na tlačítko „Uložit“ a proveďte důkladnou kontrolu – po odeslání žádosti již nelze provádět změny.
Posuňte stránku nahoru a ověřte, že splňujete všechny požadavky:
- první zaškrtávací políčko provedl Comgate za vás, proto jej můžete potvrdit,
- druhé políčko – systémová ověření – zajišťuje Checkout automaticky. Vaším úkolem je pouze zajistit soulad s brand guidelines, poté jej můžete potvrdit,
- funkční testy u třetího políčka provedl opět Comgate, příslušné políčko tedy můžete také zaškrtnout.
Na webu nesmí být uvedeno, že se jedná o testovací nebo demo prostředí. Aby byla doména schválena, musí prezentovat plně produkční produkt.
Jakmile splňujete všechny požadavky ke schválení, odešlete žádost kliknutím na „Submit for approval“.
Nedodržení brand guidelines může mít za následek pozastavení přístupu ke službě Google Pay až do provedení nápravy. Tento proces je plně v kompetenci společnosti Google a Comgate jej nemůže ovlivnit.
Řešení problémů se schválením
Pokud Google žádost o schválení zamítne, zašle vám e-mail s podrobným vysvětlením a instrukcemi pro další postup.
V případě nejasností se můžete přímo z portálu Google Pay Console obrátit na zákaznickou podporu Google prostřednictvím „Okamžitá podpora“ v levém menu. Odpověď obvykle obdržíte do 48 hodin, přičemž první reakce bývají často obecného charakteru – nenechte se tím odradit.
Při problémech s registrací domény se vždy obracejte primárně na podporu Google, protože Comgate v této oblasti nemá rozhodovací pravomoc a naše zákaznická podpora vás s případnými dotazy pravděpodobně odkáže zpět na tým Google Pay.
Příprava vývojového prostředí
Pro úspěšnou integraci je nezbytné mít připravené kvalitní vývojové prostředí, které umožní efektivní implementaci potřebných funkcí. Zvláštní pozornost vyžaduje konfigurace prostředí pro tlačítko Apple Pay.
HTTPS
Základním předpokladem pro správnou funkčnost je provozování lokálního projektu na HTTPS.
V projektech využívajících Vite lze použít například:
@vitejs/plugin-basic-ssl– oficiální balíček Vite [dokumentace]vite-plugin-mkcert– vhodná alternativa [dokumentace]
Pro ostatní nástroje je nutné zvolit vlastní řešení.
Předem registrovaná vývojová doména
Pro testování procesu Apple Pay poskytuje společnost Comgate dvě předem registrované domény, které lze využít během vývoje. Tyto domény byly vašemu obchodu zaregistrovány při aktivaci Checkout SDK a jsou připraveny k použití.
Tento krok je nepovinný a není nutný pro správnou funkčnost Checkout SDK v produkčním prostředí.
Bez jeho provedení však není při vývoji na localhost možné spustit platební rozhraní Apple Pay a otestovat celý proces platby – a to ani u testovacích transakcí. Samotná tlačítka se zobrazí.
Úprava souboru hosts
Pro lokální testování je nezbytné upravit soubor hosts ve vašem operačním systému. Použití adresy localhost nebo přímé IP adresy nejsou u Apple Pay podporovány. Na localhostu s HTTPS se zobrazí pouze tlačítka služeb.
Pro správnou konfiguraci zjištěte v klientském portálu Comgate, jakého poskytovatele používáte pro zpracování karetních transakcí. Podporované hodnoty jsou:
CARD_CZ_CSOB_2CARD_CZ_COMGATE
- CARD_CZ_COMGATE
- CARD_CZ_CSOB_2
Nakonfigurujte svůj vývojový server (např. nginx, Apache, Vite.js, Next.js, ...) tak, aby byla projektu přiřazena doména:
Poté upravte soubor hosts, aby uvedená doména směřovala na váš vývojový stroj (localhost).
- Linux
- macOS
- Windows
- otevřete terminál
- vytvořte zálohu souboru
hostspříkazemsudo cp /etc/hosts /etc/hosts.bak - otevřete soubor
hostspříkazemsudo nano /etc/hosts - na konec souboru přidejte řádek
- pokud vyvíjíte vzdáleně, použijte místo
127.0.0.1IP adresu serveru (např. Docker) - uložte soubor
- otevřete aplikaci Terminál
- vytvořte zálohu souboru
hostspříkazemsudo cp /etc/hosts /etc/hosts.bak - otevřete soubor
hostspříkazemsudo nano /etc/hosts - na konec souboru přidejte řádek
- pokud vyvíjíte vzdáleně, použijte místo
127.0.0.1IP adresu serveru (např. Docker) - uložte soubor
- v adresáři
C:\windows\system32\drivers\etcvyhledejte souborhostsa zkopírujte jej na plochu - vytvořte zálohu souboru
hosts - otevřete původní soubor v textovém editoru
- na konec souboru přidejte řádek
- pokud vyvíjíte vzdáleně, použijte místo
127.0.0.1IP adresu serveru (např. Docker) - uložte soubor a zkopírujte jej zpět do původního adresáře (je vyžadováno oprávnění administrátora)
Po dokončení konfigurace by měla adresa směřovat na váš vývojový stroj. Apple Pay a Google Pay by měly být připraveny k použití.
Pokud bude na vývojovém prostředí použita produkční platba (nebyla založena s parametrem test=true), hrozí reálné riziko stržení finančních prostředků.
Při vývoji se tedy doporučuje pracovat primárně s testovacími platbami nebo s platbami v malých částkách.