Článek popisuje všechny potřebné kroky pro integrování nové GoPay platební brány. Najdete zde vše potřebné pro co nejrychlejší integraci online plateb do vašeho prodejního místa.

OAuth

Rozhraní platební brány využívá pro komunikaci REST API. Komunikace probíhá pomocí HTTPS požadavků. Zabezpečení přístupu k API je zajištěno otevřeným bezpečným protokolem OAuth2.0.

OAuth protokol umožňuje získávat různé stupně oprávnění pro přístup k jednotlivým funkcionalitám API. Komunikace probíhá na základě tzv. tokenů. Na začátku integrace od nás obdržíte údaje ClientID a ClientSecret, které slouží k vytváření potřebných tokenů.

Tip GoPay:
V případě, že jste údaje ClientID a ClientSecret ještě neobdrželi, kontaktujte nás, prosím, na e-mailu integrace@gopay.cz.

Prvním krokem před vytvořením platby je tedy vytvoření tokenu, který následně zasíláte s každým požadavkem na API. Token je předáván v hlavičce https požadavku.

Token získáte pomocí volání API na URL /api/oauth2/token. Token je možné vytvořit ve dvou množinách získaných práv, a to payment-create, který slouží pouze pro zakládání plateb a dále payment-all pro všechny další platební operace. Získaný token má životnost 30 minut a je ho nutné předávat v hlavičce každého požadavku na API.

Tip GoPay:
API pro testovací prostředí se nachází na adrese https://gw.sandbox.gopay.com/api/
Provozní prostředí je dostupné na adrese https://gate.gopay.cz/api/

Založení platby

Další krokem pro provedení platby je její založení. Platba je založena voláním na URL /api/payments/payment GoPay REST API. Při založení platby jsou specifikovány všechny její parametry jako jsou cena, měna platby, povolené platební metody, předvybraná platební metoda, položky objednávky, jazyk platební brány, adresy pro notifikace a adresy pro návrat na prodejní místo. Více informací najdete v popisu standardní platby.

Pro úspěšné provedení požadavku je nutné v hlavičce předat dříve založený token, který nás opravňuje k provedení požadované operace.

Jako výsledek volání je vrácen JSON objekt, který obsahuje všechny informace o platbě. Z těchto informací je nejdůležitější parametr id, což je jedinečný identifikátor platby v systému GoPay. ID platby je potřeba si uložit do databáze k objednávce k níž platba náleží. ID je využito pro následné úspěšné zpracování návratu z platební brány, případně http notifikace. Dalším důležitým parametrem je gw_url, kterou využijeme v následujícím kroku pro vyvolání platební brány.

Vyvolání platební brány

Platební bránu je možné vyvolat buď ve variantě inline, kdy platba probíhá přímo nad prodejním místě obchodníka, nebo ve variantě redirect, kdy dojde k přesměrování na doménu gopay.cz. Oba tyto způsoby si můžete otestovat na našem ukázkovém obchodu https://www.goshop.cz. Dále je možné si vybrat ze dvou způsobů vyvolání platební brány -  předzaložení platby, nebo inicializace pomocí javascriptu. Předzaložení platby se více hodí pro vícekrokový košík, zatímco incializace pomocí javascriptu je vhodná pro platbu na jedno potvrzení.

Předzaložení platby

Tento způsob je vhodný pro vícekrokový košík, kdy se po potvrzení objednávky na serveru založí platba a následně se zákazníkovi zobrazí formulář směřující na gw_url pro vyvolání platební brány, a to buď ve formě inline nebo redirect. Po odeslání formuláře je vyvolána platební brána.

Inicializace pomocí javascriptu

Druhým způsobem je vyvolání platební brány za pomocí javascriptového volání. V okamžiku potvrzení objednávky je proveden ajaxový request na váš server. Server provede získání tokenu a následně založení platby. Jako odpověď vrátí gw_url založené platby. Jakmile získáte gw_url, provedete vyvolání platební brány pomocí metody:

 _gopay.checkout({gatewayUrl: url, inline: true});

Metoda je parametrizována objektem, který obsahuje gatewayUrl založené platby a parametr inline, který říká, zda bude platební brána vyvolána ve variantě inline, nebo redirect. Pro použití metody _gopay.checkout je nutné vložit GoPay javascriptové API:

Testovací prostředí

 <script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js">

Provozní prostředí

<script type="text/javascript" src="https://gate.gopay.cz/gp-gw/js/embed.js">

Níže naleznete příklad vyvolání platební brány pomocí javascriptu:

