Dokumentace pluginu Toret Comgate

Nacházíte se na stránkách dokumentace pluginu Comgate, který umožňuje integraci platební brány Comgate. Plugin Comgate zakoupíte zde: Toret Comgate pro WooCommerce

Poznámka: Pro implementaci platební brány potřebuje mít dokončenou registraci u Comgate.

Instalace pluginu

Po zakoupení pluginu obdržíte emailem licenční klíč a odkaz na stažení zip souboru s pluginem. Detailní návod, jak do WordPress nainstalovat plugin z počítače, najdete zde.

Aktivace pluginu

Po instalaci pluginu si otevřete plugin Comgate, do příslušného pole vložte licenční klíč a tlačítkem ověřte licenci.

Propojení Comgate s WooCommerce

Comgate je platební brána nabízející několik platebních metod. Plugin Toret Comgate propojuje tuto platební bránu s vaším WooCommerce e-shopem. Nastavení je třeba provést v klientském portálu Comgate a ve WooCommerce.

V portále Comgate po přihlášení přejděte v menu nahoře do záložky Integrace > Nastavení obchodů a vyberte ten, který chcete spravovat. Poté klikněte na Propojení obchodu a nakonec na ikonu oka Náhled.

Objeví se nová obrazovka s následujícím menu.

1. Údaje Identifikátor propojení obchodu a Heslo (secure key)(1) zkopírujte a vložte do pluginu ve WooCommerce (Toret Plugins > Comgate > Přístupové údaje). Uložte tlačítkem dole na stránce.

2. Povolený způsob založení platby (2) zvolte buď BACKEND nebo SIMPLE_REDIRECT.

3. Do polí pro URL (3) vložte URL adresy, které najdete v nastavení pluginu Comgate (Toret Plugins > Comgate > Základní nastavení > URL adresy pro nastavení v účtu Comgate).

4. Do pole Povolené IP adresy (4) je třeba zadat IP adresy serveru, kde je web hostován.  Pokud nebudou IP adresy povoleny, v pluginu se po vložení implementačních údajů nenačtou jednotlivé platební metody a platby přes platební bránu nebudou fungovat.

IP adresy se nemusí definovat jednotlivě, ale mohou být zapsány jako rozsah. Tedy IP adresa následována lomítkem a číslem určujícím počet uzamknutých bitů adresy (tzv. maskou sítě). Například tedy zápis 192.168.1.0/24 vám tedy povolí IP adresu začínající 192.168.1. s libovolným posledním číslem.

Základní nastavení pluginu

V sekci Základní nastavení pluginu (Toret Plugins > Comgate) lze dále zapnete/vypnete testovací mód (viz dále) a nastavíte přístupové údaje pro různé měny.

Přístupové údaje pro různé měny

Plugin podporuje 9 měn: CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK.

Pokud máte u Comgate různé účty pro různé měny, můžete pro každou měnu zadat vlastní přihlašovací údaje:

1. V sekci Měny s vlastními údaji vyberte měny z rozbalovacího seznamu.
2. Pro každou vybranou měnu vyplňte Merchant ID a Secret Key.
3. Pro nevybrané měny se automaticky použijí výchozí přístupové údaje.

Plugin automaticky rozpozná měnu objednávky a použije odpovídající přihlašovací údaje.

WPML podpora

Pokud používáte plugin WPML pro vícejazyčný web, můžete definovat rozdílné Comgate účty pro každou jazykovou verzi:

1. Plugin automaticky detekuje aktivní jazyky WPML.
2. Pro každý jazyk vyplňte Merchant ID a Secret Key.
3. Jazyk má v případě konfliktu přednost před měnou.

Sekce WPML se zobrazí pouze pokud je WPML nainstalovaný a aktivní.

Pokročilé nastavení

Jazyk platební brány

Určuje, v jakém jazyce se zákazníkovi zobrazí rozhraní platební brány:

Možnost	Popis
Automaticky podle e-shopu	Použije jazyk WordPress instalace
Podle fakturační země	Jazyk se odvozuje od země z fakturační adresy
Vynutit konkrétní jazyk	Zvolíte jeden z 23 podporovaných jazyků

Druh zboží

Vyberte typ zboží podle nastavení vašeho Comgate účtu:

