Dokumentace pluginu Toret GoPay Inline

Nacházíte se na stránkách dokumentace pluginu GoPay Inline, který integruje platební bránu GoPay.

Instalace pluginu

Po zakoupení pluginu obdržíte e-mailem 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 GoPay Inline, do příslušného pole vložíte licenční klíč a tlačítkem aktivujte.

Videonávod

Nastavení přístupových údajů

V nastavení pluginu GoPay (Toret plugins > GoPay Inline) je nutné zadat následující údaje, které získáte od společnosti GoPay:

• GoID – id eshopu, které jste obdrželi od GoPay
• ClientID – vaše přidělené klientské číslo
• Client secret – kód, pro spojení s api GoPay

!Pozor: Před ostrým spuštěním provozu, je třeba platební bránu otestovat. Proto nejprve od GoPay obdržíte testovací údaje. Teprve po úspěšném otestování získáte údaje provozní, kterými je nahradíte.

Test mód – nastavení určuje, zda provádíte testovací platby, či již nastavujete ostrý provoz. Zapněte jej, pokud vkládáte testovací údaje.

Při komunikaci s GoPay po Vás bude vyžadována notifikační URL. Je potřeba jim sdělit, že plugin GoPay Inline používá technologii Rest API, což znamená, že si tuto notifikační URL vygeneruje a pošle sám.

Nastavení daňových sazeb

Daňové sazby k příplatkům, dopravě a kupónům nastavíte v nastavení pluginu (Toret plugins > GoPay Inline).

Aktivace platebních metod

Po aktivaci licence, je třeba aktivovat platební metody GoPay Inline. To provedete ve WooCommerce > Nastavení > Pokladna. Zde ze seznamu vyberete a povolíte platební metody, které chcete využívat.

Pozor! Vždy je třeba mít aktivní platební metodu „GoPay“. Bez její aktivace nebudou funkční ani žádné další GoPay metody platby (např. GoPay: mPlatba).

Jakmile metodu aktivujete přepínačem, budete mít tuto platbu k dispozici. Klikněte na Spravovat a pokračujte s nastavením platební metody.

Nastavení platebních metod

Po rozkliknutí platební metody lze nastavit:

• titulek a popis metody, které se zobrazí v pokladně
• způsoby dopravy zásilky, pro které bude tato platební metoda dostupná
• země, pro které bude tato platební metoda dostupná
• ikonu platební metody, která se zobrazí v pokladně

Provedené změny nezapomeňte uložit.

Povolení doprav a zemí

Pro správné fungování platebního procesu je často nutné omezit platební bránu jen na určité země nebo dopravní metody.

Např. Pro osobní vyzvednutí můžete chtít zakázat platbu kartou.

V nastavení platební metody najdete pole pro způsoby dopravy a země, kterých se omezení bude týkat.

Apple Pay

Pokud chcete v pokladně nabízet metodu platby Apple Pay, je třeba ji nejprve aktivovat v GoPay účtu na gopay.cz

Po aktivaci v účtu můžete metodu platby GoPay: Apple Pay aktivovat v nastavení WooCommerce pokladny (viz výše). Nyní se Vám v pokladně zobrazí platební metoda Apple Pay. 

!Pozor: V testovacím režimu nelze úspěšně uhradit platbu Apple Pay, protože neumožňuje využít testovací platební karty. Všechny platby se tedy budou jevit zamítnuté ze strany banky.

Původní nastavení platební metody GoPay

Jedná se o starší verzi nastavení platební metody, ve které jsou všechny způsoby platby GoPay v jedné platební metodě WooCommerce – platební metoda „GoPay“.

Pozor! Způsoby platby nastavené v této metodě se nezobrazují v případě použití blokového editoru v pokladně (Gutenberg pokladna), ale i tak je při použití blokové pokladny nutné mít tuto metodu aktivní. Pro zobrazení jednotlivých metod v Gutenberg pokladně využijte oddělené platební metody GoPay.

Toto nastavení provedete přes metodu platby GoPay (WooCommerce >Nastavení > Pokladna > GoPay). Zde lze nastavit:

• titulek a popis metody, které se zobrazí v pokladně
• způsoby dopravy zásilky, pro které bude tato platební metoda dostupná
• země, pro které bude tato platební metoda dostupná
• ikonu platební metody
• povolené platební metody a bankovní převody
• výběr, předvýběr a řazení metod v pokladně

