Platební brány

Platební brány jsou mostem mezi e-shopem a světem online plateb — díky nim mohou zákazníci platit kartou, rychlým bankovním převodem, Apple Pay, Google Pay nebo jinými metodami, aniž by se museli zabývat čímkoli mimo váš web. Modul /payment-gateway slouží ke konfiguraci těchto bran, 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í — stejně jako různé brány pro různé provozní segmenty, takže modul pokrývá jak malé 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 pro organizaci se souhrnnými daty, což umožňuje rychlou orientaci i ve větších instalacích. Každý řádek zobrazuje 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 aktivní, počet plateb zpracovaných bránou, datum vytvoření a čas posledního použití.Neaktivní brány zůstávají viditelné v přehledu, ale nemohou přijímat nové platby. Nicméně jsou stále dostupné pro stávající transakce za účelem kontroly nebo dodatečné synchronizace, takže deaktivace brány neznamená ztrátu historie ani omezení auditovatelnosti.

Podporovaní poskytovatelé

Administrace aktuálně podporuje tři poskytovatele plateb, kteří dohromady pokrývají většinu českého a evropského trhu. Liší se především rozsahem nabízených platebních metod a geografickým zaměřením, ale technická integrace se z pohledu administrace chová pro všechny podobně.| Poskytovatel | Typy plateb | Prostředí | | --- | --- | --- | | GoPay | Platební karty, bankovní tlačítka, Apple Pay, Google Pay | production, sandbox | | Comgate | Platební karty, online bankovnictví, QR platba | production, test | | Stripe | Platební karty, Apple Pay, Google Pay, SEPA, opakované platby | production, test |> ℹ️ Konkrétní nabízené platební metody (karty, bankovní tlačítka, mobilní peněženky) se řídí samotným poskytovatelem a vaším smluvním balíčkem s ním. V administraci konfigurujete pouze připojení k bráně; poskytovatel je odpovědný za dostupnost jednotlivých metod na své straně.

Prostředí brány

Každá instance brány běží v jednom ze tří režimů, které rozlišují, zda jsou zpracovávány reálné peníze nebo testovací data. Volba prostředí má přímý dopad na chování celé administrace — od přesměrování zákazníka až po skutečné dokončení objednávky.- Produkční (p) — reálné platby od skutečných zákazníků. Peníze jsou převáděny na váš obchodní účet u poskytovatele.- Sandbox (s) — oficiální testovací prostředí poskytovatele s testovacími kartami. Žádné reálné peníze nejsou převáděny.- Testovací (t) — lokální testovací režim administrace bez volání externí brány, slouží pouze k ověření chování objednávkového procesu.> ⚠️ Vždy ověřte celý platební tok v sandboxu před spuštěním do produkce. Přepnutí brány ze sandboxu do produkce znamená změnu prostředí a ve velké většině případů také výměnu všech přístupových klíčů, protože poskytovatelé oddělují produkční a testovací účty na samotné autentizační úrovni.

Přidání nové brány

Tlačítko Přidat v pravém horním rohu otevře dialog pro přidání nové brány a provede vás nastavením krok za krokem. Nejprve vyberete poskytovatele (GoPay, Comgate nebo Stripe), poté zvolíte kód brány — krátký identifikátor, který vám pomůže bránu identifikovat (např. gopay-production); pokud pole necháte prázdné, kód se vygeneruje automaticky. Dále zadáte popis, který se objeví v seznamu, zvolíte prostředí (výchozí je sandbox, aby se zabránilo náhodným produkčním platbám) 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 okamžitě objeví v seznamu a systém ji obvykle automaticky otestuje (viz sekce Testování připojení).

Detail brány

Kliknutím na bránu se otevře její detailní stránka, rozdělená do pěti záložek, které dohromady pokrývají celý životní cyklus brány od základního nastavení po monitorování výkonu.- Informace — základní nastavení brány, kód, popis, prostředí a stav aktivity.- Připojení — stav připojení s poskytovatelem, možnost otestovat konfiguraci a přehled maskovaných dat.- Přihlašovací údaje — API klíče a další citlivá data; otevření této záložky vyžaduje zvýšená oprávnění.- Platby — seznam transakcí zpracovaných bránou s aktuálním stavem každé z nich.- Statistiky — přehled úspěšnosti plateb, průměrné částky a počtu úspěšných a neúspěšných transakcí.

Záložka Přihlašovací údaje

Každý poskytovatel používá vlastní kombinaci identifikátorů a klíčů, ale koncepčně jde o podobnou 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 brány, secret key je tajný klíč pro podepisování požadavků (nikdy jej nesdělujte třetím stranám) a secure key je dodatečný podpisový klíč, který používá například Comgate.> ⚠️ Tajné klíče jsou v rozhraní zobrazeny maskované — jsou viditelné pouze první a poslední znaky. Celý obsah klíče lze získat pouze přímo z administrace poskytovatele, což zabraňuje jeho náhodnému úniku ze snímků obrazovky nebo sdílených relací.

Testování připojení