• Fyzické zboží – Produkty vyžadující odeslání.
• Digitální služby / virtuální zboží – Software, služby, předplatné.

E-mailový odkaz na zaplacení

Pokud je zapnuto, plugin přidá do zákaznických e-mailů pro objednávky ve stavu Selhala platba tlačítko „Zaplatit objednávku“ s přímým odkazem na platební bránu.

Dostupné filtry pro úpravu vzhledu:

• tcomgate_email_link_label – Text tlačítka
• tcomgate_email_link_heading – Nadpis sekce
• tcomgate_email_link_button_color – Barva tlačítka
• tcomgate_email_link_button_text_color – Barva textu tlačítka

Apple Pay styl tlačítka

Platí pouze pro bránu Apple Pay. Výběr z variant:

• Černé (výchozí)
• Bílé
• Bílé s okrajem

Ikony platebních metod

Zaškrtnutím Skrýt všechny ikony globálně schováte ikony u všech Comgate bran v pokladně. Toto nastavení přepíše individuální nastavení u jednotlivých metod.

Automatické vracení plateb

Automatická refundace funguje na základě změny stavu objednávky. Pokud se objednávka přepne do zvoleného stavu, zákazníkovi se automaticky vrátí peníze.

Automatické vracení nastavíte takto:

1. aktivujte funkci „Povolit automatické vracení!
2. vyberte stav(y) objednávek, ve kterých k refundaci dojde
3. uložte

Pozor! Proběhlá refundace je nevratná.

Ladění

Debug režim

Zapne detailní logování všech API volání do WooCommerce logu. Logují se:

• Vytvoření platby (požadavek + odpověď)
• Příchod a zpracování webhooků
• Změny stavu objednávek
• Opakované platby a obnovy předplatných
• Refundace
• Stržení pre-autorizací
• Chybové stavy s detaily

Retence logů

Nastavte počet dní, po kterých se logy automaticky smažou (výchozí 30 dní).

Do logu vstoupíte na záložce Diagnostika a logy.

Diagnostika a logy

• Stav spojení s API – Otestuje připojení k Comgate API.
• URL pro předání výsledku platby – Zobrazí aktuální webhook URL.
• Verze pluginu – Aktuální verze.
• WooCommerce Logy – Odkaz na systémové logy WooCommerce.

Logy v detailu objednávky

V detailu objednávky se zobrazí tabulka s historií událostí:

• Datum, ID transakce, typ události
• Možnost zobrazit surová data každé události

Nastavení platebních metod

Nyní je možné přejít k nastavení platebních metod (Toret Plugins > Comgate > Platební metody)

Způsob zobrazení brány

V sekci Způsob zobrazení brány zvolte, jak se brána zobrazí zákazníkovi:

• Přesměrování na platební bránu (Redirect) – Zákazník je přesměrován na stránku Comgate, kde dokončí platbu. Výchozí a nejspolehlivější varianta.
• Vložené okno v e-shopu (Inline) – Platební brána se otevře v modálním okně přímo nad vaším e-shopem. Funguje pouze pro karetní metody.

Typy platebních metod

Plugin automaticky vytváří několik typů platebních metod:

Typ	ID	Popis
Comgate – výběr na bráně (Sdružená metoda)	all	Zákazník vybere metodu přímo v bráně Comgate
Platba kartou – sdružené metody	card_all	Pouze karetní metody
Bankovní platba – sdružené metody	bank_all	Pouze bankovní převody (výběr banky proběhne přímo v bráně)
Individuální metody	{id}	Jedna metoda pro každý způsob platby

Nastavení platebních metod (Dostupné platební kanály)

Nastavení platebních metod najdete na záložce Platební metody (Toret plugins > Comgate > Platební metody)

1. Klikněte na Aktualizovat metody z API Comgate (1) pro načtení dostupných metod.
2. Každou metodu můžete zapnout/vypnout přepínačem přímo v tabulce (2)
3. Pro změnu pořadí bran v pokladně klikněte na Spravovat řazení ve WooCommerce (3)

Nově načtené metody z API jsou ve výchozím stavu vypnuté — musíte je ručně aktivovat.

Kliknutí na název platební metody se dostanete do jejího individuálního nastavení.