Pole Povolit GoPay platební metody slouží k výběru metod, které se zobrazí v pokladně. Po kliknutí do pole se zobrazí dostupné platební metody, ze kterých vyberete požadované. Provedené změny nezapomeňte uložit ve spodní části stránky.

Testování plateb

Všechny údaje i postup plateb pro otestování platební brány najdete v testovacím integračním soupisu, který jste obdrželi od společnosti GoPay po schválení vaší registrace.

Pro vyzkoušení funkčnosti pluginu se používají tyto testovací karty:

Typ karty	Číslo karty	Stav autorizace
MasterCard	5447380000000006	Úspěšná – platba uhrazena
VISA	4444444444444448	Úspěšná – platba uhrazena
VISA	4188030000000011	Nedostatek peněžních prostředků na kartě – platba zamítnuta
Maestro	6705040000000019	Zamítnuto v autorizačním centru banky – platba zamítnuta
MasterCard	5160000000000013	Špatné číslo karty – platba zamítnuta

Podmínkou testování je zapnutý testovací mód v pluginu.

Jakmile máte testování za sebou, napište e-mail na integrace@gopay.cz. Pracovníci GoPay následně zkontrolují, jestli se vám podařilo správně integrovat platební bránu GoPay na vašem e-shopu. Pokud je vše v pořádku, získáte provozní údaje pro ostrý provoz platební brány. Tyto údaje zadáte namísto testovacích a vypnete testovací mód. Nyní již můžete přijímat platby přes tuto platební bránu.

Kompatibilita s WPML

WPML je jeden z nejpoužívanějších pluginů pro vytváření jazykových verzí WordPress stránek.

Plugin pro platební bránu je plně přeložitelný, pomocí MO souborů, s kterými umí pracovat program PoEdit a plugin Loco Translate.

Plugin obsahuje detekci zvoleného jazyka a podle něj nastaví jazyk dialogu platební brány.

Akceptovány jsou tyto jazyky:

• Angličtina
• Němčina
• Ruština
• Polština
• Slovenština
• Čeština

Při jiném jazyce je automaticky nastavena čeština.

Omezení platebních metod pomocí filtru

Výběr platebních metod, které GoPay nabízí, umožňuje select s ikonami každé platební metody.

Protože má GoPay nastavení, které umožňuje vybrat, pro které země se bude nabídka zobrazovat, můžete výběr povolit například pro Českou Republiku, ale pro Slovensko ne.

To může být problematické, pokud potřebujete pro některé případy vypnout určité platební metody.

Proto plugin obsahuje filter gopay_checkout_enabled_methods, který umožňuje upravovat pole platebních metod pro GoPay.

Jsou to:

• PAYMENT_CARD
• BANK_ACCOUNT
• PRSMS
• MPAYMENT
• PAYSAFECARD
• SUPERCASH
• GOPAY
• PAYPAL
• BITCOIN

Následující funkce umístěná do souboru functions.php zobrazí pro angličtinu a němčinu (při použití WPML) jen PayPal a platební kartu:

add_filter( 'gopay_checkout_enabled_methods', 'custom_en_payments' );
function custom_en_payments( $payment_methods ){

    if( ICL_LANGUAGE_CODE == 'en' || ICL_LANGUAGE_CODE == 'de' ){

        $new_array = array();

        foreach( $payment_methods as $key => $item ){
             if( $key == 'PAYMENT_CARD' ){
                  $new_array[$key] = $item;
             }
             elseif( $key == 'PAYPAL' ){
                  $new_array[$key] = $item;
             }

         }

         if( !empty( $new_array ) ){
              return $new_array;
         }


     }
     return $payment_methods;

}

Výchozí jazyk platební brány

Platební brána GoPay podporuje několik jazyků. Podle fakturační země, kterou zákazník zadá v pokladně, plugin určí, v jakém jazyce se bude brána zobrazovat.

Např. při zadání slovenské fakturační adresy bude rozhraní ve slovenštině.

Je ale možné, že zákazník bude z jiné země, než je nadefinováno v pluginu (GB, DE, PL, SK a CZ). Proto je možné v nastavení pluginu Toret plugins > GoPay Inline, zvolit výchozí jazyk pro všechny ostatní země.

