WC QR Platba – Fio banka

WooCommerce platební brána pro české e-shopy, která umožní zákazníkům zaplatit objednávku přes QR kód (Czech QR platba / SPayD).

Plugin po vytvoření objednávky zobrazí platební údaje a QR kód, následně automaticky kontroluje příchozí platby přes Fio API a objednávku označí jako zaplacenou.

Hlavní funkce

• QR platba pro WooCommerce checkout
• Automatická kontrola plateb přes Fio API (cron)
• Ověření platby podle variabilního symbolu (VS)
• Kontrola výše platby s tolerancí (zaokrouhlení)
• Podpora klasického checkoutu i WooCommerce Blocks
• Podpora HPOS (High-Performance Order Storage)
• Polling na thank-you stránce (automatické potvrzení po připsání platby)
• Ruční kontrola plateb z administrace WooCommerce
• Přehled VS/TX přímo ve sloupci objednávek

Požadavky

• WordPress 5.8+
• WooCommerce 6.0+
• PHP 7.4+
• Aktivní účet u Fio banky s vygenerovaným API tokenem pro čtení transakcí

Instalace

1. Nahrajte plugin do adresáře wp-content/plugins/wc-qr-platba-fio.
2. Aktivujte plugin v administraci WordPressu.
3. Přejděte do WooCommerce → Nastavení → Platby → QR Platba (Fio banka).
4. Vyplňte bankovní údaje a Fio API token.
5. Uložte nastavení a povolte platební metodu.

Konfigurace platební brány

V administraci nastavte:

• Číslo účtu (bez lomítka)
• Předčíslí účtu (volitelné)
• Kód banky (pro Fio obvykle 2010)
• Majitel účtu
• Fio API token
• Předpona variabilního symbolu (volitelně)
• Velikost QR kódu

Variabilní symbol (VS)

• Výchozí VS je ID objednávky.
• Pokud nastavíte předponu, plugin vytvoří VS ve tvaru prefix + order_id.
• Výsledný VS je omezen na max. 10 číslic.

Jak to funguje

1. Zákazník zvolí platební metodu QR Platba – bankovní převod.
2. Po dokončení objednávky se zobrazí platební instrukce a QR kód.
3. Plugin pravidelně načítá transakce z Fio API.
4. Podle VS dohledá objednávku, ověří částku a stav objednávky.
5. Pokud je vše v pořádku, objednávku označí jako zaplacenou (payment_complete).

WooCommerce Blocks a HPOS

Plugin deklaruje kompatibilitu s:

• cart_checkout_blocks
• custom_order_tables (HPOS)

Díky tomu je platební metoda dostupná i v moderním block checkoutu.

Poznámky k provozu

• Automatická kontrola plateb běží přes WP-Cron (interval hourly).
• Na thank-you stránce běží polling přes AJAX, který kontroluje stav objednávky.
• Pokud chybí js/qrcode.min.js, plugin zobrazí instrukce pro ruční převod bez QR kódu.

Troubleshooting

Platební metoda se nezobrazuje v checkoutu

• Ověřte, že je metoda aktivní.
• Ověřte vyplněné číslo účtu a kód banky.
• Zkontrolujte, že používáte kompatibilní verze WordPress/WooCommerce.

Platby se nepárují automaticky

• Zkontrolujte platnost Fio API tokenu.
• Ověřte, že zákazník použil správný VS.
• Ověřte, že přijatá částka není nižší než částka objednávky.
• Prověřte, že WP-Cron na hostingu běží.

QR kód se nezobrazí

• Ověřte přítomnost souboru js/qrcode.min.js v pluginu.

Vývoj

Repo obsahuje hlavní soubory:

• wc-qr-platba-fio.php – bootstrap pluginu, cron, AJAX, párování plateb
• class-wc-qr-platba-fio-gateway.php – definice WooCommerce gateway a zobrazení QR
• class-wc-qr-platba-fio-blocks.php – registrace metody pro WooCommerce Blocks
• js/wc-qr-fio-blocks.js – frontend registrace platební metody pro block checkout

Licence

Projekt je licencován pod GPLv2 or later. Viz soubor LICENSE.

Autor

Adam Hornof
https://hornof.dev