Tato dokumentace obsahuje průvodce integrací platební brány GoPay a REST API referenci. K integraci můžete použít také jednu z námi nabízených knihoven.

PHP

• PHP >= 8.1
• GitHub: https://github.com/gopaycommunity/gopay-php-api
• Packagist: https://packagist.org/packages/gopay/payments-sdk-php
• Instalace: composer require gopay/payments-sdk-php

Python

• Python >= 3.6
• GitHub: https://github.com/gopaycommunity/gopay-python-api
• PyPi: https://pypi.org/project/gopay/
• Instalace: pip install gopay

.NET (C#)

• .NET Standard >= 2.0
• GitHub: https://github.com/gopaycommunity/gopay-dotnet-api
• NuGet: https://www.nuget.org/packages/GoPay.NET
• Instalace: dotnet add package GoPay.NET

Java

• Java >= 11
• GitHub: https://github.com/gopaycommunity/gopay-java-api.git
• Maven: https://mvnrepository.com/artifact/cz.gopay
• Instalace:

git clone https://github.com/gopaycommunity/gopay-java-api.git
cd gopay-java-api
mvn package

Prvním krokem k vytvoření platby je získání tokenu. Toto je provedeno pomocí API volání v rámci REST API. U některých software knihoven je token získán automaticky při inicializaci.

Dalším krokem je samotné založení platby. Toto je provedeno pomocí API volání pro založení platby, v němž předáte parametry platby a údaje o zákazníkovi. Dále předáte return_url, na kterou bude zákazník přesměrován zpět z brány, a notification_url na kterou bude zaslána HTTP notifikace. K oběma bude v query parametru přidáno ID platby. Také zde určíte, jaké platební metody budou pro platbu k dispozici - viz sekce Nastavení platebních metod.

Na API volání je jako odpověď vrácen JSON, který obsahuje dvě důležité informace:

• ID platby - v parametru id, což je jedinečný identifikátor platby v rámci systému GoPay. Pomocí něj lze provádět dotaz na stav platby.
• URL platební brány - v parametru gw_url - pomocí této URL lze zákazníka přesměrovat na platební bránu nebo vyvolat inline bránu.

Dále v závislosti na typu platby může odpověď obsahovat další informace. Detailní popisy pro založení jednotlivých druhů plateb naleznete v samostatné sekci Platby.

Pomocí získané gw_url je možné vyvolat platební bránu, která může být v jedné ze 3 verzí

• Redirect varianta. Na získanou gw_url zákazníka přesměrujete (např. HTTP redirectem, HTML formulářem apod.) Zákazník opustí e-shop a přejde na zabezpečené prostředí GoPay platební brány pod doménou gate.gopay.cz.
• Inline varianta. Je potřeba implementovat JavaScriptem na straně eshopu. Eshop se musí nacházet na doméně s HTTPS zabezpečením. Zákazník není přesměrován z eshopu, platební brána se otevře přes něj jako overlay. Pokud v některém kroku platby dojde k přesměrování na stránky třetí strany (online banking, 3DS), vrátí se zákazník na bránu ve variantě Redirect. Ukázky a detailnější popis platební brány naleznete v našem centru nápovědy v článku Co je inline platební brána?.
• Mobilní varianta. Na mobilních zařízeních je vždy vyvolána mobilní verze redirect brány, i pokud máte v eshopu implementovanou inline variantu. Mobilní brána je optimalizována pro zobrazení a ovládání na mobilních zařízeních.

Detailní informace k vyvolání platební brány a návod, jak implementovat Inline variantu, naleznete v sekci Vyvolání platební brány

Na platební bráně má zákazník na výběr platební metody, které byly povoleny při Založení platby. Zákazníkovi se zobrazí buďto seznam platebních metod, nebo lze jednu předvybrat. Bližší informace jsou v sekci Nastavení platebních metod.

Dále má zákazník možnost platební bránu zavřít křížkem. Tím je přesměrován zpět na návratovou URL, aniž by proběhl pokus o uhrazení platby. Platba v tomto případě zůstává ve stavu CREATED.

V okamžiku, kdy se zákazník pokusí platbu uhradit tlačítkem pro potvrzení platby (může na něm být Zaplatit, či jiná textace), přiřadí se k platbě platební metoda a stav platby se změní na PAYMENT_METHOD_CHOSEN. Pokud se zákazník nachází např. na formuláři se zadáním čísla karty, ale ještě neklikl na tlačítko Zaplatit, není platební metoda vybrána.

Poté, co je platební metoda zvolena, dojde k autorizaci platby. Pro každou platební metodu se tento proces může lišit. Výsledkem může být jedna z těchto situací:

• Platba je uhrazena. Autorizace dopadla úspěšně a částka platby je připsána na GoPay účet obchodníka. Platba je ve stavu PAID (popřípadě AUTHORIZED u předautorizací).
• Platba je zamítnuta. V některém bodu došlo k zamítnutí platby ze strany partnera (např. banka nebo 3DS centrum zákazníka). Platba je ve stavu CANCELED.
• Zatím neznáme výsledek platby. Nemáme od protistrany ještě výsledek o tom, jak platba dopadla. Toto může přetrvávat i poté, co se zákazník vrátí do eshopu. Jakmile bude výsledek znám, bude k platbě odeslána notifikace.

Pokud je platba v některém z těchto stavů, již není možné měnit platební metodu, ani se k ní vrátit.

Zákazník je přesměrován zpět na eshop poté, co dokončí platbu. Bránu může také zavřít sám a tím dojde k návratu na eshop. Přesměrován je na return_url, která byla předána při založení platby. K URL jsou připojeny query parametry:

• id - obsahuje ID platby, podle kterého lze dotázat její stav
• parent_id - pouze u opakované platby - obsahuje ID zakládající platby

Pomocí parametrů eshop provede dotaz na stav platby a zákazníka o výsledku informuje.

Pokud dojde ke změně stavu platby, je odeslána HTTP notifikace. Skládá se z notification_url, která byla předána při založení platby. K URL jsou připojeny query parametry:

• id - obsahuje ID platby, podle kterého lze dotázat její stav
• parent_id - pouze u opakované platby - obsahuje ID zakládající platby

Na tuto URL je odeslán HTTP GET request. Pouze u změny stavu platby z CREATED na PAYMENT_METHOD_CHOSEN k odeslání notifikace nedochází. Notifikace informace o stavu platby nenese, pouze id. Stav je potřeba ověřit pomocí API volání. Stav platby se může změnit vícekrát (např. jednou při zaplacení na PAID a později při refundaci na REFUNDED).

Platba může mít následující stavy:

• CREATED - platba vytvořena
• PAYMENT_METHOD_CHOSEN - čeká se na výsledek platby
• TIMEOUTED - životnost platby vypršela
• PAID - platba byla uhrazena
• CANCELED - platba byla zamítnuta
• AUTHORIZED - platba byla předautorizována
• PARTIALLY_REFUNDED - část platby byla refundována
• REFUNDED - celá platba byla refundována

Proces platby má 2 životnosti:

• Životnost 1 - od vytvoření platby po potvrzení platební metody na bráně - vždy stejná pro každou platbu ve stavu CREATED
• Životnost 2 - od potvrzení platební metody na bráně po výsledek / koncový stav platby - liší se pro jednotlivé platební metody

Pokud do vypršení první životnosti nedojde k pokusu platbu uhradit, nastane stav TIMEOUTED. Pokud do vypršení druhé životnosti není znám výsledek platby, také nastane stav TIMEOUTED.

K založení standardní platby využijete API volání pro založení platby. Stačí předat pouze povinné parametry requestu. U standardní platby je vždy potřeba její autorizace ze strany zákazníka.

Všechny ostatní typy plateb jsou zakládány stejným API voláním, které je obohacené o dodatečné parametry.

Všechny typy plateb lze navzájem kombinovat. Platba tedy může být například opakovatelná na vyžádání a předautorizovaná současně.

Příklady pro všechna SDKs a podrobný popis API volání naleznete v sekci Založení platby.

Automatická opakovaná platba je založena API voláním pro založení platby. V requestu je předán objekt recurrence.

U automatické platby je povinné předat tyto parametry:

• recurrence_cycle určuje cyklus opakované platby, tedy zda opakovaná platba bude prováděna každý Xtý den, týden či měsíc. Nabývá hodnot uvedených v číselníku Recurrence cycle.
• recurrence_period určuje periodu opakování platby (nikoliv frekvenci), tedy kolik dnů, týdnů či měsíců má uplynout mezi dvěma platbami.
• recurrence_date_to určuje platnost opakované platby. Do tohoto data ji bude systém platební brány automaticky strhávat. Hodnota musí být vyšší než aktuální datum a vyšší než poslední den, kdy se má platba strhnout.

Ve objektu se určuje perioda, nikoliv frekvence. Příklad:

{
    "recurrence_cycle": "MONTH",
    "recurrence_period": 2,
    "recurrence_date_to": "2025-12-31"
}

S tímto voláním bude opakovaná platba provedena jednou za 2 měsíce, nikoliv 2x měsíčně.

Pokud si přejete platby opakovat ročně, nastavte recurrence_cycle na MONTH a recurrence_period na 12, pak bude opakování probíhat každých 12 měsíců, tedy jednou ročně

Následné opakované platby mají stejné parametry jako zakládající platba, nelze tedy měnit např. částku apod. Pokud je následná platba zamítnuta, další pokus o stržení platby proběhne až v následujícím termínu opakování.

Podrobný popis API volání a příklady pro jednotlivé knihovny naleznete v sekci založení standardní platby. U opakované platby je potřeba předat povinný objekt recurrence.

Opakovaná platba na vyžádání je zakládána stejným API voláním, jako automatická a je tedy rovněž potřeba předat povinný objekt recurrence.

V tomto objektu je potřeba předat tyto povinné parametry:

• recurrence_cycle vždy ON_DEMAND
• recurrence_date_to určuje platnost opakované platby. Do tohoto data ji bude systém platební brány strhávat na základě vašich API požadavků. Hodnota musí být vyšší než aktuální datum a vyšší než poslední den, kdy se má platba strhnout.

Parametr recurrence_period se u tohoto druhu opakované platby vůbec nepoužívá. Stržení následných plateb probíhá pomocí k tomu určeného API volání. V něm se zadává částka, ID objednávky a další parametry platby.

V době, kdy je vrácena odpověď na API volání, ještě platba zpravidla nebývá uhrazena. O výsledku platby je možné se informovat pomocí dotazu na stav platby na základě HTTP notifikace, kterou vám zašleme při změně stavu platby.

Příklady pro všechna SDKs a podrobný popis API volání naleznete v sekci Založení platby a Stržení opakované platby.

Zrušení opakované platby je možné následujícími způsoby:

• Ze strany obchodníka pomocí API volání pro zrušení opakované platby
• Ze strany obchodníka prostřednictvím GoPay obchodního účtu
• Ze strany zákazníka prostřednictvím e-mailu se stavem platby, který mu zasíláme
• Ze strany GoPay (zpravidla na žádost zákazníka)
• Automaticky v okamžiku, kdy dojde k vypršení platnosti karty zákazníka
• Automaticky v okamžiku, kdy nastane datum předané jako date_to při založení platby

Pokud se přes API pokusíte zrušit opakování, které již v minulosti zrušené bylo, končí volání chybou s popisem, že opakování již je zrušeno.

Při zrušení opakování platby standardně nedochází k odeslání HTTP notifikace. Pokud si ji přejete v tomto případě dostávat, kontaktujte technickou podporu GoPay.

Příklady pro všechna SDKs a podrobný popis API volání naleznete v sekci Zrušení opakované platby.

V odpovědi na dotaz na stav platby je u mateřské opakovatelné platby vrácen navíc objekt recurrence, který popisuje opakování platby. Ten obsahuje i parametr recurrence_state, který popisuje stav opakování platby. Podle jeho hodnoty lze ověřit, zda k dané zakládající platbě lze provádět následné opakované platby, či nikoliv.

Standardně lze provádět nejvýše jednu následnou opakovanou platbu na vyžádání za kalendární den. Výjímkou je den, kdy je založena mateřská opakovatelná platba, ta se již do tohoto limitu počítá, takže ve stejný den nelze vytvořit následnou opakovanou platbu.

V případě, že opakování nebude úspěšné, budete pravděpodobně chtít provést další pokus platbu strhnout. Takovýto pokus je možné provést nejdříve následující kalendární den, nebo 24 hodin od posledního pokusu. Při pokusu strhnout platbu dříve dojde k zamítnutí pokusu kvůli limitu jednoho opakování denně.

Nedoporučujeme také opakování hned po první neúspěšné opakované platbě rušit. Doporučujeme provést celkem alespoň 3 pokusy v rozmezí nejméně 24h od sebe, než zrušíte opakovanou platbu a zákazníkovi předplacenou službu. Můžete také brát v potaz víkendy a pokusy o opakování provádět pouze v pracovní dny, kdy je větší pravděpodobnost, že zákazníkovi přibydou na účtě chybějící finance.

Před provedením dalšího pokusu o opakování platby vždy nejdříve vyčkejte na obdržení HTTP notifikace k předchozímu pokusu a zkontrolujte jeho stav. Tím se vyhnete možnému duplicitnímu stržení platby. Také doporučujeme rozlišovat mezi situacemi, kdy k vytvoření platby došlo, ale byla následně zamítnutá a situacemi, kdy k vytvoření vůbec nedošlo (vrátil se API error).

Předautorizovaná platba je založena API voláním pro založení platby, ve kterém je potřeba předat parametr preauthorization s hodnotou true. Po založení platby je vrácen objekt popisující její stav a parametry. Průběh autorizace platby je stejný jako u standardní platby, jak je popsáno v sekci Popis vytvoření a průběhu platby.

Poté, co zákazník předautorizovanou platbu dokončí, platba přechází do stavu AUTHORIZED. O změně stavu platby informujeme prodejní místo pomocí automatické HTTP notifikace na notifikační URL adresu předanou při založení platby. V tomto okamžiku je na účtě klienta provedena blokace částky, která zatím není stržena (zaúčtována).

Autorizovanou platbu je možno strhnout dvěma způsoby:

• Stržení platby v plné výši. Využijete k tomu API volání, ve kterém není potřeba předávat žádné parametry. Volání strhne blokaci z účtu zákazníka a finanční prostředky připíše na GoPay obchodní účet obchodníka.
• Částečné stržení. Lze jej provést pomocí API volání pro částečné stržení. V něm je potřeba v parametru amount specifikovat částku platby, která musí být nižší nebo rovna celkové autorizované částce. V případě stržení menší částky, než na kterou byla platba původně autorizována, dochází k aktualizaci údajů původní platby dle nového volání. Zbylá částka je zákazníkovi automaticky uvolněna zpět na platební kartu.

Platba následně přechází do stavu PAID.

Již autorizovanou platbu lze také zrušit prostřednictvím API volání pro zrušení předautorizace. Blokace finančních prostředků na účtu zákazníka je následně uvolněna a platba přechází do stavu CANCELED.

Předautorizovanou platbu lze také založit s nulovou částkou. Proběhne pouze ověření karty, ale nebude blokována žádná částka. To lze zkombinovat např. se zakládající opakovanou platbou (režim ON_DEMAND) pokud chcete nabídnout zkušební období zdarma. Dále lze s iniciační platbou pro vytvoření karetního tokenu, pokud chcete získat token bez toho, abyste zákazníkovi něco účtovali.

Takto založenou platbu nelze strhnout (volání skončí chybou), ale lze ji zrušit.

Kombinace platby s nulovou částkou a zakládající opakované platby není aktuálně podporována Raiffeisenbank! Takovéto platby nelze autorizovat kartami Raiffeisenbank a EQUA bank.

U plateb kartou je možné získávat unikátní otisk karty (tzv. card_fingerprint). Pomocí něj lze porovnat, zda dvě platby byly uhrazeny jednou a tou samou kartou. Pokud je karta použita prostřednictvím Apple Pay nebo Click To Pay, bude se otisk lišit od případu, kdy byla ručně zadána.

Při uložení karty s vyžádáním karetního tokenu (viz Platba karetním tokenem) je card_fingerprint vždy generován.

card_fingerprint bude součástí objektu payment card v dotazu na stav platby.

Funkce vytváření fingerprintu není automaticky aktivní. Pro její aktivaci kontaktuje technickou podporu GoPay.

Pro vytvoření karetního tokenu proveďte standardní založení platby pomocí API volání, kde je v objektu payer potřeba předat v poli request_card_token hodnotu true. V poli allowed_payment_instruments předejte jako jedinou hodnotu PAYMENT_CARD.

Poté, co je uhrazena, provedete dotaz na stav platby. V odpovědi nalezneme objekt payer, který obsahuje card_id. Díky tomuto identifikátoru můžete získat detaily karty včetně tokenu a jeho stavu.

Pomocí k tomu určeného API volání můžete díky hodnotě card_id získat detaily uložené karty.

Detaily obsahují:

• Údaje karty, jako vymaskovaný PAN a expiraci
• card_fingerprint, díky kterému můžete ověřit, zda daná karta již je uložená
• card_token, který můžete použít pro následné platby

Před čtením dalších údajů o kartě vždy nejprve kontrolujte, zda parametr card_status nabývá hodnoty active. Pokud ne, nebude objekt obsahovat další údaje.

Pro použití tokenu založte platbu pomocí standardního API volání. V objektu payer předejte v parametru allowed_card_token dříve získaný card_token. Tím zákazník nebude muset zadávat údaje z karty. 3DS ověření může být stále vyžadováno. V objektu payer také předejte pole allowed_payment_instruments a v něm pouze hodnotu PAYMENT_CARD. To je u tohoto typu platby vyžadováno.

Karta může být smazána ze strany obchodníka a to k tomu určeným API voláním, anebo ze strany GoPay (např. z důvodu nepoužívání). Pokud je karta smazána, změní se card_status na deleted a údaje o kartě již nebudou k dispozici. O změně stavu informujeme pomocí HTTP notifikace.

Pro použití funkce platby tokenem je nutno u GoPay zaregistrovat URL, na kterou budou zasílány HTTP notifikace.

Ty jsou odesílány ve chvíli, kdy:

• Došlo k revokaci tokenu ze strany GoPay nebo obchodníka
• Došlo k aktualizaci údajů o kartě (např. při vypršení platnosti staré karty)

HTTP notifikace je GET požadavek s query parametrem card_idnesoucí dříve získané ID karty.

Například: GET https://example.com/card-notify?card_id=123456

Pomocí ID je pak následně potřeba provést dotaz na detaily karty a ověřit card_status, případně aktualizovat údaje.

Bez předání bankovních údajů

Poté, co zákazník v rámci PSD2 platby udělí souhlas pro GoPay, dojde k vypsání jeho účtů. Zákazník vybere, který účet chce použít a pokračuje k autorizaci platby.

Je použito standardní API volání pro založení platby, kdy je potřeba předat objekt payer tímto způsobem:

• allowed_payment_instruments musí být vždy nastaveno pouze na BANK_ACCOUNT
• allowed_swifts musí vždy být nastaveno na konkrétní banku zákazníka
• pro banku musíte mít zapnuté PSD2 platby

S předáním bankovních údajů

Pokud znáte bankovní údaje zákazníka a chcete získat token k jednomu konkrétnímu účtu, můžete v API předat bankovní údaje. Poté, co zákazník v rámci PSD2 platby udělí souhlas pro GoPay, dojde k načtení jeho účtů. Pokud se žádný účet neshoduje s předanými údaji, platba je zamítnuta. Pokud je nalezena shoda, pokračuje zákazník k autorizaci platby.

Je použito standardní API volání pro založení platby, kdy je potřeba předat objekt payer tímto způsobem:

• allowed_payment_instruments musí být vždy nastaveno pouze na BANK_ACCOUNT
• allowed_swifts musí vždy být nastaveno na konkrétní banku zákazníka
• je potřeba předat objekt bank_account a v něm údaje o účtu zákazníka buďto v českém, nebo v mezinárodním formátu
• pro banku musíte mít zapnuté PSD2 platby

V okamžiku, kdy je první platba uhrazena, dochází standardně k odeslání HTTP notifikace, viz Odeslání notifikace. Z ní získáte ID platby a s jeho pomocí provedete dotaz na stav platby. V odpovědi na tento dotaz je vrácen token účtu jako součást objektu bank_account v objektu payer.

Pro použití tokenu založte platbu pomocí standardního API volání. V objektu payer předejte objekt bank_account a v něm dříve získaný account_token. Zákazník nebude muset procházet udělením souhlasu ani vybírat účet, pouze autorizuje platbu. V objektu payer také předejte pole allowed_payment_instruments a v něm pouze hodnotu BANK_ACCOUNT. To je u tohoto typu platby vyžadováno.

Povolené platební metody

Povolené platební metody lze ovládat pomocí pole allowed_payment_instruments

• Případ 1: pole allowed_payment_instruments vůbec nepředáte, zákazníkovi se zobrazí rozcestník všech platebních metod, které má eshop povolené
• Případ 2: předáte více metod, zákazníkovi se zobrazí rozcestník, kde si bude moct jednu z předaných metod vybrat
• Případ 3: předáte přesně jednu hodnotu, po otevření platební brány se rovnou zobrazí zákazníkovi

Z tohoto pole jsou také odstraněny všechny metody, které nejsou aktivní na eshopu.

Předvybraná platební metoda

Předvybranou platební metodu lze určit předáním parametru default_payment_instrument. Ovlivňuje pouze případy 1 a 2 viz výše, na případ 3 nemá vliv. Pokud tento parametr nepředáte, zobrazí se zákazníkovi rozcestník s výběrem platebních metod. Tímto parametrem můžete po otevření brány zákazníkovi rovnou zobrazit konkrétní platební metodu. Ten však stále bude mít možnost si platební metodu změnit. Předvybraná metoda musí být prvkem množiny nabízených metod v závislosti na nastavení povolených metod viz výše.

Pro využití těchto parametrů je potřeba v allowed_payment_instruments předávat hodnotu BANK_ACCOUNT.

Online vs Offline převod

Nabízíme dva typy bankovních převodů. Offline převod je zobrazení platebních údajů, zákazník následně musí sám zadat platební příkaz. Platbu lze uhradit z jakékoliv banky, pokud jsou dobře uvedné platební údaje (číslo účtu, částka, VS). U online převodu přesměrujeme zákazníka přímo do jeho bankovnictví, kde má příkaz předpřipravený. Platbu lze uhradit pouze z jeho banky pomocí předpřipraveného platebního příkazu.

Povolené SWIFTy

Banky, ze kterých je možné převodem platit, můžete určit pomocí pole allowed_swifts.

• Případ 1: pole allowed_swifts vůbec nepředáte. Zákazník platbu bankovním převodem bude moci uhradit z jakékoliv banky.
• Případ 2: v allowed_swifts předáte jeden či více SWIFTů. K dispozici budou pouze ty banky, jejichž SWIFT jste předali v poli allowed_swifts.
• Případ 3: v poli allowed_swifts předáte pouze jeden SWIFT a zároveň v poli allowed_payment_instruments předáte pouze hodnotu BANK_ACCOUNT. Pokud je pro tuto banku dostupný online převod, bude zákazník po otevření brány automaticky přesměrován přímo do bankovnictví banky.

Předvybraný SWIFT

Předvybrat banku lze předáním jejího SWIFTu v parametru default_swift. Banka s předvybraným SWIFTem bude v seznamu bank zobrazena jako první a bude zvýrazněna.

GoPay nabízí platby typu BNPL (Buy Now Pay Later), neboli odložená platba. Aktuálně jsou k dispozici dvě takovéto metody - TWISTO a SKIPPAY - viz číselník PaymentInstrument. Tyto platby jsou k dispozici ve dvou režimech:

• Odložená platba - Zákazník uhradí dodavateli celou částku později (v API DEFERRED_PAYMENT)
• Platba na třetiny - Zákazník uhradí během platby třetinu částky, zbytek uhradí dodavateli ve dvou dalších splátkách (v API PAY_IN_THREE)

Při založení platby lze tyto režimy ovlivnit. V objektu Payer lze nastavit tyto parametry:

• allowed_bnpl_types - Typy BNPL plateb, které budou k dispozici
• default_bnpl_type - Předvybraný typ BNPL platby

Tyto parametry má smysl předávat, máte-li alespoň jednu z těchto platebních metod na eshopu povolené a předáváte ji v parametru allowed_payment_instruments Nastavení se projeví u všech dodavatelů. Možné hodnoty jsou uvedeny v číselníku BNPL Types

Zobrazení či nezobrazení jednotlivé metody a BNPL typu je také dané částkou platby, protože každý poskytovatel udává limity, pro které je způsob platby dostupný:

• Twisto odložená platba - bez limitu
• Twisto platba na třetiny - Od 1 500 CZK výše
• Skip Pay odložená platba - 0 až 50 000 CZK
• Skip Pay platba na třetiny - 3 000 až 100 000 CZK

Platební metoda Apple Pay je vázána na platební metodu Platební karta. Je tedy potřeba mít na vašem e-shopu povolené platby kartou.

Apple Pay je k dispozici pouze na zařízeních, které takovéto platby umožňují (typicky Apple zařízení disponující Touch ID nebo Face ID). Doporučujeme ji tedy zobrazovat v objednávce pouze klientům, kteří takto zaplatit mohou. K tomu slouží JavaScript, který ověří, zda klient tyto podmínky splňuje. Více se dozvíte na stránkách Apple pro vývojaře.

První kontrola je window.ApplePaySession, která ověřuje, zda je k dispozici Apple Pay JS API, což je pouze v prohlížeči Safari. Tuto kontrolu je možné volat i na nezabezpečeném připojení (HTTP). Tuto variantu doporučujeme v případě, že váš web nemá TLS zabezpečení.

Druhá kontrola window.ApplePaySession.canMakePayments() ověřuje, zda zařízení, přes které zákazník na web přistupuje, umožňuje platby přes Apple Pay. Tato kontrola vyžaduje, aby web podporoval HTTPS protokol, lze ji tedy použít pouze pokud máte TLS zabezpečení. Jedná se o spolehlivější kontrolu a pokud možno, doporučujeme používat obě.

Oficiální Apple developer portal také poskytuje informace ohledně:

• Použití loga Apple Pay a dalšího artworku v sekci Marketing
• Návod na vlastní úpravy Apple Pay tlačítka v sekci Styling the Apple Pay Button using CSS

Doporučené logo najdete ke stažení v článku Jaká používat loga a názvy platebních metod?

Vyvolání redirect varianty brány je pouhé přesměrování zákazníka na gw_url. Zákazník je přesměrován na zabezpečené prostředí GoPay, kde se zobrazí platební brána a je možné dokončit platbu. V prvním kroku je nutné získat gw_url platby. Ta je vrácena v odpovědi požadavku na založení platby. Ve druhém kroku je potřeba zákazníka na získanou URL přesměrovat.

Toho lze dosáhnout několika způsoby:

1. Odkazem
2. HTTP Redirectem
3. JavaScriptem

Způsoby 2. a 3. mají tu výhodu, že klient je na platební bránu přesměrován hned z první stránky checkoutu. U prvního způsobu je nejprve přesměrován na další stránku, kde musí znova kliknout na tlačítko či odkaz. Při popisu postupu předpokládáme, že v checkoutu zákazník vyplňuje formulář, jehož odesláním dochází k vytvoření platby.

Postup přesměrování odkazem:

• formulář je odeslán metodou POST na server
• server vytvoří platbu a získává gw_url
• server vrací novou html stránku, kam je gw_url umístěna jako odkaz (pomocí např. PHP či template systému)
• zákazník je na platební bránu přesměrován kliknutím na odkaz

Postup přesměrování HTTP Redirectem:

• formulář je odeslán metodou POST na server
• server vytvoří platbu a získává gw_url
• server vrací HTTP Redirect (např. 302 Found) a v hlavičce Location předává gw_url
• prohlížeč při přijetí odpovědi automaticky přesměrovává zákazníka na platební bránu

Postup přesměrování JavaScriptem:

• k formuláři se připojí event listener, který čeká na odeslání (submit) formuláře. Po odeslání volá callback funkci, která:
  • zabrání výchozí akci, která by způsobila refresh stránky
  • serializuje data z formuláře do formátu JSON
  • pomocí AJAX volání odesílá data na server
• server v rámci komunikace s GoPay systémem získává gw_url platby
• server vrací gw_url platby v odpovědi na AJAX request
• následně je zákazník JavaScriptem přesměrován na platební bránu (např. pomocí window.location)

V JavaScriptových příkladech se pro zjednodušení nezabýváme zpracováním výjimek, proto chybí ověření výsledku AJAX volání a try-catch blocky. V produkci by toto měl vývojař ošetřit.

Verze inline platební brány je vyvolána přímo nad eshopem. Zákazník není přesměrován na doménu GoPay, ale nachází se stále na adrese eshopu, který je v pozadí platební brány stále vidět. Další informace a ukázky vzhledu inline brány naleznete v centru nápovědy v článku Co je inline platební brána?. Pokud při procesu platby dojde k přesměrování (např. do 3DS, do online bankovnictví), vrací se zákazník na standardní redirect bránu.

Pro využití inline platební brány na prodejních místech je nutné mít TLS certifikát (podpora HTTPS). Pokud není HTTPS dostupné, dojde k vyvolání standardní redirect brány

K vyvolání inline je potřeba nejprve získat gw_url. Místo toho, aby na ní byl zákazník přesměrován, je platební brána vyvolána:

1. Formulářem
2. JavaScriptem

Podobně jako u redirect platební brány má vyvolání JavaScriptem tu výhodu, že se platební brána zvedá v jednom kroku a zákazníkovi tedy stačí odeslat jeden formulář. U vyvolání formulářem je proces dvoukrokový.

Postup vyvolání formulářem:

• Formulář je odeslán metodou POST na server.
• Server vytvoří platbu a získává gw_url.
• Server vrací novou html stránku, s formulářem, kam je gw_url umístěna jako action (pomocí např. PHP či template systému). Formulář musí mít metodu POST, atribut id nastavený na gopay-payment-button a musí do něj být vložený script (viz příklad).
• Zákazník odesláním formuláře vyvolává inline platební bránu.

Postup vyvolání JavaScriptem:

• V hlavičce dokumentu vložit link na náš JavaScript (https://gw.sandbox.gopay.com/gp-gw/js/embed.js na testovacím prostředí a https://gate.gopay.cz/gp-gw/js/embed.js na produkčním prostředí).
• K formuláři se připojí event listener, který čeká na odeslání (submit) formuláře. Po odeslání volá callback funkci, která:
  • zabrání výchozí akci, která by způsobila refresh stránky
  • serializuje data z formuláře do formátu JSON
  • pomocí AJAX volání odesílá data na server
• Server v rámci komunikace s GoPay systémem získává gw_url platby.
• Server vrací gw_url platby v odpovědi na AJAX request.
• Následně se volá _gopay.checkout() metoda, která jako argument přijímá konfigurační objekt.
• V konfiguračním objektu metody je gw_url předána jako gatewayUrl a inline je nastaveno na true (viz příklad).

V JavaScriptových příkladech se pro zjednodušení nezabýváme zpracováním výjimek, proto chybí ověření výsledku AJAX volání a try-catch blocky. V produkci by toto měl vývojař ošetřit.

Platební brána je aktuálně čistě webová aplikace. Pokud je tedy integrována do mobilní aplikace, je nutno s tím počítat. To se týká i všech jejích platebních metod - včetně Apple Pay a Google Pay. Aktuálně není možné tyto platební metody využít bez platební brány pouhým vyvoláním nativního dialogu přímo z aplikace, je nutná interakce zákazníka s platební bránou.

Nepoužívejte WebView. WebView nedisponuje plnou funkčností prohlížeče a platební brána a metody jako Apple Pay a Google Pay nebudou pomocí těchto technologií fungovat. Toto se týká např. technologií WebView pro Android a WKWebView pro Apple.

Používejte technologie, které mají funkčnost plnohodnotného prohlížeče - což znamená Chrome Custom Tabs pro Android a SFSafariViewController pro iOS.

V API volání pro založení platby je předán parametr return_url v objektu callback. Na ni je zákazník z brány přesměrován metodou GET, jako query parametr id je předáno ID platby, ze které se zákazník vrací. Pomocí tohoto ID je následně potřeba provést dotaz na stav platby.

V odpovědi získáte parametr state, který popisuje stav platby. Následné zpracování stavu je popsané v sekci Zpracování stavu platby.

Pokud byla vyvolána inline brána JavaScriptem, je možno předat callback funkci jako druhý parametr metody _gopay.checkout. V takovém případě nedochází k přesměrování zákazníka na return_url, ale je volána callback funkce přímo na stránce, na které došlo k vyvolání platební brány. Callback funkci je jako argument předán objekt, který obsahuje return_url platby jako parametr url včetně query parametru id.

Ve funkci doporučujeme pomocí AJAX volání provést dotaz na stav platby. V tomto případě je nutno mít na vašem serveru endpoint, který přijme ID platby, provede dotaz na stav platby pomocí REST API a následně vrátí stav platby. Callback funkce jej může následně dále zpracovat.

ID platby můžete získat z url, která je předána jako argument callback funkci (první příklad), případně ho můžete mít uložené v proměnné již od asynchornního založení platby (druhý příklad - vychází z vyvolání inline brány JavaScriptem).

V JavaScriptových příkladech se pro zjednodušení nezabýváme zpracováním výjimek, proto chybí ověření výsledku AJAX volání a try-catch blocky. V produkci by toto měl vývojař ošetřit.

Podle stavu platby při návratu může nastat jedna ze čtyř situací:

1. Platba byla úspěšná (stavy PAID či AUTHORIZED)
2. Platba byla zrušena (stavy CANCELED či TIMEOUTED)
3. Neproběhl pokus platbu uhradit (stav CREATED)
4. Čeká se na výsledek platby (stav PAYMENT_METHOD_CHOSEN)

Průběh stavů, kterých platba nabývá, je popsán v sekci Popis vytvoření a průběhu platby.

Stavem AUTHORIZED je označena předautorizovaná platba, autorizace tedy proběhla úspěšně a platbu bude možné následně strhnout pomocí API volání.

Pokud je platba při návratu ve stavu CREATED, zákazník neprovedl pokus platbu uhradit a platební bránu zavřel. Může nastat také, pokud bránu zavřel, protože chtěl zvolit jinou platební metodu. V takovém případě mu tedy lze nabídnout založení nové platby s jinou platební metodou.

Pokud je stav platby při návratu PAYMENT_METHOD_CHOSEN, znamená to, že se zákazník pokusil platbu uhradit, ale ještě nemáme výsledek platby. To může nastat například u bankovních převodů, kdy se čeká na připsání platby na účet GoPay. Tato platba ještě může být v budoucnu uhrazena, proto nedoporučujeme nabízet zákazníkovi provedení nové platby. O následné změně stavu platby budete informováni prostřednictvím HTTP notifikace.