<body>
<script type="text/javascript" src="https://gw.sandbox.gopay.com/gp-gw/js/embed.js"></script>
<h3>Inline-gw</h3>
<script type="text/javascript">         
   $( document ).ready(function() {
       //handluje eventu pro provedeni platby
       $( '#payment-invoke-checkout' ).on( 'click', function( event ) {
           event.preventDefault();
           postParams = $('#payment-container').serialize();
           //platbu zakladame asynchronnim volanim ze serverove strany (kde nejprve ziskavame 'access token', nasledne 'zakladame platbu')
           $.ajax({
               url: '/eshop/create-payment',
               type: 'POST',
               data: postParams

           }).done(function( inlineCreateResult ) {
               //predpokladejme, ze volani zalozeni platby vraci inlineCreateResult, ktery obsahuje url (gw_url ze zalozeni platby)
               //pomoci .js API startujeme embed platebni branu
               _gopay.checkout({gatewayUrl: inlineCreateResult.gw_url, inline: true}, function(checkoutResult) {

                   //uzavreni embedu muzeme odchytavat callbackem
                   //callbacku je pri uzavreni predavan objekt checkoutResult, ktery obsahuje vlastnost id a url (return-url)
                   //!! je nutne pocitat i s variantou navratu z platebniho procesu na returnURL!! (platebni tlacitka)

                   //dalsim volanim dotazujeme stav platby a zobrazujeme vysledek                          
                   $.ajax({
                       url: '/eshop/get-payment-status',
                       type: 'POST',
                       data: {inlineGetState: null, eshopGoId: $(actionBean.eshop.eshopGoId), paymentId: checkoutResult.id}    

                   }).done(function( inlineGetStateResult ) {
                       $("#payment-container").prepend("<p style='background-color:yellow;padding:8px;border:solid black 1px'>Stav platby: " + inlineGetStateResult.state + "<br><br>URL: <a href='" + checkoutResult.url + "'>" + checkoutResult.url + "</a></p>")                                
                   });
               });

           }).error(function(data) {
               alert('error' + data);
           });
       });
   });         
</script>

<form id="payment-container" action="/eshop/create-payment">
   <input type="hidden" name="order_id" value="123"/>
   <button id="payment-invoke-checkout" type="submit" name="pay">Zaplatit</button>
</form>

Návrat z platební brány

Pro provedení nebo zrušení platby je zákazník navrácen zpět na prodejní místo. Návrat je možné provést dvěma způsoby. První z nich je provedení přesměrování na return_url, které bylo definováno při založení platby. Druhá možnost spočívá v zavolání callback funkce, která byla předána jako další parametr pro _gopay.checkout. V takovém případě nedochází k žádnému přesměrování. Callback funkci je, ale možné vyvolat pouze v případech, že zákazník pro provedení platby nebyl přesměrován mimo platební bránu. V opačném případě probíhá standardní přesměrování na return_url.

Návrat přes návratovou URL

Při založení platby je v objektu callback předán parametr return_url. Po provedení platby je zákazník přesměrován na tuto URL. Za return_url je platební bránou připojen GET parametr ?id=<id_platby>. Pomocí získaného id dokážete jednoduše identifikovat, o jakého zákazníka se jedná. Dále je nutné pomocí , id provést dotaz na stav platby a zákazníkovi zobrazit informaci o aktuálním stavu.

Návrat pomocí callback funkce

Druhou možností je neprovádět přesměrování na return_url. Platební brána může u platebních metod, u kterých nedochází k přesměrování z platební brány (například platba kartou) pouze zavolat vámi definovanou funkci, kterou předáte jako součást vyvolání platební brány pomocí _gopay.checkout. Volání může tedy vypadat následovně:

 _gopay.checkout({gatewayUrl: inlineCreateResult.url, inline: true}, function(checkoutResult) { alert(checkoutResult);})

 Po platbě bude tedy vyvolána vámi definovaná funkce. Ve funkci doporučujeme provést ajaxový request na váš server, který ověří stav platby. Na základě stavu platby zákazníkovi zobrazte příslušnou informaci o provedení platby.

    

I v případě využití callbackové funkce je nutné počítat s return_url. U některých platebních metod, například online bankovních tlačítek, dochází k přesměrování mimo platební bránu a callback funkci tedy není možné vyvolat. V těchto případech dochází vždy k návratu na return_url.

Notifikace

Notifikace zajišťuje automatické informování prodejního místa o jakékoli změně stavu platby.    

Jako součást objektu callback při založení platby je předáván parametr notification_url. Na tuto URL zasíláme v případě jakékoli změny stavu platby asynchronní HTTP/GET notifikaci. Notifikace je volána ve formátu http://eshop.tld?id=<id_platby>.
Pomocí GET parametru id si v databázi vyhledáte příslušnou objednávku a provedete dotaz na stav platby, který vám sdělí její aktuální stav. Stav uložíte do databáze k objednávce, případně provedete vámi definované akce pro konkrétní stav, např. uhrazení platby.

SSL certifikát

Pro využití inline platební brány na prodejních místech je nutné mít SSL certifikát od certifikační autority (podpora HTTPS). Na prodejních místech, které SSL certifikát nemají,
dojde standardně k vyvolání redirect varianty popisované níže.

Redirect varianta je alternativním řešením, které odvede zákazníka z prostředí prodejního místa na zabezpečené prostředí platební brány GoPay s nejdůvěryhodnějším EV (rozšířené ověření) certifikátem. Pro menší zákazníky, kteří nemají potenciál zřízení SSL certifikátu, doporučujeme použití této redirect varianty platební brány.