Dokumentace pluginu Toret Fio

Nacházíte se na stránkách dokumentace pluginu Toret Fio, který do e-shopu integruje službu automatické kontroly přijetí plateb z Fio Banky a stejnojmennou platební bránu.

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řte plugin Toret Fio (Toret plugins → Toret Fio), do příslušného pole vložíte licenční klíč a tlačítkem Ověřit licenci aktivujte.

Párování plateb převodem

1. Propojení pluginu s bankovním účtem

Aby se plugin spároval s bankovní účtem, tak je nutné v internetovém bankovnictví vygenerovat token. Ten vygenerujete v Nastavení → API → Přidat nový token.

S pluginem je možné spárovat více účtů najednou. Například Vám zákazníci platní na různé účty podle měny. Pluginem můžete kontrolovat platby na CZK účtu a zároveň na EUR účtu.

2. Nastavení stavu objednávky po spárování platby

V další kroku je důležité vybrat stav objednávky, na který se objednávka automaticky přepne poté, co bude spárována s platbou. Aby došlo ke spárování, tak musí souhlasit variabilní symbol s nastaveným zdrojem objednávky a také částka objednávky s částkou v platbě. Stav si nastavíte zlášť pro fyzické a virtuální produkty.

3. Párování plateb podle variabilního symbolu

Aby se objednávky spárovaly s platbou, tak musí souhlasit variabilní symbol (VS) v platbě s nastaveným zdrojem v pluginu např. s číslem objednávky. Pokud souhlasí VS a částka, tak se platba s objednávkou spáruje a změní se stav objednávky. U slovenských zákazníků se automaticky kontroluje poznámka platby. Slovenští zákazníci nemají možnost zadat variabilní symbol.

Párovat VS můžete podle ID objednávky, čísla objednávky, podporovaných číslovacích pluginů Toret Order number a WooCommerce Sequential Order number. V případě, že vám ani jedna z možností k napárování variabilního symbolu nevyhovuje, tak můžete napárovat vlastní pole. Do nastavení pluginu vložíte hodnotu vlastního pole pro získání variabilního symbolu.

Pokud chcete VS u plateb kontrolovat z více zdrojů, tak můžete nastavit záložní pole pro párování platby. Do příslušné funkce nastavíte ID vlastního pole, ze kterého má plugin získat hodnotu variabilního symbolu. 

Pokud je variabilní číslo příliš krátké, banky před něj přidávají nuly a párování plateb může selhat. Aktivací funkce Automaticky odstranit počáteční nuly z variabilního čísla tomuto selhání předejdete.

4. Načítání plateb a nastavení kontroly uhrazených objednávek

Pro načtení a aktualizaci plateb jsou dvě možnosti.

První možností, kterou doporučujeme, je načtení a aktualizace plateb pomocí URL CRONu. Každý e-shop má vlastní URL CRONu, kterou najdete v nastavení pluginu Fio. CRON nastavíte na vašem hostingu s intervalem jaký vám vyhovuje, aby se platby s objednávkami pravidelně kontrolovaly. Například můžete nastavit, aby se spouštěl každou hodinu. Tím zajistíte, že se každou hodinu zkontrolují platby s objednávkami a pokud se platba s objednávkou bude shodovat, tak se změní stav objednávky podle předchozího nastavení.

Druhou možností je automatická kontrola pomocí WordPress funkce. Tuto možnost nedoporučujeme, protože může být ovlivněna např. cashovacím nebo bezpečnostním pluginem. V případě, že si možnost automatického načtení pomocí WordPress funkce zvolíte, tak je ještě nutné v pluginu nastavit počet hodin, po jejichž uplynutí se bude výpis aktualizovat.

Pro obě možnosti aktualizace plateb je nutné ještě nastavit počet dní zpětně, tedy za jakou dobu zpětně se budou platby načítat. Tím omezíte kontrolu na konkrétní časové období a nekontrolujete všechny objednávky na e-shopu.