Individuální nastavení platební metody

Každá platební metoda má vlastní nastavení ve WooCommerce → Nastavení → Platby:

Nastavení	Popis
Aktivovat	Zapne/vypne platební metodu
Inline brána	Povolí modální okno (přepíše globální nastavení)
Název	Název zobrazený zákazníkovi v pokladně
Popis	Popis pod názvem v pokladně
Vlastní ikona	Nahraďte výchozí ikonu vlastní z knihovny médií
Povolené metody	Omezení na konkrétní sub-metody (pro sdružené metody)
Povolit pro země	Omezení na konkrétní fakturační země
Nezobrazovat ikonu	Skryje ikonu u této metody

Provedení testovacích plateb

Dalším krokem před spuštěním provozu jsou tzv. testovací platby. Ověřte, zda v nastavení pluginu (Toret plugins > Comgate) máte zapnutý testovací mód. Po úspěšném dokončení testování nezapomeňte testovací mód vypnout.

Nyní je čas vrátit se do portálu Comgate do záložky Technické propojení.

V sekci Technická dokumentace najdete návod k provedení plateb.

Seznam všech testovacích plateb naleznete v portálu Comgate pod záložkou Technické propojení – Testovací platby. Mezi nimi můžete také vyhledávat a filtrovat je.

Položka Testovací logy skrývá také záznam plateb včetně chyb, kvůli kterým se platba nezdařila.

Po provedeném testování kontaktujte společnost Comgate, která prověří testovací platby a integraci platební brány a zažádá o schválení u karetní asociace. Tento proces trvá cca 14 dní. Během této doby lze bránu využívat pro platby bankovními tlačítky, ale nikoliv pro karetní transakce.

Jakmile budete informováni o schválení, bude vaše platební brána Comgate plně provozuschopná a můžete přes ni začít přijímat platby bez omezení.

Refundace

Plugin umožňuje přímé vrácení peněz přes platební bránu. Tuto funkci najdete v detailu objednávky > tlačítko Vrátit > Vrátit x Kč přes Comgate.

Druhou možností je nastavit automatickou refundaci podle stavu objednávky, viz Automatická refundace.

Opakované platby (Subscriptions)

Požadavky

Opakované platby vyžadují plugin WooCommerce Subscriptions. Po jeho aktivaci se funkce automaticky zapne. Manuální vypnutí/zapnutí lze provést v sekci Opakované platby. (Toret Plugins > Comgate > Opakované platby).

Jak to funguje

1. První platba (master): Zákazník zaplatí standardně přes checkout. Comgate vrátí token, který se uloží k objednávce.
2. Automatické obnovy: WooCommerce Subscriptions naplánuje obnovu a Comgate automaticky strhne platbu na pozadí pomocí uloženého tokenu — zákazník není přesměrován.
3. Změna karty: Zákazník může v sekci Můj účet → Předplatná kliknout na „Změnit platební kartu“ a provést novou verifikační platbu, která aktualizuje token.

Podporované operace

• Zrušení předplatného
• Pozastavení a obnovení předplatného
• Změna částky předplatného
• Změna data obnovy
• Změna platební metody

Důležité

• Token je vytvořen na stejném Comgate účtu, ze kterého jsou následně strhovány obnovy.
• Plugin ukládá přihlašovací údaje k předplatnému, aby bylo zajištěno správné párování i při změně globálních nastavení.
• URL předání výsledku platby musí být správně nastavena v klientské sekci Comgate (viz Propojení Comgate s WooCommerce)

Automatické opakování (nezdařených) plateb

Pokud automatické stržení selže (např. nedostatek prostředků, dočasný problém banky), plugin může platbu automaticky zkusit znovu.

Konfigurace

• Povolit opakování – Zapne automatické pokusy (max 3).
• 1. pokus po x (dní) – Výchozí: 1 den po selhání.
• 2. pokus po x (dní) – Výchozí: 7 dní po druhém selhání.
• 3. pokus po x (dní) – Výchozí: 14 dní po třetím selhání.

Po vyčerpání všech pokusů se objednávka automaticky označí jako neúspěšná.

Retry mechanismus využívá WooCommerce Action Scheduler. Ujistěte se, že WP-Cron je na vašem serveru funkční.

