Skip to main content

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
Tip

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 platobných brán obchodu, na ktorom bude Checkout SDK implementované.

Aktivácia Checkout SDK​

Aktivácia je veľmi jednoduchá, stačí postupovať podľa návodu:

  1. V menu vyberte Služby → Platobné brány a otvorte platobnú bránu (obchod), pre ktorú chcete Checkout SDK aktivovať.
  2. Na záložke Prepojenie obchodu kliknite na prepojenie, cez ktoré chcete Checkout SDK prevádzkovať. Otvorí sa jeho detail, kde zvoľte Upraviť.
Tip

Odporúčame pre každú integráciu založiť nové prepojenie obchodu (tlačidlo Pridať prepojenie na záložke 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.

https://app.comgate.eu/

alt text

  1. V sekcii Peňaženky a SDK zaškrtnite položku Checkout SDK (web).
https://app.comgate.eu/

alt text

  1. Zobrazia sa ďalšie nastavenia pre Checkout SDK. V tejto časti povoľte všetky služby (Apple Pay, Google Pay), ktoré chcete prostredníctvom Checkout SDK prevádzkovať.
https://app.comgate.eu/

alt text

  1. Do zoznamu Povolené adresy webu (origins) pridajte tlačidlom Pridať adresu všetky originy, na ktorých bude Checkout SDK prevádzkované – vrátane vývojových a testovacích. Každý origin je samostatná položka zoznamu; ku každej možno doplniť poznámku (napr. na čo prostredie slúži).
https://app.comgate.eu/

alt text

Príklad:

  • https://www.vas-eshop.sk – produkcia
  • https://test.vas-eshop.sk – testovacie prostredie
Upozornenie

Checkout SDK bude fungovať iba na originoch uvedených v tomto zozname. Ak origin chýba, platobné rozhranie sa nenačíta.

  1. 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:

  1. Prejdite na zoznam prepojení obchodu, viď krok 1 vyššie v časti Aktivácia Checkout SDK.
  2. V zozname prepojení obchodu kliknite na požadované prepojenie – zobrazí sa jeho detail.
  3. V sekcii Peňaženky a SDK nájdite položku Checkout ID (bude vo formáte UUIDv4). Hodnotu skopírujete ikonou vedľa poľa.
Poznámka

Hodnota Checkout ID by mala byť zaznamenaná pre ďalšie použitie (prípadne je potrebné vedieť, kde ju možno znova nájsť).

https://app.comgate.eu/

alt text

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ť.

Poznámka

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

Upozornenie

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/.

Upozornenie

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.

Tip

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: v sekcii Peňaženky a SDK pri položke Kontrola overenia kliknite na tlačidlo "Skontrolovať pre NAZOV_METODY" (tlačidlo je k dispozícii pre každú kartovú metódu, ktorú máte na obchode aktívnu). Po zobrazení zelenej potvrdzovacej hlášky je do systému zadaná požiadavka na registráciu domény u Apple a Stav Apple Pay sa zmení na Čaká na registráciu. 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.

Ak kontrola súbor nenájde alebo k nemu nemá prístup, portál zobrazí HTTP kód a výňatok odpovede vášho servera. Najčastejšou príčinou je firewall alebo ochrana pred robotmi (napr. Cloudflare) – v takom prípade povoľte prístup z IP adresy Comgate 89.185.236.55 a z IP adries Apple Pay.

https://app.comgate.eu/

alt text

Upozornenie

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 súboru v portáli je spustená automatická registrácia domény. Položka Stav Apple Pay v detaile prepojenia obchodu môže nadobúdať nasledujúce stavy:

StavPopis
RegistrovanéRegistrácia bola úspešne dokončená a služba je aktívna.
Čaká na súbor na overenie doményDoména zatiaľ nebola registrovaná. Nahrajte súbor a spustite kontrolu tlačidlom "Skontrolovať pre NAZOV_METODY".
Čaká na registráciuDoména čaká na spracovanie registrácie, ktoré bude vykonané automaticky.
Čaká na opätovnú registráciuDoména čaká na spracovanie opätovnej registrácie, ktoré bude vykonané automaticky.
Nepovolené pre obchodApple Pay je zakázané pre celý obchod; detaily je možné získať prostredníctvom podpory.

Ak registrácia u Apple zlyhá (najčastejšie kvôli súboru, ktorý medzitým z domény zmizol), systém Apple Pay na prepojení vypne. Odporúčaný postup: skontrolujte súbor na doméne, v úprave prepojenia znova zaškrtnite Apple Pay, uložte a spustite kontrolu znova. 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á.

Tip

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:

  1. výber produktu – používateľ si prezerá produkt alebo službu,
  2. obrazovka pred nákupom – používateľ je pripravený vykonať nákup,
  3. výber platobnej metódy – používateľ zvolí Google Pay,
  4. 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),
  5. 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:

  1. prvé zaškrtávacie políčko vykonal Comgate za vás, preto ho môžete potvrdiť,
  2. 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ť,
  3. funkčné testy u tretieho políčka vykonal opäť Comgate, príslušné políčko teda môžete tiež zaškrtnúť.
Upozornenie

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".

Upozornenie

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.

Informácie

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 (detail platobnej brány, záložka Povolené platobné metódy, stĺpec ID metódy), akého poskytovateľa používate pre spracovanie karetných transakcií. Podporované hodnoty sú:

  • CARD_CZ_CSOB_2
  • CARD_CZ_COMGATE

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).

  • otvorte terminál
  • vytvorte zálohu súboru hosts príkazom sudo cp /etc/hosts /etc/hosts.bak
  • otvorte súbor hosts príkazom sudo nano /etc/hosts
  • na koniec súboru pridajte riadok
  • ak vyvíjate vzdialene, použite namiesto 127.0.0.1 IP adresu servera (napr. Docker)
  • uložte súbor

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.

Upozornenie

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.