Pro pokročilé nastavení obsahuje plugin i filtr, který umožňuje manipulovat s jazykem brány:

return apply_filters( ‚gopay_inline_default_lang‘, $lang, $order );

Filtry

Jazyk platební brány

Vyvolání dialogu platební brány lze provést v různých jazycích. GoPay tak umožňuje používat platební bránu i pro zahraniční zákazníky.

Bohužel, WordPress nemá v sobě zakomponovaný mechanismus pro změnu jazyka webu. Proto se na toto používají různé doplňkové pluginy.

Ty sice umožňují mít vícejazyčný web a většinou spolupracují s WooCommerce, ale protože je jich více, není vždy možné zjistit, v jakém jazyce je přepnutý e-shop ve chvíli, kdy je uskutečněna objednávka.

U většiny pluginů je možné zjistit aktuální jazyk a dle toho upravit i jazyk vyvolaného dialogu pro GoPay. Pro tento případ je v pluginu připraven filtr, s názvem gopay_inline_default_lang. Ten přijímá argumenty $default_lang a $order.

Defaultní jazyk platební brány je stanovován následovně:

• Zkontroluje se nastavení pluginu a pokud není nastaven výchozí jazyk, je označen jako CS.
• Následně se zkontroluje země zákazníka a pro GB, PL, SK, DE a RU se nastaví odpovídající jazyk. Pokud je země jiná, použije se v prvním kroku nastavený výchozí jazyk.
• V posledním kroku se vrací nastavený jazyk, přes výše zmíněný filtr gopay_inline_default_lang

Kód funkce pro stanovení jazyka:

function gopay_inline_get_lang( $order, $order_meta ){

$country = $order_meta[‚_billing_country‘][0];
$option = get_option( ‚woo_gopay_inline‘ );
if( !empty( $option[‚default-lang‘]) && $option[‚default-lang‘] != ‚-‚ ){
$default_lang = $option[‚default-lang‘];
}else{
$default_lang = ‚CS‘;
}

if( $country == ‚CZ‘ ){ $lang = ‚CS‘; }
elseif( $country == ‚GB‘ ){ $lang = ‚EN‘; }
elseif( $country == ‚SK‘ ){ $lang = ‚SK‘; }
elseif( $country == ‚DE‘ ){ $lang = ‚DE‘; }
elseif( $country == ‚RU‘ ){ $lang = ‚RU‘; }
elseif( $country == ‚PL‘ ){ $lang = ‚PL‘; }
else{
//Get default language
$lang = $default_lang;
}

return apply_filters( ‚gopay_inline_default_lang‘, $lang, $order );
}

Ovlivnění jazyka pomocí vlastní funkce

Jazyk platební brány můžete ovlivnit právě pomocí filtru v posledním kroku.

Do pluginu, nebo do functions.php aktivní šablony vložte funkci:

// Custom filter from payment Gateway developers
add_filter( 'gopay_inline_default_lang', 'gopay_create_payment_lang' );
function gopay_create_payment_lang(){
return 'EN';
}
// End of custom filter from payment Gateway developers

Nyní bude vaše platební brána vždy v angličtině. V případě, že chcete zobrazovat dialog podle zvoleného jazyka, musíte kód funkce upravit tak, aby reflektovala aktuální jazyk. Což je ale již záležitost použitého pluginu.

Filtr pro změnu čísla objednávky v GoPay

V případě, že potřebujete manipulovat s číslem objednávky, jež je odesláno do systému GoPay, můžete využít filtr „gopay_inline_invoice_number“

$gopay_invoice = apply_filters( ‚gopay_inline_invoice_number‘, $order_id );

Filtr pro jazyk platební brány

apply_filters( ‚gopay_inline_default_lang‘, $lang, $order );

Změna jazyka brány pomocí filtru

Přestože se snažíme co nejvíce usnadnit používání pluginu, není možné být připraven na všechny možnosti, které WordPress nabízí.

Proto plugin obsahuje filtr, pomocí kterého je možné změnit nastavení jazyka platební brány.

Pomocí následující funkce, kterou můžete vložit do functions.php a změnit jazyk brány. Příklad je pro WPML.

