V tomto článku naleznete seznam požadavků pro integraci platební brány GoPay do dodavatelských obchodních platforem (např. e-shopová řešení typu Shoptet nebo Eshop-rychle.cz).
Jednotlivé požadavky vychází z dlouhodobých zkušeností GoPay s integracemi platební brány GoPay do těchto řešení. Jejich cílem je zajistit optimální zobrazení a fungování platební brány GoPay pro koncové uživatele a dosáhnout maximálního konverzního výkonu celého objednávkového procesu.
💡 Tip GoPay: Chcete se stát Certifikovaným dodavatelem GoPay? Integrujte GoPay podle uvedených požadavků, nechte si integraci posoudit a získejte označení Certifikovaný dodavatel GoPay. Více informací naleznete v článku "Jak získám označení Certifikovaný dodavatel GoPay?".
Technické požadavky
V rámci implementace s platební bránou vaše řešení musí splnit povinná kritéria a mělo by se řídit našimi doporučeními.
Povinná kritéria
Poskytněte prosím technické podpoře GoPay ukázkovou testovací stránku s prodejním formulářem a přístup do jeho administrace (prostředí) z pohledu obchodníka.
Přístup nesmí být podmíněný instalací řešení / aplikace třetí strany, zajistěte prosím webový přístup na ukázkovou stránku a do administrace.Integrace s platební bránou musí probíhat v REST API (V3).
Vycházejte z nejnovější verze SDKknihoven a jazyků PHP, .NET, Java a pod.
E-shop poběží na zabezpečené stránce s HTTPS, TLS podpora musí být alespoň ve verzi 1.2.
Platby na provozním prostředí musí vždy probíhat ze shodné URL adresy e-shopu, která byla k obchodnímu účtu registrovaná a schválená, viz dle článku "Z jaké URL mohu zakládat platby?".
Zajistěte, aby se dotaz na stav platby provedl vždy po redirectu (
return_url) a HTTP notifikaci (notification_url) a docházelo ke korektním aktualizacím příslušných objednávek. Dotaz na stav platby prosím neprovádějte cyklicky.U objednávek prosím zobrazte správně a pro klienty srozumitelně názvy stavů objednávek.
Když zákazník přejde v e-shopu do košíku objednávky (checkout), proveďte prosím získání seznamu povolených platebních metod (vrácený seznam je vždy v češtině). Funkcionalitu volejte prosím pouze jednou, neposílejte k ní requesty cyklicky.
V košíku objednávky zajistěte správné zobrazení platebních metod - na výběr máte z přímé / agregované prezentace, viz ukázky níže. Pro zobrazení předvybrané platební metody na bráně prosím použijte parametr default_payment_instrument v objektu payer. Platební metody ovšem nesmí být spojeny do jedné možnosti, tedy aby zákazník musel volit metodu až na bráně. Seznam platebních metod je možné uchovávat v cache, ale je nutno zajistit případnou aktualizaci, aby se promítly změny, pokud obchodník zakáže / povolí některé metody ve svém GoPay obchodním účtu. Alternativně je obchodníkovi v konfiguraci pluginu možno nabídnout vlastní nastavení platebních metod. V takovém případě provádějte API volání pro získání platebních metod v konfiguraci pluginu, a to v okamžiku, kdy obchodník nastavuje platební metody v rámci pluginu.
Podporuje-li vaše prostředí různé jazykové mutace a ne pouze českou, názvy platebních metod převeďte a zobrazte v odpovídajícím jazyce (například u stránky v angličtině zobrazit anglické názvy platebních metod Payment card, Online bank transfer atd.).
Zajistěte prosím, aby se platební metoda Apple Pay zákazníkům v košíku objednávky zobrazila pouze v případě použití podporovaných zařízeních Apple s prohlížečem Safari. Informace k implementaci naleznete v našem článku v části "Jak integrovat Apple Pay?", anebo přímo na stránce Apple pro vývojáře.
K prezentaci platebních metod prosím používejte výhradně správná loga platebních metod.
Zabraňte zpoplatnění platebních metod.
Po založení platební brány prosím zajistěte vyvolání platební brány, viz náš článek část "Vyvolání platební brány". Nabídněte obchodníkovi možnost volby mezi Inline a Redirect (přesměrováním).
Prezentujte prosím ve vaší administraci správné názvy údajů Client Secret, ClientID a GoID, obdobně nabídněte obchodníkovi možnost nastavení testovacího a provozního prostředí.
Zajistěte ve vaší administraci validaci údajů (Client Secret, ClientID a GoID pro příslušnou variantu prostředí - testovací / produkční) vždy, když v ní obchodník provede úpravu nastavení údajů, a to následovně. Client Secret a ClientID ověříte získáním přístupového tokenu a v případě GoID zkontrolujete získáním seznamu povolených platebních metod. Ověření prosím neprovádějte cyklicky.
Předávejte prosím vždy v rámci objektu contact všechny parametry. Telefon zákazníka předávejte vždy včetně předčíslí (př. +420).
Odchytejte prosím všechny možné a vámi podporované scénáře pro úspěšné / neúspěšné dokončení plateb, stejně tak situaci spojenou s návratem do e-shopu (objednávky) bez potvrzení platební metody na platební bráně a situaci v případě na bráně potvrzené banky pro offline (standardní) bankovní převod. Jedná se konkrétně o následující situace.
Platba zaplacena (PAID) - zákazník se vráti do e-shopu a musí se mu zobrazit rekapitulace s potvrzením úspěšné úhrady.
Platba zamítnuta (CANCELED) - zákazník platbu nedokončil úspěšně, vrátí se do e-shopu, kde by se měla zobrazit rekapitulace s informací o neuhrazené objednávce a měla by se mu nabídnout možnost provést novou platbu, případně nabídnout možnost zaslání e-mailu s linkem na provedení nové platby.
Vypršelá platba (TIMEOUTED) - zákazník mohl zůstat příliš dlouho na bráně a nevrátil se na e-shop, poté si aktualizuje objednávku a měla by se zobrazit informace, že objednávka nebyla úspěšně uhrazena, tedy opět nabídnout provedení nové platby, či zaslání e-mailu s odkazem na provedení nové platby.
Platební metoda vybrána (PAYMENT METHOD CHOSEN) - v rámci uvedené situace se čeká na výsledek platby, platba zatím není uhrazena, ale k uhrazení může dojít později. Situace bude nejčastěji nastávat u offline bankovního převodu (má-li obchodník v GoPay obchodním účtupovoleno u Bankovních převodů Offline), avšak může k ní výjímečně dojít také u dalších platebních metod. V tomto případě by nemělo být zákazníkovi nabízeno opětovné zaplacení, aby nedošlo k dvojí úhradě. Pokud je platba následně ukončena stavem TIMEOUTED, ze strany GoPay bude odeslána HTTP notifikace a na jejím základě lze odeslat zákazníkovi email s odkazem na opětovné uhrazení.
Vytvořena (CREATED) - Zákazník na platební bráně nepotvrdil žádnou platební metodu, vrátil se do e-shopu, životnost platby ještě nevypršela (možnost ověření dotazem po přesměrování / redirectu) a měl by mít možnost pokračovat ve stejné platbě k dané objednávce.
Možný scénář v případě nestandardní situace - Pokud by zákazník zavřel okno ve chvíli, kdy na bráně nepotvrdil žádnou metodu a z brány neprovedl přesměrování zpět do e-shopu a následně by si například v novém okně prohlížeče vyvolal košík / objednávku (coby příhlášením uživatele k účtu na e-shopu), v tomto případě to lze při vstupu do zákazníkova účtu (u příslušné objednávky) ošetřit provedením dotazu na stav platby mimo doporučené situace (redirect, HTTP notifikace), postačí však provést jednou / při vstupu (ověřování stavu neprovádějte cyklicky). K id platby, kterou jste si předtím uložili do databáze, získáte k příslušné objednávce informaci o aktuálním stavu nedokončení/zaplacení. Zůstává-li platba stále ve stavu CREATED, můžete zákazníkovi u objednávky nabídnout k této platbě nové vyvolání brány (předvybraná metoda zůstává stejná). Pokud by nastala jakákoli jiná situace popsaná výše, pak můžete postupovat dle odpovídajícího doporučení.
Nepovinné - doporučené možnosti
Nabízíte-li e-shop ve více jazyčných mutacích, předávejte prosím při založení platby také parametr lang s odpovídajícím jazykem.
V případě neúspěšné platby nabídněte a zašlete zákazníkovi email s odkazem na opětovné uhrazení. Link na platbu lze vygenerovat standardně coby parametr gw_url a umístit do těla e-mailu. U platby můžete nabídnout předvybranou platební metodu, jako u původní platby, kterou zákazník k objednávce prováděl. Můžete se inspirovat naším článkem, konkrétně částí "Umístění push platby do e-mailu s potvrzením objednávky".
V rámci vyššího komfortu pro klienty můžete umožnit přímo GoPay předávat provozní údaje obchodníků (Client Secret, ClientID a GoID) do administrace vaší platformy. Tzn. zajistit přístup přes přihlášení na doméně obchodníka pod www.nejakyeshop.xy/gopay-login. Po přihlášení bude moci technik technické podpory GoPay zadat do formuláře potřebné údaje.
Další možné funkcionality, které můžete nabídnout
Refundace plateb - nabídněte zákazníkům možnost vrácení prostředků.
Opakované platby - umožněte zákazníkům pravidelné stržení plateb, a to v některé ze dvou podporovaných variant.
Předaturizované platby - funkcionalita je vhodná pro použití v kombinaci s opakovanými platbami, u předobjednávek a za platbu služeb, u kterých se může částka změnit, anebo k platbě nakonec nedojde. Garantujeme blokaci až po dobu 4 dnů.
Stahování výpisů pohybů přes API - v rámci funkcionality lze stahovat výpisy pohybů v podporovaných formátech.
Unikátní otisk karty a Platba karetním tokenem - Funkcionalita umožňuje jednak v rámci tzv. otisku karty ověřit, že při platbě byla použita konkrétní platební karta, a zároveň lze zajistit, aby tato konkrétní karta byla použita u následných plateb (lze použít u standardní platby, inicializačních/zakládající opakované platby a předautorizované platby).
PSD2 platba tokenem účtu - díky této funkcionalitě lze zajistit u PSD2 (expresních) bankovních převodů, že platby budou v rámci zapamatovaného režimu probíhat ke konkrétnímu bankovnímu účtu zákazníka.
Požadavky na prezentaci GoPay
Pro prezentaci informací o GoPay na vašich stránkách nebo v administraci vašeho řešení vycházejte výhradně z článku "Jaké informace o GoPay můžete prezentovat zákazníkům"? Pokud chcete prezentovat informace nad rámec toho, co je v článku uvedeno, vždy o tom GoPay informujte a výsledný záměr s námi konzultujte.
Zajistěte, aby se obchodníci vašeho řešení mohli registrovat u GoPay prostřednictvím přiděleného registračního formuláře se specifickou URL adresou. Díky registraci přes tento formulář rozpoznáme, že daný obchodník používá vaše řešení.
Odkaz na registrační formulář prezentujte na viditelném místě v administraci vašeho řešení i na vašich webových stránkách, v případě, že na nich uvádíte informace o GoPay.