Konfigurácia
Pre správnu funkciu Checkout SDK je potrebné nakonfigurovať obchod v systéme Comgate a overiť domény pre jednotlivé platobné metódy. Prepojenie obchodu, prostredníctvom ktorého sa platby zakladajú a spracovávajú, musí byť tiež riadne nastavené.
Pred začatím konfigurácie je potrebné si dôkladne premyslieť, aké služby budú cez Checkout prevádzkované.
V súčasnosti sú k dispozícii iba služby:
- Apple Pay
- Google Pay
Sekcie tutoriálu, ktoré sa týkajú nevyžadovaných služieb, je vhodné pri integrácii preskočiť.
Založenie obchodu
S podpisom zmluvy o poskytovaní platobných služieb a so založením obchodu vám ochotne pomôže naša zákaznícka podpora.
Konfigurácia v klientskom portáli
Pre začatie konfigurácie obchodu sa prihláste do klientskeho portálu Comgate pod profilom, ktorý má dostatočné oprávnenia na správu integrácie obchodu, na ktorom bude Checkout SDK implementované.
Aktivácia Checkout SDK
Aktivácia je veľmi jednoduchá, stačí postupovať podľa návodu:
- V hornom menu vyberte Integrácia a v časti Nastavenia obchodov vyberte obchod, pre ktorý chcete Checkout SDK aktivovať.
- V hornej časti stránky vyberte kartu Prepojenie obchodu a následne zo zoznamu vyberte prepojenie, cez ktoré chcete Checkout SDK prevádzkovať.
Odporúčame pre každú integráciu založiť nové prepojenie obchodu. Overenie domény Google Pay a Apple Pay prebieha iba pri prvej aktivácii Checkout SDK na danom obchode. Akékoľvek ďalšie prepojenia preberajú konfiguráciu z obchodu.
- Nájdite položku Checkout SDK a zakliknite ju.
- Dôjde k rozbaleniu ďalších nastavení pre Checkout SDK. V tejto časti povoľte všetky služby, ktoré chcete prostredníctvom Checkout SDK prevádzkovať.
- Do poľa Povolené originy vyplňte všetky originy, na ktorých bude Checkout SDK prevádzkované – vrátane vývojových a testovacích. Každý origin sa uvádza na samostatnom riadku. Riadky začínajúce znakom
#sú považované za komentáre a sú ignorované.
Príklad:
# produkcia
https://www.vas-eshop.sk
# alebo možno mať komentár aj na rovnakom riadku za originom
# (oddelený je prvou medzerou)
https://test.vas-eshop.sk testovacie prostredie
Checkout SDK bude fungovať iba na originoch uvedených v tomto poli. Ak origin chýba, platobné rozhranie sa nenačíta.
- Kliknite na tlačidlo Uložiť.
Tým je konfigurácia dokončená a pripravená na prípadné overenie domén, ak overenie ešte nebolo pre daný obchod vykonané v rámci iného prepojenia.
Získanie checkoutId
Pre využitie Checkout SDK je potrebné získať hodnotu checkoutId, ktorá slúži na jednoznačnú identifikáciu prepojenia obchodu:
- prejdite na zoznam prepojení obchodu, viď kroky 1 a 2 vyššie v časti Aktivácia Checkout SDK.
- V zozname prepojení obchodu nájdite požadované prepojenie a kliknite na symbol oka pre zobrazenie detailu.
- Na stránke detailu zíďte dolu a nájdite položku Identifikátor Checkout SDK (bude vo formáte UUIDv4).
Hodnota Identifikátor Checkout SDK by mala byť zaznamenaná pre ďalšie použitie (prípadne je potrebné vedieť, kde ju možno znova nájsť).
Overenie domény
Každá služba spracovávajúca platobné dáta vyžaduje overenie domény, na ktorej je prevádzkovaná. Podmienky tohto overenia sú určované poskytovateľom služby a spoločnosť Comgate ich nemôže akokoľvek ovplyvniť.
Overenie vykonajte iba pre služby, ktoré majú byť používané. V prípade, že overenie nevykonáte teraz, je možné ho vykonať kedykoľvek neskôr. Bez overenia nebude daná služba funkčná na produkcii.
Apple Pay
Pre správnu funkciu Apple Pay je vyžadované overenie domény, na ktorej je služba prevádzkovaná. Toto overenie je povinné aj pre vývojové a testovacie prostredie, čo je určitý problém.
Špecifické správanie mimo produkcie
Apple Pay má skvelú podporu u platobných brán, ale samotný Apple komplikuje lokálny vývoj.
Pre zobrazenie rozhrania Apple Pay musí web bežať cez HTTPS a doména musí byť overená u Apple pomocou well-known súboru a registrácie. V produkcii to nie je problém – HTTPS je štandardom a overovací súbor sa nahrá v priebehu chvíľky.
Pri vývoji je situácia zložitejšia. Lokálny server na localhost Apple Pay nepodporuje a pokus o registráciu localhost:8080 zlyhá. Tlačidlo sa síce po spustení cez HTTPS zobrazí, ale platbu – ani testovaciu – nie je možné vykonať. Doména musí byť vždy registrovaná u Apple.
Zdroj: https://medium.com
V súčasnosti nie je možné Apple Pay na localhoste plnohodnotne testovať. Cieľovým bodom integrácie Web Checkout SDK je iba dosiahnutie zobrazenia tlačidla; samotný platobný tok možno otestovať až v produkčnom prostredí.
Overenie produkčnej domény
Apple vyžaduje pre overenie domény špeciálny súbor apple-developer-merchantid-domain-association. Tento súbor musí byť umiestnený do súborovej štruktúry webu a sprístupnený na presne určenej URL.
Verifikačný súbor je možné stiahnuť prostredníctvom Merchant API z endpointu
/v2.0/appleDomainAssociation. Pre prístup na API použite prihlasovacie údaje merchant a secret z prepojenia, u ktorého bolo v predchádzajúcich krokoch povolené Checkout SDK.
Čo robiť, ak mi endpoint appleDomainAssociation ohlási chybu "Only one card method is allowed."?
K tejto situácii dochádza iba vtedy, ak sú u obchodu aktivované dve rôzne karetné metódy súčasne. Systém v takom prípade nedokáže určiť, ktorý validačný súbor má vrátiť, a označí stav ako kolíziu.
Ide o veľmi špecifický a ojedinelý scenár, pre ktorý nie je zatiaľ účelné pripravovať univerzálny návod. Je efektívnejšie ho riešiť individuálne prostredníctvom podpory.
V prípade výskytu je potrebné obrátiť sa na podporu. Tá zaistí buď priame vyriešenie problému, alebo odovzdanie zodpovedným špecialistom.
Validačný súbor
Po stiahnutí validačného súboru je potrebné ho nahrať na vašu doménu alebo subdoménu. Aby bolo overenie funkčné, musí byť súbor dostupný napríklad na adrese:
https://www.vas-eshop.sk/.well-known/apple-developer-merchantid-domain-association. Vďaka tomu bude možné prevádzkovať Apple Pay na https://www.vas-eshop.sk/.
Ak má byť Apple Pay dostupné aj na ďalších subdoménach, je potrebné vykonať rovnaký postup pre každú z nich zvlášť a sprístupniť tak validačný súbor napríklad na subdoméne https://checkout.vas-eshop.sk/.well-known/apple-developer-merchantid-domain-association
V odpovedi endpointu je vrátený iba obsah súboru. Stiahnutý obsah musí byť uložený do vyššie menovaného súboru na disk a nahraný na server bezo zmeny. Súbor nesmie obsahovať zalomenie riadku na konci! Obsah je tvorený iba jedným riadkom. Kódovanie súboru musí byť ASCII alebo UTF-8.
Akákoľvek nekonzistencia s požiadavkami na vlastnosti súboru povedie k odmietnutiu súboru zo strany systémov Apple.
Obsah súboru sa v určitých intervaloch mení. Hoci k zmenám nedochádza často, odporúča sa implementovať mechanizmus automatickej výmeny. Aktualizácia by mala prebiehať aspoň raz denne, ideálne v ranných hodinách pred začiatkom špičky objednávok, aby sa predišlo prípadným problémom s platením.
⚠️ Spoločnosť Comgate nenesie zodpovednosť za nemožnosť vykonávania platieb v prípade, že validačný súbor na doméne obchodníka nebude včas aktualizovaný.
Správne nahranie súboru je potrebné overiť v klientskom portáli v detaile prepojenia obchodu kliknutím na tlačidlo "Skontrolovať pre NAZOV_METODY". Po zobrazení zelenej potvrdzovacej hlášky je do systému zadaná požiadavka na registráciu domény u Apple. Spracovanie prebieha automaticky a štandardne je dokončené do 10 minút. Vo výnimočných prípadoch môže trvať niekoľko hodín, preto sa odporúča počkať aspoň 24 hodín.
Súbor apple-developer-merchantid-domain-association musí na doméne zostať po celý čas používania Apple Pay v košíku e-shopu. Pri každej platbe si Apple Pay siaha pre obsah súboru.
Stavy registrácie
Po vykonaní kontroly validity v portáli je zahájená automatická registrácia domény, ktorá môže nadobúdať nasledujúce stavy:
| Stav | Popis |
|---|---|
| Povolené | Registrácia bola úspešne dokončená a služba je aktívna. |
| Zakázané | Služba je vypnutá. |
| (čaká na registráciu) | Doména čaká na spracovanie registrácie, ktoré bude vykonané automaticky. |
| (čaká na preregistráciu) | Doména čaká na spracovanie preregistrácie, ktoré bude vykonané automaticky. |
| (zakázané pre celý obchod) | Apple Pay je zakázané pre celý obchod; detaily je možné získať prostredníctvom podpory. |
| (chyba registrácie) | Pri registrácii došlo k chybe. Odporúčaný postup: deaktivujte Apple Pay, uložte zmenu, následne ho znova aktivujte a uložte. Ak problém pretrváva a žiadosť o (pre)registráciu nie je spracovaná, obráťte sa na zákaznícku podporu. |
Google Pay
Na rozdiel od Apple je proces u Google jednoduchší. Počas vývoja možno integráciu prevádzkovať v testovacom režime (podrobnosti viď ďalej) a až pri nasadení do produkcie je potrebné vykonať schválenie domény a prepnúť konfiguráciu na produkčný režim.
Google Pay nevyžaduje umiestnenie validačného súboru na doménu, vyžaduje však jej schválenie v portáli Google Pay Console. Postup je popísaný v oficiálnej dokumentácii. Pre túto fázu postačí zriadenie prístupu do portálu. V rámci implementácie Google Pay sa k tomuto kroku vrátite, aby ste vykonali overenie domény a aktiváciu produkčnej implementácie.
Google Pay Merchant ID
Pri implementácii Web Checkout SDK do vlastného e-shopu je nevyhnutné v rámci vytvorenia profilu v Google Pay Console zaznamenať príslušné Merchant ID. Tento identifikátor sa následne uvádza v parametri payment.googlePayMerchantId pri konfigurácii modulu Google Pay.
Hodnotu Merchant ID nájdete v pravom hornom rohu hlavičky stránky Google Pay Console. Identifikátor je uvedený vo formáte BCR2AN9TWDNZ7G2L či v obdobnom tvare.
Overenie produkčnej domény
Pre overenie produkčnej domény je potrebné mať účet v Google Pay Console. Po prihlásení zvoľte v ľavom menu položku „Rozhranie API služby Google Pay" a v sekcii „Integrate with your website" kliknite na „+ Add website".
Vyplňte URL (vrátane subdomény), ako typ integrácie zvoľte „Brána" a nahrajte päť snímok obrazovky znázorňujúcich priebeh procesu platenia prostredníctvom Google Pay. Tieto snímky slúžia na schválenie zo strany Google a musia zodpovedať brand guidelines. Bez ich splnenia nebude integrácia schválená.
Návrh tlačidla možno vygenerovať v simulátore, avšak tieto návrhy neodporúčame používať na účely schvaľovania.
Uvedené screenshoty odporúčame zhotoviť z počítača:
- výber produktu – používateľ si prezerá produkt alebo službu,
- obrazovka pred nákupom – používateľ je pripravený vykonať nákup,
- výber platobnej metódy – používateľ zvolí Google Pay,
- obrazovka platby Google Pay – používateľovi sa zobrazia uložené platobné údaje. (Poznámka: Android neumožňuje zhotoviť screenshot tejto obrazovky, použite preto iné zariadenie na jej odfotenie),
- obrazovka po nákupe – používateľ úspešne dokončil platbu.
Na screenshoty sú kladené tiež určité požiadavky:
- Každý snímok môže mať maximálnu veľkosť 1 MB.
- Jeden screenshot možno použiť pre viac kategórií, ak zodpovedá procesu.
Po vyplnení formulára kliknite v pravom dolnom rohu na tlačidlo „Uložiť" a vykonajte dôkladnú kontrolu – po odoslaní žiadosti už nemožno vykonávať zmeny.
Posuňte stránku nahor a overte, že spĺňate všetky požiadavky:
- prvé zaškrtávacie políčko vykonal Comgate za vás, preto ho môžete potvrdiť,
- druhé políčko – systémové overenia – zaisťuje Checkout automaticky. Vašou úlohou je iba zaistiť súlad s brand guidelines, potom ho môžete potvrdiť,
- funkčné testy u tretieho políčka vykonal opäť Comgate, príslušné políčko teda môžete tiež zaškrtnúť.
Na webe nesmie byť uvedené, že ide o testovacie alebo demo prostredie. Aby bola doména schválená, musí prezentovať plne produkčný produkt.
Akonáhle spĺňate všetky požiadavky na schválenie, odošlite žiadosť kliknutím na „Submit for approval".
Nedodržanie brand guidelines môže mať za následok pozastavenie prístupu k službe Google Pay až do vykonania nápravy. Tento proces je plne v kompetencii spoločnosti Google a Comgate ho nemôže ovplyvniť.
Riešenie problémov so schválením
Ak Google žiadosť o schválenie zamietne, zašle vám e-mail s podrobným vysvetlením a inštrukciami pre ďalší postup.
V prípade nejasností sa môžete priamo z portálu Google Pay Console obrátiť na zákaznícku podporu Google prostredníctvom „Okamžitá podpora" v ľavom menu. Odpoveď zvyčajne dostanete do 48 hodín, pričom prvé reakcie bývajú často všeobecného charakteru – nenechajte sa tým odradiť.
Pri problémoch s registráciou domény sa vždy obracajte primárne na podporu Google, pretože Comgate v tejto oblasti nemá rozhodovaciu právomoc a naša zákaznícka podpora vás s prípadnými otázkami pravdepodobne odkáže späť na tím Google Pay.
Príprava vývojového prostredia
Pre úspešnú integráciu je nevyhnutné mať pripravené kvalitné vývojové prostredie, ktoré umožní efektívnu implementáciu potrebných funkcií. Zvláštnu pozornosť vyžaduje konfigurácia prostredia pre tlačidlo Apple Pay.
HTTPS
Základným predpokladom pre správnu funkčnosť je prevádzkovanie lokálneho projektu na HTTPS.
V projektoch využívajúcich Vite možno použiť napríklad:
@vitejs/plugin-basic-ssl– oficiálny balíček Vite [dokumentácia]vite-plugin-mkcert– vhodná alternatíva [dokumentácia]
Pre ostatné nástroje je potrebné zvoliť vlastné riešenie.
Vopred registrovaná vývojová doména
Pre testovanie procesu Apple Pay poskytuje spoločnosť Comgate dve vopred registrované domény, ktoré možno využiť počas vývoja. Tieto domény boli vášmu obchodu zaregistrované pri aktivácii Checkout SDK a sú pripravené na použitie.
Tento krok je nepovinný a nie je potrebný pre správnu funkčnosť Checkout SDK v produkčnom prostredí.
Bez jeho vykonania však pri vývoji na localhost nie je možné spustiť platobné rozhranie Apple Pay a otestovať celý proces platby – a to ani u testovacích transakcií. Samotné tlačidlá sa zobrazia.
Úprava súboru hosts
Pre lokálne testovanie je nevyhnutné upraviť súbor hosts vo vašom operačnom systéme. Použitie adresy localhost alebo priamej IP adresy nie sú u Apple Pay podporované. Na localhoste s HTTPS sa zobrazia iba tlačidlá služieb.
Pre správnu konfiguráciu zistite v klientskom portáli Comgate, akého poskytovateľa používate pre spracovanie karetných transakcií. Podporované hodnoty sú:
CARD_CZ_CSOB_2CARD_CZ_COMGATE
- CARD_CZ_COMGATE
- CARD_CZ_CSOB_2
Nakonfigurujte svoj vývojový server (napr. nginx, Apache, Vite.js, Next.js, ...) tak, aby bola projektu priradená doména:
Potom upravte súbor hosts, aby uvedená doména smerovala na váš vývojový stroj (localhost).
- Linux
- macOS
- Windows
- otvorte terminál
- vytvorte zálohu súboru
hostspríkazomsudo cp /etc/hosts /etc/hosts.bak - otvorte súbor
hostspríkazomsudo nano /etc/hosts - na koniec súboru pridajte riadok
- ak vyvíjate vzdialene, použite namiesto
127.0.0.1IP adresu servera (napr. Docker) - uložte súbor
- otvorte aplikáciu Terminál
- vytvorte zálohu súboru
hostspríkazomsudo cp /etc/hosts /etc/hosts.bak - otvorte súbor
hostspríkazomsudo nano /etc/hosts - na koniec súboru pridajte riadok
- ak vyvíjate vzdialene, použite namiesto
127.0.0.1IP adresu servera (napr. Docker) - uložte súbor
- v adresári
C:\windows\system32\drivers\etcvyhľadajte súborhostsa skopírujte ho na plochu - vytvorte zálohu súboru
hosts - otvorte pôvodný súbor v textovom editore
- na koniec súboru pridajte riadok
- ak vyvíjate vzdialene, použite namiesto
127.0.0.1IP adresu servera (napr. Docker) - uložte súbor a skopírujte ho späť do pôvodného adresára (je vyžadované oprávnenie administrátora)
Po dokončení konfigurácie by mala adresa smerovať na váš vývojový stroj. Apple Pay a Google Pay by mali byť pripravené na použitie.
Ak bude na vývojovom prostredí použitá produkčná platba (nebola založená s parametrom test=true), hrozí reálne riziko stiahnutia finančných prostriedkov.
Pri vývoji sa teda odporúča pracovať primárne s testovacími platbami alebo s platbami v malých sumách.