Skip to main content

Integračný checklist

Checklist prevedie vývojára celou integráciou useCheckout() — od aktivácie účtu po produkčné nasadenie.

Tip

Zaškrtnuté body sa ukladajú do lokálnej pamäte prehliadača a zostávajú zachované aj po obnovení stránky.

SymbolVýznam
🔜Musí byť splnené pred nasadením do produkcie (nemusí byť v poradí).
⚠️Kritické — bez splnenia nebude SDK fungovať správne.
❔Voliteľné.

1. Predpoklady​

Účet v Comgate je aktívny.
Je aktivovaná aspoň jedna z nasledujúcich metód (podľa plánovaných platobných metód):
Iba karta — aktivovaná metóda CARD_CZ_COMGATE.
Iba Apple Pay / Google Pay — aktivovaná metóda CARD_CZ_COMGATE alebo CARD_CZ_CSOB_2.
Karta + Apple Pay / Google Pay — aktivovaná metóda CARD_CZ_COMGATE.
Obchod je registrovaný v Comgate so správnou doménou / subdoménou.
🔜 HTTPS je dostupné na produkčnej doméne.
⚠️ SDK nie je spustené v iframe ani WebView.
❔ Ak je používané CSP — povolené domény checkout.comgate.cz, payments.comgate.cz, pay.google.com, applepay.cdn-apple.com.
❔ Musí byť umožnené nahranie súborov do /.well-known/ na vašej doméne (pre Apple Pay).

2. Konfigurácia v Comgate portáli​

V portáli je vytvorené prepojenie obchodu s aktivovanými službami (Card, Apple Pay, Google Pay).
Bolo získané checkoutId z nastavenia prepojenia.

❔ Overenie domény — Apple Pay​

Iba ak integrujete Apple Pay.

🔜 Na vašu doménu nahraný súbor /.well-known/apple-developer-merchantid-domain-association.
🔜 Obsah súboru zodpovedá hodnote z endpointu /v2.0/appleDomainAssociation (ASCII/UTF-8, bez trailing newline).
🔜 Doména + subdomény overené v klientskom portáli Comgate.
🔜❔ Implementované automatické obnovovanie obsahu súboru.

❔ Overenie domény — Google Pay​

Iba ak integrujete Google Pay.

🔜 Doména + subdomény schválené v Google Pay Console.
🔜 Pripravené screenshoty integrácie pre Google review.

3. Implementácia useCheckout()​

[Odkaz na dokumentáciu] · [Príklady]

Založenie platby (backend)​

⚠️ Platba je založená cez Merchant API — získané transactionId.
⚠️ Pri založení platby je vždy odovzdaný e-mail platiteľa.

Príprava HTML elementov​

❔ Pre Apple Pay: <div> s definovaným rozmerom (min. 240×45 px).
❔ Pre Google Pay: <div> s definovaným rozmerom (min. 240×45 px).
❓ Pre kartu: kontajner s unikátnym ID, vnútorné elementy #{id}-ibox a #{id}-button > button, min. rozmer 280×250 px.
⚠️ Elementy existujú v DOM pred volaním useCheckout().

Volanie useCheckout()​

Odovzdaný checkoutId a transactionId.
⚠️ Implementované všetky povinné callbacky: onPaid, onCancelled, onPending, onError.
V onPaid používateľ vidí potvrdenie úspechu (alebo je presmerovaný).
V onCancelled / onPending používateľ vidí zrozumiteľnú správu a môže akciu opakovať.
V onError je chyba zalogovaná a používateľ informovaný.

Spracovanie výsledku (result)​

Kontrolovaný result.applepay?.success — ak false, element skrytý.
Kontrolovaný result.googlepay?.success — ak false, element skrytý.
Ošetrený stav, keď useCheckout() rejectne (SDK sa nepodarilo načítať).

4. SPA — životný cyklus​

Povinné pre aplikácie s client-side routingom (Vue, React, Next.js, Nuxt, …).

Upozornenie

Bez správneho úklidu zostávajú staré inštancie v pamäti a spôsobujú konflikty pri ďalšom načítaní platobnej stránky.

⚠️ Pri opustení stránky volané destroy() na Apple Pay, Google Pay aj Card inštanciách.
⚠️ Na Core sa destroy() nevolá — je to singleton riadený SDK.
⚠️ Úklid vykonaný v správnom lifecycle hooku (onUnmounted / useEffect cleanup).
⚠️ Pre novú platbu sa volá useCheckout() znovu — stará inštancia sa nepoužíva.

5. Backend — overenie platby​

Nebezpečenstvo

Nikdy sa nespoliehajte iba na frontendové callbacky (onPaid). Vždy overte stav platby server-to-server.

⚠️ Backend overuje stav platby cez Merchant API (endpoint /v1.0/status) po obdržaní notifikácie.
⚠️ Objednávka je označená ako zaplatená až po potvrdení z backendu, nie na základe onPaid.

6. Testovacie scenáre​

Pred nasadením do produkcie overte nasledujúce scenáre pre každú implementovanú metódu:

❔ Apple Pay​

Úspešná platba → onPaid sa zavolal, používateľ vidí potvrdenie.
Zamietnutá platba (nedostatok prostriedkov) → onPending, používateľ informovaný.
Používateľ zavrel Apple Pay sheet → onPending, aplikácia sa správa korektne.
❔ Predautorizačná platba → onPaid.
❔ Iniciačná opakovaná platba → onPaid.

❔ Google Pay​

Úspešná platba → onPaid sa zavolal, používateľ vidí potvrdenie.
Zamietnutá platba (nedostatok prostriedkov) → onPending, používateľ informovaný.
Používateľ zavrel Google Pay dialóg → onPending, aplikácia sa správa korektne.
❔ Predautorizačná platba → onPaid.
❔ Iniciačná opakovaná platba → onPaid.

❔ Platba kartou​

Úspešná platba → onPaid sa zavolal, používateľ vidí potvrdenie.
Zamietnutá platba (nedostatok prostriedkov) → onPending, používateľ informovaný.
3D Secure overenie prebehlo (iframe modal) a platba dokončená.
Neplatné údaje karty → používateľ vidí validačnú chybu.
❔ Predautorizačná platba → onPaid.

7. Produkčné nasadenie​

🔜 Apple Pay — doména overená v Comgate portáli (produkcia).
🔜 Google Pay — doména schválená v Google Pay Console (produkcia).
checkoutId zodpovedá produkčnému prepojeniu.
⚠️ SDK elementy nie sú programovo skrývané, prekrývané ani modifikované.
Platba otestovaná na reálnom zariadení (iOS pre Apple Pay, Android pre Google Pay).
Všetky implementované platobné metódy (karta, Apple Pay, Google Pay) sú funkčné v produkčnom prostredí.