Platební brány jsou mostem mezi e-shopem a světem online plateb — díky nim může zákazník zaplatit kartou, rychlým bankovním převodem, Apple Pay, Google Pay nebo dalšími metodami, aniž by musel cokoliv řešit mimo váš web. Modul /payment-gateway slouží ke konfiguraci těchto bran, k testování jejich připojení, sledování úspěšnosti plateb a správě přístupových údajů. Každá organizace může mít současně nakonfigurováno více bran — například jednu pro produkci a druhou v sandboxu pro testování — a také různé brány pro různé segmenty provozu, takže modul pokrývá jak drobné e-shopy, tak rozsáhlé projekty s více prodejními kanály.
Přehled platebních bran
Tabulka obsahuje všechny nakonfigurované brány organizace se souhrnnými údaji, které umožňují rychlou orientaci i u větších instalací. V každém řádku vidíte unikátní kód brány (typicky ve formátu gopay-production), poskytovatele (GoPay, Comgate nebo Stripe), volitelný popis pro snazší orientaci, prostředí (produkce, sandbox nebo test), příznak aktivity, počet plateb, které branou prošly, datum vytvoření a okamžik posledního použití.
Neaktivní brány zůstanou viditelné v přehledu, ale nemohou přijímat nové platby. Ke stávajícím transakcím jsou však stále přístupné pro účely kontroly nebo dodatečné synchronizace, takže vypnutí brány neznamená ztrátu historie ani omezení auditu.
Podporovaní poskytovatelé
Administrace v současnosti podporuje tři platební poskytovatele, kteří společně pokrývají většinu českého i evropského trhu. Liší se především nabídkou platebních metod a geografickým zaměřením, technické napojení se však z pohledu administrace chová u všech obdobně.
| Poskytovatel | Typ plateb | Prostředí |
|---|---|---|
| GoPay | Platební karty, bankovní tlačítka, Apple Pay, Google Pay | produkce, sandbox |
| Comgate | Platební karty, online bankovnictví, QR platba | produkce, test |
| Stripe | Platební karty, Apple Pay, Google Pay, SEPA, opakované platby | produkce, test |
ℹ️ Nabídku konkrétních platebních metod (karty, bankovní tlačítka, mobilní peněženky) řídí samotný poskytovatel a váš smluvní balíček u něj. V administraci nastavujete pouze připojení k bráně; o dostupnost jednotlivých metod se stará poskytovatel na své straně.
Prostředí brány
Každá instance brány běží v jednom ze tří režimů, které odlišují, zda se pracuje se skutečnými penězi nebo s testovacími daty. Volba prostředí má přímý dopad na chování celé administrace — od přesměrování zákazníka až po skutečné uzavření objednávky.
- Produkce (
p) — skutečné platby od reálných zákazníků. Peníze se převádějí na váš obchodní účet u poskytovatele. - Sandbox (
s) — oficiální testovací prostředí poskytovatele s testovacími kartami. Žádné reálné peníze se nepřevádějí. - Test (
t) — lokální testovací režim administrace bez volání externí brány, sloužící pouze k ověření chování objednávkového procesu.
⚠️ Před spuštěním do ostrého provozu vždy nejprve ověřte celý platební tok v sandboxu. Přepnutí brány z sandboxu do produkce znamená změnu prostředí a v drtivé většině případů i výměnu všech přístupových klíčů, protože poskytovatelé oddělují produkční a testovací účty na úrovni samotné autentizace.
Přidání nové brány
Tlačítko Add v pravém horním rohu otevře dialog pro přidání nové brány a provede vás zakládáním krok za krokem. Nejprve vyberete poskytovatele (GoPay, Comgate nebo Stripe), poté zvolíte kód brány — krátký slug, který vám pomůže bránu poznat (například gopay-production); pokud pole necháte prázdné, kód se vygeneruje automaticky. Následně zadáte popis, který se ukáže v seznamu, zvolíte prostředí (výchozí je sandbox, aby nebylo možné omylem spustit produkční platby) a vyplníte přihlašovací údaje získané od poskytovatele — klíče a identifikátory se liší podle typu brány. Po uložení se brána rovnou objeví v seznamu a systém ji zpravidla automaticky otestuje (viz sekce Testování připojení).
Detail brány
Po kliknutí na bránu se otevře detail rozdělený do pěti záložek, které dohromady pokrývají celý životní cyklus brány od základního nastavení až po sledování výkonu.
- Informace — základní nastavení brány, kód, popis, prostředí a stav aktivity.
- Připojení — stav spojení s poskytovatelem, možnost testování konfigurace a přehled maskovaných údajů.
- Přihlašovací údaje — API klíče a další citlivé údaje; otevření této záložky vyžaduje zvýšená oprávnění.
- Platby — seznam transakcí, které branou prošly, s aktuálním stavem každé z nich.
- Statistiky — přehled úspěšnosti plateb, průměrná částka a počet úspěšných i neúspěšných transakcí.
Záložka Přihlašovací údaje
Každý poskytovatel používá svou vlastní kombinaci identifikátorů a klíčů, ale koncepčně jde o obdobnou sadu. Merchant ID je identifikátor vašeho obchodu u poskytovatele, public key slouží jako veřejný klíč, který lze sdílet v požadavcích na bránu, secret key je tajný klíč pro podpis požadavků (ten nikdy nesdělujte třetím stranám) a secure key je doplňkový podpisový klíč, který využívá například Comgate.
⚠️ Tajné klíče se v rozhraní zobrazují maskované — viditelné jsou pouze první a poslední znaky. Celý obsah klíče získáte pouze přímo v administraci poskytovatele, což brání jeho náhodnému úniku ze snímků obrazovky nebo screen-share sezení.
Testování připojení
Pro ověření, že brána opravdu funguje, slouží test připojení. Po jeho spuštění administrace pošle kontrolní dotaz na API poskytovatele a pokusí se načíst základní údaje o obchodě. Test se spouští buď automaticky (po uložení nebo úpravě přihlašovacích údajů), nebo ručně tlačítkem Otestovat připojení v záložce Připojení. Výsledkem je jasná odpověď úspěch nebo neúspěch, přičemž v případě selhání administrace zobrazí i konkrétní chybovou zprávu od poskytovatele — ta obvykle napoví, zda jste zadali špatný klíč, zvolili nesprávné prostředí, nebo zda vám u poskytovatele vypršelo členství.
💡 Při změně klíčů můžete test spustit s novými hodnotami, aniž byste přepsali stávající konfiguraci. Pokud test projde, teprve potom uložte změny — tím eliminujete riziko, že byste aktuálně fungující nastavení přepsali nefunkčními údaji a přerušili tak platby zákazníkům.
Životní cyklus platby v bráně
Každá platba prochází čtyřmi fázemi, které dohromady popisují, co se mezi stisknutím tlačítka „Zaplatit" v košíku a uzavřením objednávky vlastně děje. Ve fázi vytvoření zvolí zákazník v košíku platební metodu, administrace vytvoří platební požadavek v bráně a přesměruje jej na stránku poskytovatele. Ve fázi čekání zákazník potvrzuje platbu v bance nebo zadává údaje karty a brána zatím drží transakci ve stavu PENDING. Při potvrzení brána vrací zákazníka zpět na e-shop a zároveň volá webhook do administrace se stavem platby. A konečně ve fázi finalizace si administrace stav u brány pro jistotu ještě ověří (takzvaná synchronizace) a pokud je platba úspěšná, označí objednávku jako Zaplacenou.
Webhook callback je interní komunikační kanál mezi bránou a administrací — umožňuje branám informovat systém o změnách stavu i v případě, že se zákazník nevrátí zpět na e-shop (například když zavře prohlížeč hned po platbě).
ℹ️ Pokud máte podezření, že brána callback neposlala nebo že nebyl doručen, použijte akci Synchronizovat platbu v detailu platby — administrace si stav vyžádá znovu a případně opraví závěrečné zpracování.
Propagace platby na objednávku a fakturu
Jakmile brána potvrdí úhradu, platba se přes provázaná napojení automaticky projeví ve všech souvisejících entitách, takže není nutné žádné ruční dokončování. Samotná platba přejde do stavu PAID a zapíše se u ní částka, poskytovatel i datum. Objednávka se označí jako Zaplacená a pokračuje dál ve svém workflow — obvykle míří k expedici a doručení. Faktura, pokud již byla vystavena, přejde do stavu Zaplacená s datem úhrady podle platby. Pokud naopak platba selže (byla zrušena, zamítnuta bankou nebo vypršela), objednávka zůstává otevřená a zákazník je automaticky vyzván k opětovné úhradě, takže celý proces končí kontrolovaným stavem bez ztráty objednávky.
Statistiky a monitoring
Záložka Statistiky zobrazuje pro každou bránu přehled výkonu, který je nezbytný pro včasnou detekci problémů. Konkrétně uvidíte celkový počet platebních pokusů, počet úspěšných plateb, počet neúspěšných či zrušených transakcí, počet plateb, které stále čekají, součet zaplacených částek a úspěšnost v procentech. Právě dlouhodobý trend úspěšnosti je nejcitlivější indikátor zdraví platebního toku — prudký pokles obvykle poukazuje na problém, který je potřeba řešit co nejrychleji.
💡 Pokud úspěšnost dlouhodobě klesá pod 80 %, ověřte u poskytovatele, zda neevidujete větší počet zamítnutých karet. Často jde o aktivaci fraud filtrů nebo změnu limitů na jeho straně a rychlá komunikace s podporou poskytovatele problém obvykle vyřeší dřív, než vás stojí významnou část tržeb.
Doporučené postupy
Vždy založte nejdřív bránu v sandboxu a proveďte zkušební objednávku, než přepnete na produkci — ušetříte si tím většinu chyb, které se na ostrém provozu opravují obtížně. Kódy bran pojmenovávejte srozumitelně (gopay-production, stripe-eu), abyste se v nich při více obchodních jednotkách rychle orientovali. Pokud brána není aktivně používána, vypněte ji místo mazání; historie plateb zůstane dohledatelná a v případě potřeby můžete bránu znovu aktivovat. Pravidelně sledujte statistiky — prudký pokles úspěšnosti je první příznak změny na straně poskytovatele a včasná reakce je obvykle snadná, zatímco opožděná může znamenat ztracené tržby. A konečně: přístupové klíče měňte vždy, když odchází člen týmu, který je znal. Administrace umožňuje výměnu klíčů bez narušení aktivních plateb, takže bezpečnostní hygienu lze udržovat bez jakéhokoli dopadu na zákazníky.