add_filter( 'gopay_create_payment_lang', 'my_custom_gopay_function' );
function my_custom_gopay_function( $lang ){
    //Získáme aktuální jazyk
    $current_lang = ICL_LANGUAGE_CODE;
    if( $current_lang == 'en' ){
        return 'EN';
    }else{
        return 'CS';
    }
}

Tato funkce pro zvolenou angličtinu, nastaví dialog platební brány na angličtinu. Pro jiné jazyky bude brána v češtině.

Změna klientských údajů pomocí filtru

Klientskými údaji jsou myšleny GoID, ClientID a Client secret. 

Tyto údaje slouží k navázání spojení s GoPay. Pomocí filtrů můžete ovlivnit jejich volání a můžete je změnit. Je tak možné, mít několik účtů na GoPay a podle předem definovaných podmínek tyto účty přepínat. 

My si ukážeme, jak změnit údaje podle toho, jaká dopravní metoda byla použita v objednávce. 

Samotná definice filtrů vypadá takto:

$client_id = apply_filters( ‚gopay_inline_client_id‘, $client_id, $order_id );
$client_secret = apply_filters( ‚gopay_inline_client_secret‘, $client_secret, $order_id );
$goid = apply_filters( ‚gopay_inline_goid‘, $goid, $order_id );

Každý z filtrů kromě hodnoty, obsahuje i id objednávky. Pomoci id objednávky pak můžete získat objekt objednávky a řešit různé případy a podmínky. 

Příklad je psaný na zjištění id dopravní metody, avšak, pokud použijete stejnou dopravní metodu vícekrát, musíte zjistit i její instance, pomocí $shipping->get_instance_id();

<?php

add_filter( 'gopay_inline_client_id', 'toret_change_client_id', 10, 2 );
function toret_change_client_id( $client_id, $order_id ){

    $order = wc_get_order( $order_id );
    $shipping = $order->get_items( 'shipping' );
    $shipping = array_shift( $shipping );
  
    if( $shipping->get_method_id() == 'flat_rate' ){
      return 'my_custom_client_id';
    }
  
    return $client_id;

}

add_filter( 'gopay_inline_client_secret', 'toret_change_client_secret', 10, 2 );
function toret_change_client_secret( $client_secret, $order_id ){

    $order = wc_get_order( $order_id );
    $shipping = $order->get_items( 'shipping' );
    $shipping = array_shift( $shipping );
  
    if( $shipping->get_method_id() == 'flat_rate' ){
      return 'my_custom_client_secret';
    }
  
    return $client_secret;

}

add_filter( 'gopay_inline_goid', 'toret_change_goid', 10, 2 );
function toret_change_goid( $goid, $order_id ){

    $order = wc_get_order( $order_id );
    $shipping = $order->get_items( 'shipping' );
    $shipping = array_shift( $shipping );
  
    if( $shipping->get_method_id() == 'flat_rate' ){
      return 'my_custom_goid';
    }
  
    return $goid;

}

Změna stavu objednávky u zaplacené transakce

Plugin při zaplacení transakce uvede objednávku do stavu completed a nebo processing. To podle toho, zda se jedná o virtuální produkt ke stažení (completed), nebo ne (processing).

Protože to není vždy žádoucí, obsahuje plugin filtry, které to dokáží ovlivnit. Defince filtrů vypadá takto:

$set_status = apply_filters( „gopay_notify_virtual_product_status“, $status, $order );
$set_status = apply_filters( „gopay_notify_normal_product_status“, $status, $order );

Každý z filtrů kromě hodnoty, obsahuje i objekt objednávky. Pomocí objednávky pak můžete řešit různé případy a podmínky.

Příklad filtru pro fyzické produkty:

add_filter("gopay_notify_normal_product_status", "toret_gopay_custom_paid_status", 10, 2 );

if ( !function_exists( "toret_gopay_custom_paid_status") ) {

function toret_gopay_custom_paid_status( $status, $order ) {

return "completed";

}

}

Příklad filtru pro virtuální produkty:

add_filter("gopay_notify_virtual_product_status", "toret_gopay_custom_paid_status", 10, 2 );

if ( !function_exists( "toret_gopay_custom_paid_status") ) {

function toret_gopay_custom_paid_status( $status, $order ) {

return "processing";

}

}