5. Upozornění

Nastavení funkce Upozornění není povinné pro funkčnost pluginu, ale rozhodně ji doporučujeme nastavit. Do funkce nastavíte emailovou adresu, na kterou Vám přidej email, pokud platba nesouhlasí s částkou v objednávce. Například zákazník pošle nižší nebo naopak vyšší platbu.

Upozornění na neshodující se platbu s hodnotou objednávky:

Upozornění na chybnou platbu:

Tip: Číslo objednávky v emailovém upozornění Vám vezme přímo do detailu objednávky.

6. Tabulka s načtenými platbami

Na konci nastavení pluginu najdete tabulku s načtenými pohyby na účtu. Jedná se o tabulku plateb, které se pomocí pluginu načetly z vašeho účtu. Jak už jsem zmínil, tak stav objednávky se změní pouze pokud částka a VS symbol sedí s objednávkou. V případě, že se částka liší nebo je špatně zadán nebo nebyl vyplněn variabilní symbol, tak se platba s objednávkou nespáruje a nedojde ke změně stavu objednávky.

Pro lepší přehlednost jsou jednotlivé platby podbarveny podle toho, v jakém vztahu je platba s objednávkou.

• Bílé podbarvení – Nespárována
• Zelené podbarvení – Spárováno a vše sedí
• Oranžové podbarvení – Nespárováno, částka nesedí

Tabulka obsahuje také filtr, kterým si můžete jednotlivé platby vyfiltrovat. Můžete vypsat platby, které jsou ve stavu: Spárováno, Nespárováno, Nedoplaceno, Přeplaceno.

V případě, že načítáte platby z více účtů, tak si můžete přehled v tabulce přepnout podle tokenu.

Tip: Pokud se objednávka nezpáruje z důvodu chybné částky, tak můžete kliknout na číslo objednávky ve sloupci „OBJEDNÁVKA“ a přejdete přímo do jejího detailu.

Fio platební brána

Plugin Toret Fio obsahuje také možnost nastavení platební brány, pokud ji máte u Fio banky nasmlouvanou.

Nastavení platební brány najdete v nastavení WooCommerce → Pokladna → Platební brána Fio.

Pro správnou implementaci platební brány Fio na váš eshop, budete potřebovat mít podepsanou smlouvu. V případě, že máte již vše vyřízené, obdržíte e-mailem přístupy do testovacího rozhraní. Paltební bránu Fio zaštituje GP Webpay. Integrace platební brány je tedy totožná jako v případě pluginu pro platební bránu GP Webpay.

Propojení pluginu s platební bránou

Níže najdete popsané kroky, které potřebujete pro vytvoření, stažení a nahrání klíčů do GP Webpay prostředí a do WordPressu.

Jakmile provedete testovací platby (číslo testovací karty budete mít v e-mailu nebo ji najdete zde) a GP Webpay vám potvrdí, že je vše v pořádku, dostanete produkční klíč. Nyní budete muset celý proces zopakovat na provozním prostředí – klíč opět jej nahrajete do prostředí GP Webpay a do WordPressu, upravíte nastavení jména klíče v pluginu a na závěr vypnete checkbox Test v nastavení pluginu.

Podrobný návod níže ↓

1. Přihlášení do testovacího prostředí.

Přihlášení najdete na adrese https://test.portal.gpwebpay.com/, ale i tak vám URL přijde do e-mailu včetně loginu.

Po přihlášení budete vyzváni k potvrzení údajů a změně vygenerovaného hesla. Na e-mail vám bude zaslán kód pro potvrzení změny.

2. Vytvoření a uložení testovacího klíče

Znovu se přihlásíte a vygenerujete soukromý klíč.

Soukromý klíč

Vytvoření a nahrání soukromého klíče se skládá z více kroků. Nejprve přejděte do sekce Správa klíčů a klikněte na Vytvořit.