Pre-autorizace

Pre-autorizace zablokuje částku na kartě zákazníka, ale nestrhne ji okamžitě. Peníze se strhnou teprve po dosažení zvoleného stavu objednávky.

Kdy je to užitečné

• E-shopy odesílající zboží s prodlevou (na objednávku, předobjednávky).
• Situace, kdy chcete platbu schválit ručně před stržením.

Režimy pre-autorizace (Použít pre-autorizaci pro)

Režim	Popis
Všechny produkty	Pre-autorizace se použije pro každou objednávku
Vybrané kategorie	Pouze objednávky obsahující produkt z vybrané kategorie
Individuálně u produktu	Zaškrtávací políčko přímo v editaci produktu (záložka Obecné)

Stav pro stržení platby

Zvolte stav objednávky (např. „Zpracovává se“, „Dokončeno“), při jehož dosažení plugin automaticky strhne zablokovanou částku.

Ruční správa v objednávce

V detailu objednávky se zobrazí meta box Comgate – Pre-autorizace s informacemi:

• ID transakce
• Stav platby (Autorizováno / Strženo / Zrušeno)
• Tlačítko Strhnout platbu – okamžitě strhne blokovanou částku
• Tlačítko Zrušit rezervaci – uvolní blokaci na kartě zákazníka

---

Hooks a filtry pro vývojáře

Pro používání pluginu není nutné filtry používat. Filtry slouží k rozšíření nebo vlastní úpravě funkčnosti pluginu. S jejich implementací vám pomůže váš programátor.

Filtry

Filtr	Popis
toret_comgate_transaction_request_params	Úprava parametrů odesílaných do Comgate API při vytváření platby
tcomgate_main_icon	Přepsání ikony hlavní sdružené brány
tcomgate_email_link_label	Text tlačítka v e-mailu
tcomgate_email_link_heading	Nadpis sekce v e-mailu
tcomgate_email_link_button_color	Barva tlačítka v e-mailu
tcomgate_email_link_button_text_color	Barva textu tlačítka v e-mailu

Akce

Akce	Popis
tcomgate_gateway_hooks_registered	Spustí se po registraci všech gateway hooků

Příklad: Úprava parametrů platby

add_filter('toret_comgate_transaction_request_params', function ($params, $order) {
    // Přidání vlastního parametru
    $params['label'] = 'Moje objednávka #' . $order->get_order_number();
    return $params;
}, 10, 2);

Příklad: Vlastní barva tlačítka v e-mailu

add_filter('tcomgate_email_link_button_color', function () {
    return '#ff6600';
});

Řešení problémů

Chyba „Access from unauthorized location“

Comgate neumožňuje platby z neautorizované IP adresy serveru.

Řešení:

1. Přejděte do klientské sekce Comgate → Integrace → Nastavení obchodu → Propojení obchodu.
2. Přidejte IP adresu vašeho serveru do seznamu povolených adres.
3. IP adresu serveru najdete v záložce Diagnostika a Logy v nastavení pluginu.
4. IP adresy lze zadat i jako rozsah (např. 192.168.1.0/24).

---

Platba se nevytvoří / zákazník nevidí platební bránu

1. Zkontrolujte, že máte správně vyplněné Merchant ID a Secret Key.
2. Ověřte, že alespoň jedna platební metoda je aktivní.
3. Zkontrolujte, že v pokladně je správná měna (podporovaná vaším Comgate účtem).
4. Zapněte Debug režim a zkontrolujte WooCommerce logy.

---

Webhook nepřijímá notifikace

1. Zkontrolujte, že URL notifikací je správně nastavena v klientské sekci Comgate.
2. Ověřte, že URL yoursite.com/wc-api/toret_comgate_webhook je veřejně dostupná.
3. Zkontrolujte, že server neblokuje POST požadavky z IP adres Comgate.
4. Pokud používáte Cloudflare nebo jiný firewall, povolte přístup pro Comgate servery.

---

Opakovaná platba selhala

1. Zkontrolujte, že WP-Cron je funkční na vašem serveru.
2. Ověřte, že token (initRecurringId) je uložen u předplatného.
3. Pokud zákazník změnil kartu, nový token se uloží po dokončení verifikační platby.
4. Zkontrolujte logy v záložce Diagnostika a Logy.