Test připojení slouží k ověření, zda brána skutečně funguje. Po jeho spuštění odešle administrace kontrolní dotaz na API poskytovatele a pokusí se získat základní obchodní data. Test se iniciuje buď automaticky (po uložení nebo úpravě přihlašovacích údajů), nebo ručně kliknutím na tlačítko Otestovat připojení v záložce Připojení. Výsledkem je jasná odpověď o úspěchu nebo selhání, a v případě selhání administrace zobrazí i konkrétní chybovou zprávu od poskytovatele — ta obvykle indikuje, zda jste zadali špatný klíč, zvolili nesprávné prostředí nebo zda vypršelo vaše členství u poskytovatele.> 💡 Při změně klíčů můžete test spustit s novými hodnotami, aniž byste přepisovali stávající konfiguraci. Pokud test projde, teprve poté změny uložte — to eliminuje riziko přepsání aktuálně funkčního nastavení nefunkčními daty a tím přerušení plateb zákazníků.

Životní cyklus platby v bráně

Každá platba prochází čtyřmi fázemi, které dohromady popisují, co se skutečně děje mezi kliknutím na tlačítko „Zaplatit“ v košíku a dokončením objednávky. Ve fázi vytvoření zákazník vybere platební metodu v košíku, administrace vytvoří požadavek na platbu v bráně a přesměruje ho na stránku poskytovatele. Ve fázi čekání zákazník potvrdí platbu v bance nebo zadá údaje o kartě a brána drží transakci ve stavu PENDING. Po potvrzení brána přesměruje zákazníka zpět do e-shopu a současně zavolá webhook do administrace se stavem platby. A konečně, ve fázi finalizace, administrace znovu ověří stav u brány pro jistotu (tzv. synchronizace), a pokud je platba úspěšná, označí objednávku jako Zaplaceno.Zpětné volání webhooku je interní komunikační kanál mezi bránou a administrací — umožňuje bránám informovat systém o změnách stavu, i když se zákazník nevrátí do e-shopu (například pokud ihned po zaplacení zavře prohlížeč).> ℹ️ Pokud máte podezření, že brána neposlala zpětné volání nebo že nebylo doručeno, použijte akci Synchronizovat platbu v detailu platby — administrace si znovu vyžádá stav a případně opraví konečné zpracování.

Propagace platby do objednávky a faktury

Jakmile brána potvrdí platbu, platba se automaticky promítne do všech souvisejících entit prostřednictvím propojených integrací, což eliminuje potřebu jakéhokoli ručního dokončení. Samotná platba přejde do stavu PAID, s zaznamenanou částkou, poskytovatelem a datem. Objednávka je označena jako Zaplaceno a pokračuje ve svém pracovním postupu — obvykle směřuje k expedici a doručení. Faktura, pokud již byla vystavena, přechází do stavu Zaplaceno s datem platby podle platby. Naopak, pokud platba selže (byla zrušena, zamítnuta bankou nebo vypršela), objednávka zůstane otevřená a zákazník je automaticky vyzván k opětovné platbě, takže celý proces končí v kontrolovaném stavu bez ztráty objednávky.

Statistiky a monitoring

Záložka Statistiky zobrazuje přehled výkonu pro každou bránu, což je zásadní pro včasnou detekci problémů. Konkrétně uvidíte celkový počet pokusů o platbu, počet úspěšných plateb, počet neúspěšných nebo zrušených transakcí, počet stále čekajících plateb, součet zaplacených částek a úspěšnost v procentech. Dlouhodobý trend úspěšnosti je nejcitlivějším ukazatelem zdraví platebního toku — prudký pokles obvykle ukazuje na problém, který je třeba co nejrychleji vyřešit.> 💡 Pokud úspěšnost trvale klesá pod 80 %, ověřte u poskytovatele, zda se nesetkáváte s vyšším počtem zamítnutých karet. Často se jedná o aktivaci protifraudových filtrů nebo změnu limitů na jejich straně a včasná komunikace s podporou poskytovatele obvykle problém vyřeší, než vás bude stát značnou část vašich příjmů.

Osvědčené postupy

Vždy nejprve nastavte bránu v sandboxu a proveďte testovací objednávku před přepnutím do produkce — to vám ušetří většinu chyb, které je obtížné opravit v ostrém provozu. Názvy kódů bran pojmenujte jasně (gopay-production, stripe-eu), abyste se rychle zorientovali při správě více obchodních jednotek. Pokud brána není aktivně používána, deaktivujte ji namísto smazání; historie plateb zůstane dohledatelná a bránu můžete v případě potřeby znovu aktivovat. Pravidelně sledujte statistiky — prudký pokles úspěšnosti je prvním znamením změny na straně poskytovatele a včasná reakce je obvykle snadná, zatímco zpožděná může znamenat ztracené příjmy. A nakonec: vždy změňte přístupové klíče, když odejde člen týmu, který je znal. Administrace umožňuje výměnu klíčů bez narušení aktivních plateb, takže bezpečnostní hygiena může být udržována bez jakéhokoli dopadu na zákazníky.