V dalším kroku si ke klíči vytvořte libovolné heslo, které si poznamenejte, budete ho dále potřebovat v účtu GP Webpay a při nastavení pluginu viz. Nastavení a možnosti pluginu.

Po vytvoření se klíč stáhne do počítače.

Nyní můžete rovnou klíč uložit do paměti prohlížeče. Vrátíte se do sekce Správa klíčů a rozkliknete si e-shop.

Zde je nutné vložít klíč, který se stáhl do počítače.

Při vkládání soukromého klíče do paměti prohlížeče vyberte možnost Trvale → přes tlačítko Vybrat soubor vložte stažený klíč → vyplňte heslo, které jste si v předchozím kroku vytvořili → vložte klíč tlačítkem.

Následně je nutné nahrát klíč do adresáře WordPressu. K tomu použijte funkci v nastavení pluginu „Nahrát privátní klíč“. 

3. Nastavení pluginu

Po vytvoření klíčů v administraci GP Webpay přejděte do nastavení pluginu Fio, které najdete ve WooCommerce → Nastavení → Pokladna → Platební brána Fio.

Pojďme si podrobněji popsat jednotlivé kroky:

1.  Povolit/Zakázat – zaškrtnutím tohoto políčka, určíte, zda budou mít zákazníci tuto platební metodu na stránce Pokladna k dispozici či ne

2. Titulek –  zde si můžete upravit název platební metody tak, jak se bude zobrazovat při výběru platební metody na pokladně

3. Popis – v tomto poli můžete pro zákazníka popsat instrukce k platbě

4. Ikona platební metody – pokud chcete vlastní ikonu platební metody, zadejte její URL zde. V Opačném případě je nastavena defaultní ikona z pluginu.

5. Test mód – v tomto checkboxu aktivujete/deaktivuje testovací prostředí

6. Číslo obchodníka – do tohoto pole zadejte číslo obchodníka, které vám bylo přiděleno

7. Nahrát soukromý klíč – Přes tlačtko „vybrat soubor“ nahrajete vytvořený soukromý klíč. 

8. Povolit způsob dopravy –  pokud chcete povolit všechny způsoby dopravy, ponechejte toto pole prázdné. Případně si můžete definovat pro platební bránu jen některé způsoby dopravy.

9. Povolit GP Webpay pro země – specifikujte, pro které země bude brána dostupná

10. Instrukce – zde napište instrukce k platbě, které se budou zobrazovat na Děkovné stránce a potvrzovacím e-mailu

Po vyplnění údajů nezapomeňte kliknout na tlačítko Uložit změny.

Po nastavení integrace a nastavení pluginu proveďte testovací platby s testovací platební kartou:

Číslo karty: 4056070000000016
Platnost karty: 12/2025
CVC2: 442

4. Přechod na produkční prostředí

Po úspěšné integraci e-shopu na testovacím prostředí napište na e-mail gpwebpay@gpe.cz. Ze strany platební brány vám bude zaslán e-mail s přístupem do produkčního prostředí, kde si vytvoříte nový produkční soukromý klíč (obdobně jako v kroku 2).

Nový integrační klíč budete muset opět nahrát přes nastavení pluginu Fio do adresáře WordPressu. V případě, že jste u soukromého klíče zvolili nové heslo, tak i do pluginu uložte nové heslo a poté vypněte checkbox Test v nastavení pluginu (viz krok 3).

Soukromý klíč

Automatické načítání stavu plateb

V případě dokončení platby je zákazník přesměrován na děkovnou stránku. Zároveň je předána notifikace o tom, že je objednávka uhrazena a dojde ke změně stavu objednávky na Zpracovává se (u fyzických produktů) nebo na Dokončeno (u virtuálních produktů).

Může se však stát, že zákazník z nějakého důvodu nebyl po uhrazení objednávky přesměrován na děkovnou stránku. V tom případě plugin nemá žádnou informaci od platební brány o tom, že je objednávka uhrazena. Aby nedošlo k tomu, že uhrazené objednávky bez notifikace budou funkcí WooCommerce zrušeny, je nutné nastavit funkci automatického načítání plateb.

