Platební plugin pro VirtueMart, který zákazníkovi ukáže QR kód pro platbu převodem (formát QR Platba / SPAYD) na děkovací stránce, v detailu objednávky a v potvrzovacím e-mailu. Volitelně stahuje příchozí platby z Fio banky, páruje je s objednávkami podle variabilního symbolu a objednávku sám přepne na zaplacenou.
| Joomla | VirtueMart | PHP | Aktuální verze |
|---|---|---|---|
| 4.x, 5.x | 4.x | 8.1+ | 1.0.9 |
1. Požadavky
- Joomla 4.x nebo 5.x (VirtueMart zatím Joomlu 6 nepodporuje)
- VirtueMart 4
- PHP 8.1 nebo novější s rozšířeními
gd(obrázek QR kódu do e-mailu) aopenssl(šifrování tokenu banky) - Bankovní účet v CZK, na který zákazníci platí
- Pro automatické ověření plateb: účet u Fio banky a možnost spouštět cron (volání URL) na hostingu
Bez Fio účtu plugin funguje v režimu Bez ověření: zákazník dostane QR kód a platby potvrzujete ručně tlačítkem v objednávce.
2. Instalace
- Stáhněte ZIP
plg_vmpayment_semaqr-X.Y.Z.zipze SemaHubu (Semakin.cz). - V administraci Joomly otevřete Systém > Instalovat > Rozšíření a ZIP nahrajte.
- Otevřete Systém > Spravovat > Pluginy, vyhledejte SemaQR for VirtueMart a zapněte ho. Po nové instalaci je plugin vypnutý.
Instalátor založí dvě vlastní tabulky: #__sema_qrpay_transactions (stažené platby z banky) a #__sema_qrpay_sync_state (stav stahování). Platební údaje objednávek si VirtueMart ukládá do své tabulky #__virtuemart_payment_plg_semaqr.
3. Nastavení VirtueMartu
Dvě věci ve VirtueMart > Konfigurace > Obchod, bez kterých plugin nefunguje celý:
- Bezpečná cesta (safe path) musí být nastavená. Klíčem z ní VirtueMart šifruje Fio token. Když chybí, formulář platební metody na to upozorní a token se uloží nešifrovaně.
- Mezi stavy, ve kterých se posílá e-mail zákazníkovi, musí být stav Stav po vytvoření objednávky z platební metody (výchozí U – Potvrzeno zákazníkem). Jinak zákazník e-mail s QR kódem nedostane.
Výchozí stav je záměrně U, ne P – Čeká na vyřízení: stav P ve výchozím nastavení VirtueMartu mezi stavy s e-mailem zákazníkovi není.
4. Založení platební metody
- Otevřete VirtueMart > Platební metody > Nová.
- Vyplňte název (např. QR platba převodem), jako Platební metoda zvolte SemaQR for VirtueMart a uložte.
- Po uložení se objeví záložka Konfigurace s parametry pluginu. Vyplňte je podle následujících kapitol a uložte znovu.
Jedna metoda = jeden účet. Pro jiný účet nebo jinou měnu (např. EUR účet pro Slovensko) založte další metodu se SemaQR. Omezení podle zemí a částky objednávky nastavíte ve VirtueMartu běžně, na záložce metody.
5. Účet a QR kód
| Pole | Výchozí | Význam |
|---|---|---|
| IBAN | – | Povinné. Účet, na který zákazník platí. Kontroluje se kontrolní součet; s neplatným IBAN se metoda v košíku nezobrazí a administrace na to upozorní. |
| BIC / SWIFT | – | Nepovinné. Připojí se do QR kódu za IBAN. |
| Číslo účtu | – | Tuzemský tvar (např. 2600123456/2010) pro zákazníky, kteří platbu zadávají ručně. |
| Povolené měny | jen CZK | Metoda se nabídne jen při nákupu v těchto měnách. |
| Variabilní symbol z | Číslo objednávky | Číslo, nebo ID objednávky. Použijí se jen číslice, nejvýše posledních 10. Když číslo objednávky žádnou číslici nemá, použije se ID. |
| Zpráva pro příjemce | Objednavka {ORDER_NUMBER} | Zástupné symboly {ORDER_NUMBER} a {SHOP_NAME}. V QR kódu se zapíše bez diakritiky, velkými písmeny, nejvýše 60 znaků. |
| Velikost QR (px) | 300 | Strana QR kódu na webu i v e-mailu. |
| Formát QR na webu | SVG | SVG je ostré a vkládá se přímo do stránky. V e-mailu je vždy PNG. |
Variabilní symbol se počítá z čísla objednávky. Pokud čísla objednávek obsahují písmena (výchozí formát VirtueMartu), zvolte ID objednávky nebo si nastavte číselná čísla objednávek – zákazník pak vidí na výpisu stejné číslo jako v e-mailu.
6. Banka a ověření plateb
| Pole | Výchozí | Význam |
|---|---|---|
| Ověřování plateb | Bez ověření | Bez ověření = jen QR kód, stav objednávky měníte ručně. Fio banka (API) = automatické párování. Testovací data jsou jen pro vývoj a fungují pouze se zapnutým ladicím režimem. |
| Fio API token | – | Token jen pro čtení, viz kapitola 7. |
| Překryv stahování (dny) | 3 | Kolik dní před posledním úspěšným stažením se pohyby stahují znovu. Chrání před platbami, které banka zaúčtuje se zpožděním. |
| Klíč pro cron | vygeneruje se | Tajný klíč v URL webcronu, nejméně 32 znaků. Vygeneruje se sám při otevření formuláře; použije se po uložení metody. |
| Tolerance částky (absolutní) | 1.00 | Rozdíl, který se ještě bere jako přesná platba. |
| Tolerance částky (%) | 0.5 | Procento z částky objednávky. Platí větší z obou tolerancí. |
| Stav po vytvoření objednávky | U – Potvrzeno zákazníkem | Stav, ve kterém objednávka čeká na platbu. Musí posílat e-mail zákazníkovi (kapitola 3). |
| Stav po zaplacení | C – Potvrzeno | Nastaví se po spárování platby v plné výši. Pokud VirtueMart při tomto stavu vystavuje fakturu, vystaví ji. |
| Stav při nedoplatku | U – Potvrzeno zákazníkem | Nastaví se, když přijde nižší částka. |
| E-mail pro upozornění | e-mail obchodu | Kam chodí upozornění na chyby a platby ke kontrole. |
| Denní souhrn nespárovaných plateb | Ano | Jednou denně seznam příchozích plateb, které se nepodařilo přiřadit k objednávce. |
| Upozornit po N chybách | 3 | Po kolika neúspěšných staženích z banky v řadě přijde e-mail. |
7. Fio API token
- Přihlaste se do internetového bankovnictví Fio a otevřete Nastavení > API.
- Zvolte Přidat nový token pro účet, na který zákazníci platí, s oprávněním jen pro čtení (pohyby na účtu).
- Token vložte do pole Fio API token v platební metodě a metodu uložte.
Token s oprávněním jen pro čtení neumožňuje z účtu nic odeslat. VirtueMart ho ukládá zašifrovaný klíčem z bezpečné cesty. Má-li token omezenou platnost, po vypršení vložte do metody nový – plugin vás na nefunkční spojení upozorní e-mailem (kapitola 13).
Fio API povoluje jeden dotaz za 30 sekund na token. Když token sdílí dvě metody nebo dva weby, část běhů se přeskočí a platby se stáhnou v dalším běhu. Nic se tím neztratí.
8. Webcron
Platby z banky stahuje a páruje webcron – pravidelné volání adresy na vašem webu. Po uložení metody s bankou se adresa zobrazí v modré zprávě nahoře ve formuláři metody:
https://vas-eshop.cz/index.php?option=com_virtuemart&view=plugin&type=vmpayment&name=semaqr&task=cron&key=<klíč>&format=rawDoporučený interval je 2–5 minut. Děkovací stránka jen čte stav z databáze; platbu spáruje až nejbližší běh cronu. Jeden klíč spustí všechny metody, které ho mají nastavený – běží i nepublikované metody.
| Hosting | Nastavení |
|---|---|
| Wedos | V administraci webhostingu založte cron úlohu, která volá adresu webcronu, s nejkratším dostupným intervalem. |
| Forpsi | Administrace > Plánovač úloh > volání URL, interval nejméně 5 minut. Po odpovědi 4xx (např. 403 při špatném klíči) Forpsi úlohu zastaví a je potřeba ji v panelu znovu zapnout. |
| Vlastní server | */3 * * * * curl -fsS '<adresa webcronu>' >/dev/null |
Webcron odpoví 200 s krátkým přehledem (staženo, nových, spárováno, nedoplatků, nespárováno, chyb), se špatným klíčem 403. Pokud hosting nenásleduje přesměrování, použijte adresu přesně v podobě, jakou ukazuje formulář (včetně www., pokud ji tak web používá).
Při prvním běhu se pohyby stahují od nejstarší objednávky, která čeká na platbu (nejvýše od dneška minus překryv), ne za celou historii účtu.
9. Zobrazení zákazníkovi, vzhled a poplatky
| Pole | Výchozí | Význam |
|---|---|---|
| Interval kontroly platby (s) | 12 | Jak často děkovací stránka zjišťuje, jestli je zaplaceno. |
| Doba čekání na platbu (s) | 600 | Po této době stránka přestane stav kontrolovat. Potvrzení pak přijde zákazníkovi e-mailem. |
| Logo a poznámka v košíku | Ano | Pod názvem metody ve výběru platby logo QR Platba a krátká poznámka. Vypněte, pokud stačí název a popis metody. |
| Zobrazit platební údaje textem | Ano | Vedle QR kódu vypsat číslo účtu, variabilní symbol, částku a zprávu pro ruční zadání. |
| Ladicí režim | Ne | Podrobný záznam do administrator/logs/semaqr.php. Chyby se zapisují vždy. |
| Loga, Informace o platbě | – | Běžná pole VirtueMartu: loga u metody a text připojený k názvu metody v objednávce. |
| Poplatky a daň | – | Pevný, minimální a procentní poplatek za platbu a daňové pravidlo, jako u ostatních metod. |
Blok s QR kódem nemá vlastní pozadí ani barvu textu – přebírá je ze šablony e-shopu, takže funguje se světlou i tmavou šablonou. Bílé je jen pole pod samotným QR kódem, aby šel spolehlivě naskenovat.
10. Jak platí zákazník
- V košíku zvolí QR platbu a dokončí objednávku.
- Na děkovací stránce vidí QR kód, platební údaje a stav Čekáme na platbu…. Otevře aplikaci banky, zvolí platbu QR kódem a kód naskenuje – účet, částka, variabilní symbol i zpráva se vyplní samy.
- Nakupuje-li na telefonu, uloží si QR kód tlačítkem Uložit QR kód do telefonu a v aplikaci banky ho načte z obrázku. Na iPhonu se otevře nabídka sdílení, ve které zvolí uložení obrázku.
- QR kód dostane také v potvrzovacím e-mailu a najde ho v detailu objednávky ve svém účtu, takže může zaplatit později.
- Jakmile cron platbu spáruje, děkovací stránka (pokud je ještě otevřená) ukáže Platba přijata ✓ a VirtueMart pošle e-mail o změně stavu podle svého nastavení.
Když v administraci změníte částku objednávky, která ještě čeká na platbu, QR kód se při dalším zobrazení přepočítá na novou částku.
11. Párování plateb
Každá příchozí platba se hledá podle variabilního symbolu mezi objednávkami zaplacenými touto metodou. Pak rozhoduje částka a měna:
| Situace | Co se stane |
|---|---|
| Částka sedí (v toleranci) | Objednávka přejde do stavu Stav po zaplacení, do historie se zapíše přijatá částka. |
| Nedoplatek | Objednávka přejde do stavu Stav při nedoplatku. Zákazník na webu i v e-mailu vidí QR kód na zbývající částku. Další platby se sčítají; po doplacení je objednávka zaplacená. |
| Přeplatek | Objednávka je zaplacená, do historie se zapíše výše přeplatku a správci přijde e-mail. |
| Platba v jiné měně | Nespáruje se, správci přijde e-mail ke kontrole. |
| Platba na zrušenou objednávku | Nespáruje se, správci přijde e-mail ke kontrole. |
| Druhá platba na zaplacenou objednávku | Nespáruje se jako duplicitní, správci přijde e-mail ke kontrole. |
| Bez variabilního symbolu nebo s neznámým symbolem | Zůstane v seznamu nespárovaných plateb a objeví se v denním souhrnu. |
Platby, které s e-shopem nesouvisejí, plugin nemění – jen je eviduje mezi nespárovanými. Jméno plátce a údaje z banky se ukládají jen pro administraci, na web se nedostanou.
12. Platba v administraci objednávky
V detailu objednávky (VirtueMart > Objednávky) má blok platby SemaQR stav platby, zaplacenou částku, datum a ID transakce a tři akce:
- Ověřit platbu nyní – okamžité stažení pohybů z banky, nemusíte čekat na cron. Platí limit Fio API 30 sekund.
- Označit jako zaplaceno – ruční potvrzení bez platby z banky (např. platba přišla na jiný účet). Jako zaplacená částka se zapíše částka objednávky a do historie, kdo objednávku označil.
- Nespárované platby (N) – seznam příchozích plateb za posledních 30 dní, které se nepodařilo přiřadit. U každé můžete:
- Spárovat zadáním čísla objednávky – platí stejná pravidla měny a tolerance jako u cronu;
- Ignorovat – platba zmizí ze seznamu i ze souhrnu.
Odkaz na nespárované platby je i ve formuláři platební metody.
13. E-mailová upozornění
Na adresu z pole E-mail pro upozornění (nevyplněno = e-mail obchodu) chodí:
- Chyba spojení s bankou – po nastaveném počtu neúspěšných stažení v řadě (výchozí 3). Další upozornění přijde až po úspěšném spojení a novém selhání.
- Platba vyžaduje kontrolu – přeplatek, platba v jiné měně, platba na zrušenou nebo už zaplacenou objednávku. Každá platba jen jednou.
- Denní souhrn nespárovaných plateb – jednou za 24 hodin, lze vypnout.
Chodí-li na účet i platby mimo e-shop (faktury, převody), objeví se v souhrnu každý den. V tom případě souhrn vypněte – upozornění na platby ke kontrole chodí dál a nespárované platby najdete v administraci.
14. Aktualizace a odinstalace
Aktualizace přicházejí přes Systém > Aktualizace jako u ostatních rozšíření, pokud máte v nastavení aktualizačního serveru SemaHub vyplněný klíč ke stažení (Download ID) z vašeho účtu na Semakin.cz. Nastavení platební metody se aktualizací nemění.
Odinstalace smaže tabulky #__sema_qrpay_transactions a #__sema_qrpay_sync_state. Tabulka VirtueMartu s platebními údaji objednávek zůstává, jak je u platebních pluginů VirtueMartu zvykem. Před odinstalací zrušte cron úlohu na hostingu.
15. Řešení problémů
Metoda se v košíku nezobrazuje
- Plugin SemaQR for VirtueMart není zapnutý (po instalaci je vypnutý).
- IBAN není platný – administrace to hlásí po uložení metody.
- Měna košíku není mezi Povolenými měnami (nevyplněno = jen CZK).
- Zabraňuje tomu omezení metody ve VirtueMartu (země, částka, skupina zákazníků).
Zákazníkovi nepřišel e-mail s QR kódem
Stav po vytvoření objednávky není mezi stavy, ve kterých VirtueMart posílá e-mail zákazníkovi (kapitola 3).
Platba je na účtu, ale objednávka se nepřepnula
- Cron neběží – otevřete adresu webcronu v prohlížeči. Musí vrátit
200;403znamená špatný klíč (na Forpsi pak úlohu znovu zapněte). - Platba má jiný nebo žádný variabilní symbol – najdete ji v Nespárovaných platbách a spárujete ručně.
- Platba přišla v jiné měně nebo na zrušenou objednávku – správci přišel e-mail ke kontrole.
- Fio platbu ještě nezaúčtovalo – mezi bankami to může trvat i do dalšího pracovního dne.
- Zkuste v objednávce Ověřit platbu nyní; podrobnosti zapisuje log
administrator/logs/semaqr.php(pro víc detailů zapněte ladicí režim).
Ověření hlásí „Banka povoluje dotaz jednou za 30 s“
Fio API přijímá jeden dotaz za 30 sekund na token. Zkuste to za chvíli; běžný cron to řeší sám v dalším běhu.
Formulář metody upozorňuje na chybějící bezpečnou cestu
Nastavte Bezpečnou cestu v Konfiguraci VirtueMartu (Obchod) a metodu uložte znovu, aby se token uložil zašifrovaný.
Denní souhrn chodí každý den s cizími platbami
Na účet chodí i platby mimo e-shop. Souhrn vypněte (Denní souhrn nespárovaných plateb = Ne), nebo nepotřebné platby v seznamu ignorujte.
Jak to vypadá v praxi
