Přeskočit na hlavní obsah

Integrační checklist

Checklist provede vývojáře celou integrací useCheckout() — od aktivace účtu po produkční nasazení.

Tip

Zaškrtnuté body se ukládají do lokální paměti prohlížeče a zůstávají zachovány i po obnovení stránky.

SymbolVýznam
🔜Musí být splněno před nasazením do produkce (nemusí být v pořadí).
⚠️Kritické — bez splnění nebude SDK fungovat správně.
❔Volitelné.

1. Předpoklady​

Účet v Comgate je aktivní.
Je aktivována alespoň jedna z následujících metod (podle plánovaných platebních metod):
Pouze karta — aktivována metoda CARD_CZ_COMGATE.
Pouze Apple Pay / Google Pay — aktivována metoda CARD_CZ_COMGATE nebo CARD_CZ_CSOB_2.
Karta + Apple Pay / Google Pay — aktivována metoda CARD_CZ_COMGATE.
Obchod je registrován v Comgate se správnou doménou / subdoménou.
🔜 HTTPS je dostupné na produkční doméně.
⚠️ SDK není spuštěno v iframe ani WebView.
❔ Pokud je používáno CSP — povoleny domény checkout.comgate.cz, payments.comgate.cz, pay.google.com, applepay.cdn-apple.com.
❔ Musí být umožněno nahrání souborů do /.well-known/ na vaší doméně (pro Apple Pay).

2. Konfigurace v Comgate portálu​

V portálu je vytvořeno propojení obchodu s aktivovanými službami (Card, Apple Pay, Google Pay).
Bylo získáno checkoutId z nastavení propojení.

❔ Ověření domény — Apple Pay​

Pouze pokud integrujete Apple Pay.

🔜 Na vaši doménu nahrán soubor /.well-known/apple-developer-merchantid-domain-association.
🔜 Obsah souboru odpovídá hodnotě z endpointu /v2.0/appleDomainAssociation (ASCII/UTF-8, bez trailing newline).
🔜 Doména + subdomény ověřeny v klientském portálu Comgate.
🔜❔ Implementováno automatické obnovování obsahu souboru.

❔ Ověření domény — Google Pay​

Pouze pokud integrujete Google Pay.

🔜 Doména + subdomény schváleny v Google Pay Console.
🔜 Připraveny screenshoty integrace pro Google review.

3. Implementace useCheckout()​

[Odkaz na dokumentaci] · [Příklady]

Založení platby (backend)​

⚠️ Platba je založena přes Merchant API — získáno transactionId.
⚠️ Při založení platby je vždy předán e-mail plátce.

Příprava HTML elementů​

❔ Pro Apple Pay: <div> s definovaným rozměrem (min. 240×45 px).
❔ Pro Google Pay: <div> s definovaným rozměrem (min. 240×45 px).
❓ Pro kartu: kontejner s unikátním ID, vnitřní elementy #{id}-ibox a #{id}-button > button, min. rozměr 280×250 px.
⚠️ Elementy existují v DOM před voláním useCheckout().

Volání useCheckout()​

Předán checkoutId a transactionId.
⚠️ Implementovány všechny povinné callbacky: onPaid, onCancelled, onPending, onError.
V onPaid uživatel vidí potvrzení úspěchu (nebo je přesměrován).
V onCancelled / onPending uživatel vidí srozumitelnou zprávu a může akci opakovat.
V onError je chyba zalogována a uživatel informován.

Zpracování výsledku (result)​

Kontrolován result.applepay?.success — pokud false, element skryt.
Kontrolován result.googlepay?.success — pokud false, element skryt.
Ošetřen stav, kdy useCheckout() rejectne (SDK se nepodařilo načíst).

4. SPA — životní cyklus​

Povinné pro aplikace s client-side routingem (Vue, React, Next.js, Nuxt, …).

Upozornění

Bez správného úklidu zůstávají staré instance v paměti a způsobují konflikty při dalším načtení platební stránky.

⚠️ Při opuštění stránky voláno destroy() na Apple Pay, Google Pay i Card instancích.
⚠️ Na Core se destroy() nevolá — je to singleton řízený SDK.
⚠️ Úklid proveden ve správném lifecycle hooku (onUnmounted / useEffect cleanup).
⚠️ Pro novou platbu se volá useCheckout() znovu — stará instance se nepoužívá.

5. Backend — ověření platby​

Nebezpečí

Nikdy nespoléhejte pouze na frontendové callbacky (onPaid). Vždy ověřte stav platby server-to-server.

⚠️ Backend ověřuje stav platby přes Merchant API (endpoint /v1.0/status) po obdržení notifikace.
⚠️ Objednávka je označena jako zaplacená až po potvrzení z backendu, ne na základě onPaid.

6. Testovací scénáře​

Před nasazením do produkce ověřte následující scénáře pro každou implementovanou metodu:

❔ Apple Pay​

Úspěšná platba → onPaid se zavolal, uživatel vidí potvrzení.
Zamítnutá platba (nedostatek prostředků) → onPending, uživatel informován.
Uživatel zavřel Apple Pay sheet → onPending, aplikace se chová korektně.
❔ Předautorizační platba → onPaid.
❔ Iniciační opakovaná platba → onPaid.

❔ Google Pay​

Úspěšná platba → onPaid se zavolal, uživatel vidí potvrzení.
Zamítnutá platba (nedostatek prostředků) → onPending, uživatel informován.
Uživatel zavřel Google Pay dialog → onPending, aplikace se chová korektně.
❔ Předautorizační platba → onPaid.
❔ Iniciační opakovaná platba → onPaid.

❔ Platba kartou​

Úspěšná platba → onPaid se zavolal, uživatel vidí potvrzení.
Zamítnutá platba (nedostatek prostředků) → onPending, uživatel informován.
3D Secure ověření proběhlo (iframe modal) a platba dokončena.
Neplatné údaje karty → uživatel vidí validační chybu.
❔ Předautorizační platba → onPaid.

7. Produkční nasazení​

🔜 Apple Pay — doména ověřena v Comgate portálu (produkce).
🔜 Google Pay — doména schválena v Google Pay Console (produkce).
checkoutId odpovídá produkčnímu propojení.
⚠️ SDK elementy nejsou programově skrývány, překrývány ani modifikovány.
Platba otestována na reálném zařízení (iOS pro Apple Pay, Android pro Google Pay).
Všechny implementované platební metody (karta, Apple Pay, Google Pay) jsou funkční v produkčním prostředí.