Postup integrace platební brány

Č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ším 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ístem 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 pomoci 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:

<form id="payment-form" action="/create-payment" method="POST">
  <label for="payment-amount">Částka: </label>
  <input type="number" name="amount" id="payment-amount" />
  <button type="submit">Zaplatit Inline</button>
</form>

// Po odeslání formuláře dojde k asynchronnímu založení platby a následnému vyvolání inline brány
document.addEventListener("DOMContentLoaded", () => {
  const paymentForm = document.querySelector("#payment-form");
  paymentForm.addEventListener("submit", async (event) => {
    event.preventDefault();
    const createResult = await createPayment(paymentForm);
    initInline(createResult);
  });
});

// Asynchronní funkce pro vytvoření platby z formuláře
const createPayment = async (form) => {
  try {
    //serializace dat z formuláře jako JSON
    const formData = new FormData(form);
    const formObject = Object.fromEntries(formData.entries());
    // Odeslání dat na endpoint, specifikovaný jako akce formuláře.
    const createResponse = await fetch(form.action, {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(formObject)
    });
    // Předpokládáme, že backend vrací JSON, který obsahuje popis platby z API odpovědi
    // viz https://doc.gopay.cz/#zalozeni-platby
    const createResult = await createResponse.json();
    if (!createResponse.ok) {
      console.error(
        `Server returned: ${createResponse.status}: ${createResponse.statusText}:\n${createResult}`
      );
      return;
    }
    return createResult;
  } catch (err) {
    console.error(err);
  }
};

// Asynchronní funkce pro provedení dotazu na stav platby podle jejího ID
const getPaymentStatus = async (paymentId) => {
  try {
    // ID platby je v příkladu předáno jako query parametr "id". Upravte podle vašich potřeb.
    const statusResponse = await fetch(`/payment-status?id=${paymentId}`, {
      method: "GET",
      headers: {
        Accept: "application/json"
      }
    });
    // Předpokládáme, že backend vrací JSON, který obsahuje popis platby z API odpovědi
    // viz https://doc.gopay.cz/#dotaz-na-stav-platby
    const paymentStatusResult = await statusResponse.json();
    if (!statusResponse.ok) {
      console.error(
        `Server returned: ${statusResponse.status}: ${statusResponse.statusText}:\n${paymentStatus}`
      );
      return;
    }
    return paymentStatusResult;
  } catch (err) {
    console.error(err);
  }
};

// Funkce, pro vyvolání inline brány
const initInline = (createResult) => {
  try {
    // Vyvolání Inline brány prostřednictvím získané gw_url
    // Jako druhý parametr je předána callback funkce, která je volána při zavření brány
    _gopay.checkout({ gatewayUrl: createResult.gw_url, inline: true }, async (checkoutResult) => {
      // V objektu checkoutResult se nachází návratová URL, ID platby a její stav
      console.log(`Stav platby ${checkoutResult.id}: ${checkoutResult.state}`);
      // Pro další informace o platbě je možné zavolat dotaz na stav platby.
      const paymentStatusResult = await getPaymentStatus(checkoutResult.id);
      // A následně odpověď libovolně zpracovat
      console.log(paymentStatusResult);
    });
  } catch (err) {
    console.error(err);
  }
};

Návrat z platební brány

Po 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á byla definována 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}, (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 (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. 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.