Filtr vložíte do child šablony, function PHP nebo do vlastního pluginu např. Toret Boilerplate.

Změna stavu objednávky pro zrušenou nebo neplatnou platbu

V případě, že nechcete u zrušené nebo neplatné platby používat výchozí stav Cancelled, můžete si pomocí filtru upravit stav na vlastní.

add_filter( 'gopay_notify_payment_canceled', 'toret_gopay_set_completed', 10, 2 );

function toret_gopay_set_completed( $status, $order ){
return ‚completed‘;
}

Místo „completed“ si pak vložte jakýkoliv jiný stav objednávky.

Filtr pro přidání popisku k jednotlivé platební metodě

V případě, že chcete k jednotlivým platebním metodám z pluginu GoPay přidat popisek, je možné jej přidat pomocí filtru.

Příklad filtru:

add_filter('toret_gopay_select_description', 'toret_custom_description', 10, 3);

if( !function_exists( 'toret_custom_description' ) ){

function toret_custom_description( $text, $BankId, $ItemName ){

if( $BankId == 'PAYMENT_CARD' ){

$text = 'Card Description';

}

if( $ItemName == 'Platba 24' ){

$text = 'Platba 24 Description';

}

return $text;

}

}

V příkladu je přidán popisek pro platební metodu Platební karty a Platba 24. Pokud chcete přidat popisek pro jiné platební metody, tak je nutné je ve filtru definovat. Popisek je nutné nastylovat.

Časté dotazy

Debugování chyb

Vzhledem k tomu, že se vždy může něco pokazit, má plugin vestavěný způsob zachytávání chyb.

V detailu objednávky, kde se vyskytla chyba, najdete v pravém horním rohu GoPay Inline Log, který se vztahuje pouze na konkrétní otevřenou objednávku.

V přehledu pluginů od Toretu najdete GoPay Inline log, který obsahuje všechny objednávky najednou.

Bohužel vaše objednávka nemůže být zpracována, protože vaše banka/obchodník odmítl transakci. Zkuste platbu provést později, nebo vyberte jinou platební metodu.

Hláška znamená, že Váš účet ještě nebyl schválen ze strany GoPay po platbu kartou. Kontaktujte podporu GoPay.

Jak získat GOID a secure key

Aby jste mohli využívat platební bránu GoPay, musíte mít podepsanou smlouvu s poskytovatelem. Následně emailem obdržíte GoID a Secure Key, které zadáte do příslušných polí nastavení GoPay platby.

Co je testovací provoz

Po aktivaci platební brány, dostáváte od GoPay přístup k testovacímu serveru. Před tím, než vám bude umožněno platit pomocí GoPay, je nutné ověřit správnost implementace. K tomu se využívá testovací prostředí.

Chyba: IOException: Read timed out – Potíže doručovat HTTP notifikace o změně stavu platby

Notifikační url, je adresa, kam vám bude GoPay zasílat změny stavu plateb. Url si plugin nastavuje sám, v případě nutnosti stačí podpoře GoPay sdělit, že používáte plugin, jenž využívá Rest API a notifikační url není třeba zadávat.

Kde je nastavení plateb pomocí GoPay

Nastavení platební brány najdete v administraci WordPressu -> Eshop WooCommerce -> Nastavení -> Pokladna -> GoPay. Zde musíte správně vyplnit formulář s údaji pro platební bránu.

Kam vložit licenční klíč

Licenční klíč, který jste obdrželi při koupi pluginu, vložte do formuláře v administraci WordPressu-> Nastavení -> WooCommerce GoPay. Po jeho ověření bude platební metoda přístupná v nastavení eshopu.

Co znamená výběr platební metody

GoPay umožňuje platit více způsoby, než pouze kartou. Pro umožnění výběru dalších možností, si v administraci nadefinujete všechny způsoby, které chcete povolit. Například, když nepoužíváte SuperCash, v nastavení pluginu ho nepřidáte.

Chyba GoPay platby: Scope je prázdné, kontaktujte podporu pluginu

Chyba GoPay platby: Scope je prázdné, kontaktujte podporu pluginu je často doprovázena chybou O:19:“GoPay\Http\Response“:3:{s:28:“GoPay\Http\ResponserawBody“;s:63:“SSL certificate problem: unable to get local issuer certificate“;s:10:“statusCode“;i:500;s:4:“json“;a:0:{}}