---

Pre-autorizace se neaplikuje

1. Zkontrolujte, že je pre-autorizace povolena v záložce Opakované platby.
2. Pokud používáte režim Vybrané kategorie, ověřte že objednávka obsahuje produkt z vybrané kategorie.
3. Pokud používáte režim Individuálně u produktu, ověřte že je u produktu zaškrtnuto políčko „Povolit pre-autorizaci (Comgate)“.
4. Pre-autorizace funguje pouze pro karetní metody.

---

Plugin po aktualizaci na v5.0 nefunguje správně

Verze 5.0 je kompletní přepracování pluginu. Po aktualizaci:

1. Projděte všechna nastavení — plugin se pokusí migrovat existující nastavení automaticky.
2. Klikněte na Aktualizovat metody z API Comgate v záložce Platební metody.
3. Zkontrolujte URL adresy v záložce Základní nastavení a porovnejte s klientskou sekcí Comgate.
4. Ověřte, že platební metody jsou aktivní.

---

Platby na splátky

Platby na splátky jsou dostupné pouze pro Českou republiku a u objednávek nad 2000 Kč. Tato metoda platby podléhá dodatečnému schválení, je proto třeba kontaktovat společnost Comgate a o její povolení zažádat.

---

Rozpadlé zobrazení platebních metod

Chyba je v šabloně, u které bude potřeba upravit kaskádové styly.

Často pomůže vložení následujícího kódu do CSS stylu:

.comgate_select {display:flex;}

---

Vyčerpán limit přesměrování / Error in cURL request: Maximum (5) redirects followed

Platební brána předává informace o provedené/neprovedené platbě informace pomocí notifikační URL. Tato notifikační URL má nastavený maximální počet přesměrování. Jedná se o ochranu ze strany Comgate.

Některé hostingy však mají interní přesměrování a může tak dojít k vyřerpání daného limitu.

Problém je třeba řešit s hostingem a ve spolupráci s nimi vysledovat dané přesměrování a snížit jejich počet.

Tento problém vzniká například u hostingu Wedos.

Chybu také může způsobit plugin třetí strany, který přesměruje notifikaci vícekrát, než Comgate dovolí.

Zkontrolujte, zda na webu nemáte jeden z níže uvedených pluginů:

• Redirect all 404 to home

Pokud nemáte na webu žádný z uvedených pluginů, tak můžete postupně deaktivovat pluginy a testovat platby (např. v testovacím módu), dokud nepřijdete na to, který plugin způsobuje nadměrné přesměrování notifikace.

---

Comgate a RankMath

V případě, že na svém webu používáte plugin RankMath společně s naším Comgate, je potřeba v nastavení Rank Math deaktivovat funkci Redirection.

V případě zapnuté funkce totiž může dojít k nepředávání notifikací z platební brány do e-shopu.

---

Comgate API chyba: Access from unauthorized location.

Pokud se v administraci zobrazuje hláška Comgate API chyba: Access from unauthorized location, znamená to,že e-shop zakládá platby z nepovolené IP adresy serveru. To se může stát, pokud váš hosting změní IP adresy serveru.

Aby vaše platební brána opět fungovala, je potřeba v Klientském portálu Comgate povolit aktuálně správné IP adresy. Jak na to:

1. Přihlaste se do portálu Comgate: https://portal.comgate.cz/cs/prihlaseni

2. Po přihlášení přejděte v menu nahoře do záložky Integrace > Nastavení obchodů a vyberte ten, který chcete spravovat.

3. Poté klikněte na Propojení obchodu a nakonec na ikonu tužky Upravit.

4. Zadejte IP adresu/y vašeho serveru. Zjistíte ji buď u vašeho poskytovatele hostingu nebo v chybové hlášce v administraci e-shopu.

Po uložení provedených změn by vaše platební brána měla být opět funkční.

Pozn.: IP adresy se nemusí definovat jednotlivě, ale mohou být zapsány jako rozsah. Tedy IP adresa následována lomítkem a číslem určujícím počet uzamknutých bitů adresy (tzv. maskou sítě). Například tedy zápis 192.168.1.0/24 vám tedy povolí IP adresu začínající 192.168.1. s libovolným posledním číslem.