Nastavení automatického načítání stavu platby najdete po kartou Toret Plugin → Toret Fio. 

Toret Fio – Automatické načítání stavu platby

1) Nastavíte počet dní pro zpětnou kontrolu stavů plateb u objednávek, tedy v jakém zpětném časovém horizontu se budou objednávky kontrolovat.

Toret Fio – nastavení počtu dní pro zpětnou kontrolu

2) Pokud nechcete kontrolovat stav platby u všech objednávek, je možné vybrat jednotlivé stavy objednávek, které se z kontroly vyřadí. Rozhodně nedoporučujeme vylučovat stav Čeká na platbu, Selhalo a Zrušeno.

Toret Fio – nastavení stavů objednávky, které se nebudou kontrolovat

3) Změna stavu objednávky podle stavu platby. V případě, že chcete po potvrzení úhrady objednávky změnit stav např. na „Zpracovává se“ nebo jiný preferovaný stav, tak u stavu platby „Požadavek na stržení“ si nastavte stav objednávky, na který se objednávka přepne. Ve stavu platby „Požadavek na stržení“ se bere objednávka jako uhrazená.

Toret Fio – změna stavu objednávky podle stavu platby

Funkci změny stavu objednávky na základě stavu platby je nutné povolit aktivací checkboxu.

Toret Fio – aktivace změny stavu objednávky na základě stavu platby

4) Aby se stav plateb aktualizoval podle nastavení z předchozích tří bodů, tak je nutné na hostingu nastavit URL CRONu, která je uvedená v nastavení u vás na webu. CRON doporučujeme pravidelně spouštět, minimálně 1x za hodinu.

Toret FIO – nastavení CRONu

Testovací platební karta

Číslo karty: 4056070000000016
Platnost karty: 12/2025
CVC2: 442

Časté dotazy

Přepnutí stavu objednávky do vlastního stavu

Pro nastavení přepnutí stavu objednávky do vlastního stavu použijte níže uvedený filtr do function.php v child šabloně, aby se filtr při aktualizaci nesmazal.

$status_set = apply_filters( ‚fio_set_status‘, $option[‚order‘], $order );

Jak nastavit párování s vlastním číslováním objednávek?

Pro vlastní párování ojednávek je potřeba do pluginu vložit název vlastního pole (custom field), které obsahuje nové číslo objednávky.

Příklad:

Booster for WooCommerce –  _wcj_order_number 

Filtry

Rozšíření stavu objednávek

V případě, že potřebujete nějakým způsobem ovlivnit rozšíření stavů objednávek, při kterých se nebude kontrolovat stav platby, byl přidán následující filtr:

$statuses = array(
'completed',
'failed',
'cancelled',
'refunded'
);
return apply_filters( 'fio_blocked_order_statuses', $statuses );
add_filter( 'fio_blocked_order_statuses', 'extend_fio_blocked_order_statuses' );
function extend_fio_blocked_order_statuses( $statuses ){
$statuses[] = 'nezaplaceno';
return $statuses;
}

Filtr pro změnu stavu objednávky po spárování platby

Po spárování objednávky s platbou je možné skrze plugin FIO automaticky změnit stav na Zpracovává se nebo Dokončeno. V případě, že používáte vlastní stavy objednávek a chcete po spárování platby změnit objednávku na vlastní stav, tak je nutné upravit plugin pomocí filtru.

Definice filtru zde:

$status_set = apply_filters( ‚fio_set_status‘, ‚processing‘, $order );

Příklad filtru:

add_filter( 'fio_set_status', 'fio_set_status_function', 1, 2 );
if( !function_exists( 'fio_set_status_function' ) ){
function fio_set_status_function( $status , $order ){
return 'completed';
}
}

Místo hodnoty completed použijete slug vlastního stavu.

Filtr vložíte do child šablony functions.php nebo do prázdného pluginu např. Boilerplate.