Problém je na straně hostingu, kde není na serveru nový kořenový certifikát.

Po kliknutí na objednat se neotevře okno pro platbu, ale rovnou se zobrazí děkovná stránka

Řešení 1

Na stránce pokladny není aktivní https, GoPay Inline vyžaduje pro své fungování aktivní https. Pokud jej nepoužíváte, doporučujeme na něj přejít nejen na stránce pokladny, ale i na celém webu.

Řešení 2

Nejsou zadány odpovídající údaje go GoPay. Pokud jsou zadány s překlepem, nebo testovací údaje nemají zaškrtnutý test, nedojde k vyvolání platební brány. Zkontrolujte, zda máte vložené správné údaje.

Řešení 3

Na e-hopu máte jen jednu sazbu daně, nebo žádnou a v nastavení pluginu je zaškrtnuto EET. V případě, že nepoužíváte více sazeb pro DPH, není třeba zasílat údaje o základech daňových sazeb na GoPay. Celé nastavení zvládnete z účtu GoPay a v pluginu tuto volbu vypněte.

Nezobrazuje se výběr platebních metod

Přestože máte v nastavení GoPay povoleno více platebních metod, stále se zobrazuje jen hlavní, bez možnosti výběru, například PayPalu.

Řešení:

Zkontrolujte, zda máte vyplněný popis platby. Výběr platebních metodu používá rozšíření popisu platební metody.

Pokud nebudete popis používat, je do něj nutné vložit minimálně mezeru. Pak se výběr platebních metod zobrazí.

SCOPE je prázdné

Ujistěte se prosím, že na serveru máte zakázaný open_basedir, se kterým není kompatibilní nastavení
API CURLOPT_FOLLOWLOCATION. Pokud je open_basedir aktivní, je třeba ho deaktivovat, nebo upravit kód api.
Pokud budete upravovat api, tak je nutné otevřít soubor vendor/mashape/unirest-php/src/Unirest/Request.php,
vyhledat CURLOPT_FOLLOWLOCATION a změnit hodnotu na false.
Na api v současné době nejsou žádné redirecty, proto by neměl být problém využívat SDK s deaktivovaným CURLOPT_FOLLOWLOCATION.

Zdvojené faktury a zdvojené odečítání ze skladu

GoPay požaduje o nastavení limitu pro HTTP notifikace do 15 vteřin a tedy jsou v pluginu nastaveny hodnoty pro správné odeslání notifikací.

Může se stát , že GoPay odešle najednou dvě odpovědi, jedna se vrací se zákazníkem na e-shop a druhou odesílá GoPay sám. GoPay je schopný poslat notifikace najednou, tedy rozdílem jsou tisíciny vteřiny. Z tohoto důvodu se může stát, že se skript spustí 2x. Na tento problém nefungují žádné zámky, hlídáčky apod., a může dojít k duplicitním fakturám nebo dvojímu odečtení ze skladu.

Pokud by plugin vystavoval faktury duplicitně, nebo více odečítal ze skladu, použijte následující filtr pro nastavení delší notifikace.

function gopay_sec_count_fce() {
return 20;
}
add_filter( 'gopay_sec_count', 'gopay_sec_count_fce', 10, 0 );

V pokladně se nezobrazují loga a checkboxy platebních metod

Pokud v pokladně u jednotlivých platebních metod nejsou vidět loga a zaškrtávací checkboxy, tak je blokuje šablona.

Problém má snadně řešení úpravou v CSS.

Do vlastního CSS vložte níže uvedenou úpravu:

.gopay_select input[type=“radio“] {display:initial!important;} /zobrazí zaškrtávací kolečka/
.gopay_select img {display:initial!important;} /zobrazí loga/

Úprava zobrazení log v blokové pokladně

Ve výchozím nastavení se zobrazuje logo nad názvem platební metody. V případě, že chcete mít logo vlevo od textu, můžete to udělat tak, že přidáte níže uvedené CSS.

.wc-block-components-checkout-step__content .wc-block-components-radio-control__label-group >span > span {
	display:flex;
}

.wc-block-components-checkout-step__content .wc-block-components-radio-control__label-group >span > span img {
	margin-right:5px;
}