Platební brána GoPay GoPay Integrační manuál verze 1.9 09.08.2011
Obsah 1 Definice...4 2 Platební brána...5 3 Postup integrace...7 3.1 Obchodník: poptávka služeb...7 3.2 GoPay: vytvoření testovacího prostředí...7 3.3 Obchodník: provedení integrace...7 3.4 GoPay: ověření integrace...8 3.5 GoPay: dokončení smlouvy, předání provozních údajů...8 4 Základní integrace...9 4.1 Princip komunikace...9 4.2 Vytvoření platby...10 4.3 Ověření platby...11 4.4 URL platební brány GoPay...11 5 Úplná integrace...12 5.1 Princip komunikace...12 5.2 Vytvoření platby...13 5.3 Přesměrování na platební bránu GoPay...14 5.4 Ověření stavu platby...14 5.5 URL platební brány GoPay...15 6 U-U integrace...16 6.1 Princip komunikace...16 6.2 Vytvoření platby...17 6.3 Přesměrování na platební bránu GoPay...17 6.4 Ověření stavu platby...17 6.5 URL platební brány GoPay...17 7 Přímá integrace...19 7.1 Princip komunikace...19 7.2 Vytvoření platby...20 7.3 Přesměrování na platební bránu...21 7.4 Ověření stavu platby...21 7.5 URL platební brány GoPay...21 8 GoPay služby...22 8.1 Služby...22 8.1.1 Vytvoření platby...22 8.1.2 Vytvoření partnerské platby...22 8.1.3 Vytvoření přímé platby...22 8.1.4 Stav platby...22 8.1.5 Založení uživatele...22 8.2 GoPayWS...23 8.2.1 Definice WS...23 Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 2
8.2.2 Popis volání...23 8.2.3 Použití WS...24 8.3 GoPayHTTP...25 8.3.1 Vytvoření platby...25 8.3.2 Stav platby...26 8.3.3 Použití GoPay HTTP...27 9 GoPay notifikace...28 9.1 Doručení notifikace...29 9.2 HTTP notifikace...29 9.3 XML-RPC notifikace...30 9.4 Email notifikace...31 9.5 SMS notifikace...32 10 Vyúčtování...33 11 Založení uživatele...34 12 Testování plateb...35 12.1 GoPay platební brána...35 12.1.1 Platební metoda GoPay...35 12.1.2 Platební metoda supercash...36 12.1.3 Platební metoda PremiumSMS...36 12.2 GoPay Monitor...36 13 Komunikační elementy...37 13.1 Platební příkaz (paymentcommand)...37 13.2 Partnerský platební příkaz (partnerpaymentcommand)...38 13.3 Přímý platební příkaz (directpaymencommand)...40 13.4 Platební session (paymentsession)...41 13.5 Identita platby (paymentidentity)...42 13.6 Výsledek volání (paymentresult)...43 13.7 Stav platby (paymentstatus)...44 13.8 Založení uživatele (buyercreate)...45 13.9 Výsledek vytvoření uživatele (buyercreateresult)...46 13.10 Kódy platebních metod...47 13.11 Stav platby...48 13.12 Doba životnosti platby...49 13.13 Kód země...50 13.14 Podpis komunikačních elementů...51 13.14.1 Vzorové implementace...51 14 Vzorové implementace...52 15 Kontaktní údaje...53 16 Přílohy...54 16.1 PHP...54 16.2 ASP.NET...56 16.3 ASP Classic...57 16.4 Java API...59 Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 3
1 Definice Obchodník Obchodní účet E-shop Zákazník GoPay peněženka Uživatel GoPay Platební brána GoPay monitor GoPayWS GoPayHTTP GoPay Notifikace Platba (Payment session) Registrační formulář Provozovatel E-shopu. Účet obchodníka v rámci GoPay, kde jsou evidovány platby z jednotlivých E-shopů. E-shop nebo internetová aplikace provozovaná obchodníkem. Osoba využívající služeb obchodníka. Internetová peněženka pro rychlé každodenní platby, posílání nebo přijímání peněz po internetu. Uživatel GoPay peněženky identifikovatelný pomocí Go přezdívky. Platební brána GoPay umožňuje obchodníkovi nebo uživateli GoPay peněženky přijímat platby na obchodní účet z níže popsaných platebních metod. Prostředí obchodníka pro sledování plateb na vytvořených obchodních účtech, E-shopech. Webová služba umožňující přístup k systémovým funkcionalitám platební brány. Webová zpřístupňuje shodné služby s GoPayWS, ale je realizována bez nutnosti použití SOAP. Zajišťuje doručení informace o provedení platby obchodníkovi. Identifikace platby v rámci GoPay. Každá platba na platební bráně má přiřazeno jedinečné číslo paymentsessionid. Součást smlouvy mezi GoPay a obchodníkem. Definuje poplatky, nastavení E-shopů a vyúčtovací politiku. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 4
2 Platební brána V rámci jediné smlouvy a jediné integrace získá každý obchodník hlavní platební metody na českém internetu za velmi výhodných podmínek. Hlavní předností je úspora nákladů v rámci jednotné správy financí. Platební brána GoPay umožňuje obchodníkovi ve svém profilu evidovat více internetových obchodů na různých obchodních účtech. Přijaté platby jsou zaznamenány na obchodní účet odpovídající danému obchodu. Převod prostředků na bankovní účet obchodníka je prováděn ve formě vyúčtování. Vyúčtování je prováděno pravidelně za určité období, nebo manuálně za aktuálně dostupné období. Parametry vyúčtování jsou blíže popsány ve smluvních podmínkách a v Registračním formuláři. Obchodní účty lze napojit na různé bankovní účty a tím rozdělit příjmy z jednotlivých činností. Fungování platební brány GoPay si můžete vyzkoušet na vzorovém E-shopu www.goshop.cz. Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 5
Platební brána GoPay je základním rozhraním pro provádění plateb prostřednictvím systému GoPay. Obchodník může jejím prostřednictvím přijímat platby následujícími platebními metodami: Platební metody Typ platby Provedení platby Poskytovatel služby VISA, MasterCard platební karta on-line Moneybookers.com AMEX, JCB platební karta on-line Moneybookers.com VISA, MasterCard GP webpay - platba kartou prostřednictvím GoPay peněženky on-line Global payments GoPay peněženka elektronická peněženka on-line GoPay.cz Moneybookers peněženka elektronická peněženka on-line Moneybookers.com Mojeplatba internetové bankovnictví on-line Komerční Banka a.s. eplatby internetové bankovnictví on-line Raiffeisenbank a.s. mpeníze internetové bankovnictví on-line BRE Bank S.A. Volksbank internetové bankovnictví on-line Volksbank a.s. Fio banka internetové bankovnictví on-line Fio banka, a.s. GE Money Bank internetové bankovnictví on-line GE Money Bank, a.s. Bankovní převod bankovní převod offline Bankovní účty GOPAY s.r.o. PremiumSMS SMS platba on-line XPay s.r.o. supercash terminály Česká pošta a.s., SAZKA a.s. offline Manum s.r.o. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 6
3 Postup integrace Integrace GoPay do prostředí E-shopu nebo internetové aplikace obchodníka je rozdělena do následujících etap. 3.1 Obchodník: poptávka služeb Na www stránkách GoPay vyplní obchodník poptávkový formulář (https://www.gopay.cz/partnerstvi). Obchodní oddělení GoPay kontaktuje obchodníka nejpozději do 3 pracovních dnů. 3.2 GoPay: vytvoření testovacího prostředí V případě, že se obchodník rozhodne využít nabídku GoPay, je třeba vyplnit a zaslat registrační formulář, na základě kterého bude vytvořeno testovací prostředí. Údaje pro nastavení testovacího prostředí jsou předávány obchodníkovi E-mailem, popřípadě SMS zprávou. 3.3 Obchodník: provedení integrace V této fázi provádí obchodník integraci GoPay do prostředí svého E-shopu. Pro implementaci může zvolit: samostatná implementace Pro samostatnou implementaci je připraveno API pro několik programových prostředí PHP, Javu, ASP.NET, ASP.Classic. GoPay modul Dále je možné použít platební moduly GoPay pro open-source řešení jako je PrestaShop, Magento, Joomla, ZenCart (viz https://www.gopay.cz/jak-funguje-gopay/platebni-moduly). Nebo lze využít služeb některého z našich certifikovaných dodavatelů (viz https://www.gopay.cz/o-nas/nasi-partneri/platebni-reseni). Pro ověření implementace je k dispozici testovací prostředí GoPay, kreditovaný uživatel GoPay a testovací platební brána. Více o testování integrace naleznete v kapitole 12 - Testování plateb. Před samotnou realizací je nutné předat na integrace@gopay.cz údaje viz níže uvedené úkoly. Úkol Obchodník předal IP adresy pro přístup k testovacímu prostředí GoPay peněženka, GoPay Monitor. Obchodník předal URL pro doručení HTTP notifikace. Splněno /NE /NE Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 7
3.4 GoPay: ověření integrace Jakmile je integrace na straně obchodníka dokončena, potom provede Tester (obchodník) níže uvedené úkoly a kontaktuje GoPay na adrese integrace@gopay.cz pro ověření integrace. Po úspěšném provedení kontroly je integrace předána k ověření úplnosti smluv. Úkol Tester vytvořil z prostředí E-shopu platbu na testovacím prostředí GoPay. Tester vytvořil z E-shopu platbu a následně provedl její úhradu on-line metodou. E-shop korektně zpracoval successurl. Tester vytvořil z E-shopu platbu a následně provedl její zrušení. E-shop korektně zpracoval failedurl. Tester vytvořil z E-shopu platbu a následně vybral platbu formou supercash (opište si číslo supercash - k pozdější úhradě). Dále se tester vrátil zpět na E-shop. E-shop korektně zpracoval successurl aniž by byla platba dokončena. Tester provede uhrazení supercash platby z rozhraní viz 12.1.2. E-shop korektně zpracuje notifikaci o provedení platby. E-shop předal GoPay logo k prezentaci na platební bráně. E-shop předal prezentační text pro sekci Kde nakupovat. Splněno /NE /NE /NE /NE /NE /NE /NE 3.5 GoPay: dokončení smlouvy, předání provozních údajů V této fázi je prováděna kontrola úplnosti smluv s GoPay. Za předpokladu úspěšně provedené kontroly, jsou obchodníkovi předány provozní údaje. Provozní údaje obdržíte emailem a SMS zprávou na kontaktní údaje uvedené ve smlouvě. Technický kontakt obdrží provozní GoID E-shopu a šifrovací klíč (secret). Obchodní kontakt obdrží přístupové údaje do prostředí GoPay Monitoru. V tento okamžik je nutné nakonfigurovat E-shop s provozními údaji (GoID, secret). UPOZORNĚNÍ: Nezapomeňte změnit URL na provozní adresy GoPay. Integrační proces je zakončen vytvořením platby na provozním prostředí a její kontrolou. Po provedení níže uvedených úkolů nás, prosím, kontaktujte na integrace@gopay.cz. Úkol Tester vytvořil z prostředí E-shopu platbu na provozním prostředí GoPay. E-shop prezentuje platební systém GoPay dle požadavků ve smlouvě. Splněno /NE /NE V případě, že nekontaktujete GoPay do 7 dnů, od předání provozních údajů, dojde k pozastavení E- shopu. Žádost o opětovnou aktivaci a prodloužení finálního testu zasílejte na integrace@gopay.cz. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 8
4 Základní integrace Základní integrace je určena pro webové aplikace typu darovací tlačítko. Jde o řešení, kde není nutná automatizovaná obsluha provedení platby. Kontrola provedení platby probíhá manuálně v prostředí GoPay monitoru. 4.1 Princip komunikace Na níže uvedeném diagramu zobrazen platební proces s využitím základní integrace. deployment Základní integrace 7 - ověření platby pomocí GoPay monitoru 4 - informace o provedení/neprovedení platby M oneybookers, Global payments, Komerční banka, M Bank, atd. E-shop 6 - E-mail - upozornění o změně stavu platby gate.gopay.cz 3 - založení/provedení platby prostřednictvím provozovatele vybrané platební metody Provozovatel platební metody 5 - přesměrování na E-shop dle provedení/zrušení platby 1 - výběr zboží/služby 2 - přesměrování po stisku tlačítka na platební bránu GoPay Zákazník Průběh platby : 1, 2) Výběr zboží/služby, přesměrování na platební bránu Pohyb zákazníka na E-shopu a výběr zboží/služby kliknutím na platební tlačítko. Následuje přesměrování na platební bránu. Sestavení platebního tlačítka je popsáno níže (viz 4.2 - Vytvoření platby). Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 9
3) Výběr platební metody Na platební bráně je zákazník vyzván k výběru platební metody a je informován o dalším postupu pro dokončení platby (přechod na platební rozhraní vybrané platební metody, odeslání PremiumSMS, platba supercash kupónu, atp.). 4,5) Vytvoření/zrušení platby V případě online plateb (viz 2 - Platební brána) dostává platební brána informaci o provedení platby okamžitě a zákazník je přesměrován dle výsledku na successurl nebo failedurl. Pro případ plateb formou offline metod může zákazník přejít na stranu E-shopu prostřednictvím successurl aniž by byla platba dokončena. Po přesměrování zpět na E-shop je nutné, aby zákazník byl informován o úspěšném/neúspěšném vytvoření platby. 6, 7) E-mail informace, ověření platby Pro zpracování objednávky, resp. určení stavu platby je nutné provést ověření v prostředí GoPay Monitoru (viz níže 4.3 - Ověření platby). Nelze spoléhat pouze na přesměrování na successurl nebo notifikační E-mail. 4.2 Vytvoření platby Platbu lze vytvořit prostřednictvím platebního tlačítka nebo formuláře. Níže je uveden příklad formuláře, který zjednodušeně demonstruje příklad užití. Pro vytvoření platby jsou platební bráně předávány parametry odpovídající elementu 13.1 - Platební příkaz (paymentcommand). Jednotlivé parametry obsahují prefix paymentcommand. viz níže. Podle užití na testovacím prostředí, nebo provozním prostředí GoPay nastavte URL (viz 4.4 - URL platební brány GoPay). <form action="https://testgw.gopay.cz/zaplatit-jednoducha-integrace" method="post"> <input name="paymentcommand.eshopgoid" value="8540279704" /> <input name="paymentcommand.productname" value="darovat 100Kc" /> <input name="paymentcommand.totalprice" value="10000" /> <input name="paymentcommand.variablesymbol" value="darovat 100Kc"/> <input name="paymentcommand.successurl" value="http://www.eshop.cz/success" /> <input name="paymentcommand.failedurl" value="http://www.eshop.cz/failed"/> <input name="paymentcommand.encryptedsignature" value="00d3d5bcbb484fec2a4b302e42d0cbf43bcf434ba949662c3a8e8580f204bfb9ca38178a3c9fd187 f45ad1da92f3b0cd" /> </form> Upozornění parametry obsahují prefix paymentcommand. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 10
Vytvoření platby je podporováno v API funkcionalitách viz níže uvedená tabulka. Prostředí PHP ASP.NET ASP.classic implementace založení platby viz 16.1, vytvoření formuláře naleznete ve třídě GopayHelper, funkci createeshopform. viz 16.2, vytvoření formuláře naleznete ve třídě PaymentGopayBase, funkce BuildFields. viz 16.3, vytvoření platby naleznete ve třídě GopayHelper, funkci createeshopform. 4.3 Ověření platby Po provedení platby a připsání prostředků na obchodní účet je obchodníkovi odeslána emailová notifikace o provedení platby. Na základě této notifikace je nutné provést kontrolu platby v prostředí GoPay monitoru. Teprve na jejím základě je možné provést dokončení platebního procesu. Prostředí GoPay monitor URL https://www.gopay.cz/gopay-monitor/prihlaseni 4.4 URL platební brány GoPay URL platební brány pro vytvoření platby je uvedeno níže. V průběhu integrace používejte testovací instanci, která Vám umožní plné ověření veškerých funkcionalit systému. Nastavení test aplikace je nutné i při používání API funkcionalit. Více informací naleznete vždy v příkladech užití jednotlivých API. Prostředí Test Produkce URL https://testgw.gopay.cz/zaplatit-jednoducha-integrace https://gate.gopay.cz/zaplatit-jednoducha-integrace Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 11
5 Úplná integrace Úplná integrace je určena E-shopy nebo webová řešení, která vyžadují automatizované zpracování provedení platby. 5.1 Princip komunikace Platba je založena ze serverové strany E-shopu pomocí GoPay služeb. E-shop získá identifikátor platby paymentsessionid před samotným provedením/zrušením platby. Tímto je vytvořena unikátní vazba mezi objednávkou a platbou. Po dokončení platby je provedena on-line kontrola platby prostřednictvím GoPay služeb (viz 8 - GoPay služby). deployment Uplna integrace 9 - dotaz na stav platby GoPayWS, GoPayHTTP 8 - HTTP notifikace o změně stavu platby 7 - dotaz na stav platby GoPayWS, GoPayHTTP 5 - informace o provedení/neprovedení platby M oneybookers, Global payments, Komerční banka, M Bank, atd. E-shop 2 - vytvoření platby GoPayWS, GoPayHTTP gate.gopay.cz 4 - založení/provedení platby prostřednictvím provozovatele vybrané platební metody Provozovatel platební metody 6 - přesměrování na E-shop dle provedení/zrušení platby 3 - přesměrování na platební bránu GoPay, před výběrem platební metody 1 - výběr zboží/služby Zákazník Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 12
Průběh platby s využitím úplné integrace je zobrazen níže: 1) Zákazník se pohybuje na E-shopu. Provádí výběr zboží/služby (plnění košíku). 2) E-shop vytvoření Platby Vytvoření platby je dostupné prostřednictvím GoPay služby (viz 5.2 - Vytvoření platby). 3) Přesměrování na platební bránu GoPay Následuje přesměrování na URL platební brány GoPay (viz 5.3 - Přesměrování na platební bránu GoPay). Součástí přesměrování je parametr, který určuje implicitní platební metodu. 4) Výběr platební metody Na platební bráně provede zákazník výběr platební metody. Nabízené platební metody jsou ovlivněny parametry předávanými při vytvoření platby. O dalším postupu pro dokončení platby je zákazník informován na platební bráně (přechod na platební rozhraní vybrané platební metody, odeslání PremiumSMS, platba supercash kupónu, atp.). 5,6,7) Provedení/neprovedení platby, ověření platby V případě online plateb (viz 2 - Platební brána) dostává platební brána informaci o provedení platby okamžitě a zákazník je přesměrován dle výsledku na successurl nebo failedurl. Pro případ plateb formou offline metod může zákazník přejít na stranu E-shopu prostřednictvím successurl aniž by byla platba dokončena. Pro dokončení, resp. pro určení stavu platby je nutné provést ověření stavu platby (viz postup popsaný v 5.4 - Ověření stavu platby). Po přesměrování zpět na E-shop je nutné, aby stav platby byl zákazníkovi vhodně prezentován. 8, 9) HTTP notifikace o změně stavu platby HTTP notifikace zajišťuje bezpečné doručení informace o změně stavu platby. Doručení HTTP notifikace je provedeno do 15 vteřin od provedení/zrušení/vypršení životnosti platby. Zpracování notifikace je blíže popsáno v kapitole 5.4 - Ověření stavu platby. Zpracování HTTP notifikace je povinné. Notifikaci lze doručit dalšími kanály (viz 9 - GoPay notifikace). 5.2 Vytvoření platby Vytvoření platby je dostupné prostřednictvím GoPay služby, (viz 8.1.1 - Vytvoření platby), předávané parametry odpovídají elementu 13.1 - Platební příkaz (paymentcommand). Jako výsledek je získán identifikátor platby v systému GoPay (paymentsessionid). Na straně E-shopu je nutné vytvořit relaci mezi objednávkou a platbou paymentsessionid. V závislosti na platební metodě GoPay požaduje po zákazníkovi množinu osobních údajů. Tyto údaje GoPay předává provozovateli platební metody. Pro usnadnění ovládání platební brány lze zákaznické Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 13
údaje předávat jakou součást platebního příkazu. Od okamžiku vytvoření je možné zjišťovat stav platby pomocí GoPay služeb (viz 8.1.4 - Stav platby). Životní cyklus platby je popsán v 13.11 - Stav platby. Vzorové implementace vytvoření platby naleznete v přiložených zdrojových kódech. Prostředí PHP ASP.NET ASP.classic Java implementace založení platby viz 16.1, vytvoření platby naleznete ve skriptu payment.php. viz 16.2, vytvoření platby naleznete ve třídě PaymentGopayFull, funkce Pay. viz 16.3, vytvoření platby naleznete ve skriptu payment.asp. viz 16.4, vytvoření platby naleznete ve třídě SimplePayment, metoda pay. 5.3 Přesměrování na platební bránu GoPay Přesměrování obsahuje parametry (viz 13.4 - Platební session (paymentsession)). Jednotlivé parametry (vyjma parametru paymentchannel) obsahují prefix sessioninfo. Parametr paymentchannel zajistí před-výběr platební metody a může nabývat hodnot (viz 13.10 - Kódy platebních metod). URL nastavte podle 5.5 - URL platební brány GoPay. Přesměrování na platební bránu GoPay https://www.gopay.cz/zaplatit-plna-integrace? sessioninfo.paymentsessionid=3803928540&sessioninfo.eshopgoid=1803628540&sessioninfo.encryp tedsignature=25ee53a1eccc253a8317bc9487174d09ba6b00a0f5267d2de6b483f58af9676d883e26600 ce3316a&paymentchannel=supercash" Upozornění: parametry (vyjma parametru paymentchannel) obsahují prefix sessioninfo. Vzorové implementace pro sestavení přesměrování naleznete ve shodných zdrojových kódech s vytvořením platby. 5.4 Ověření stavu platby Ověření stavu platby je prováděno při zpětném přesměrování z GoPay na E-shop, nebo po příchodu HTTP notifikace. URL přesměrování zpět na E-shop, ale i HTTP notifikace jsou doplněny shodnými parametry (viz 13.5 - Identita platby (paymentidentity)). Na successurl je zákazník přesměrován po provedení platby, nebo po úspěšném založením platby vybranou platební metodou (offline metody a internetová bankovnictví v nočních hodinách). Z toho důvodu je nutné provádět kontrolu stavu platby prostřednictvím GoPay služby 8.1.4 - Stav platby. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 14
Na failedurl je zákazník přesměrován pokud je provedeno zrušení platby. I v tomto případě lze provádět kontrolu dotazem na stav platby. Zpracování HTTP notifikace zajišťuje doručení informace o provedení platby i v situaci, kdy na straně zákazníka dojde k přerušení připojení k internetu, atp. Z tohoto důvodu je zpracování povinnou součástí úplné integrace. Vzorové implementace zpracování návratu na E-shop naleznete v přiložených zdrojových kódech. Prostředí PHP ASP.NET ASP.classic Java implementace založení platby viz 16.1, kontrola parametrů přesměrování a stavu platby naleznete ve skriptu callback.php. Kontrola na základě příchozí notifikace je obsažena ve skriptu notify.php. viz 16.2, kontrola parametrů přesměrování naleznete ve třídě PaymentGopayFull, funkce Callback. Kontrola na základě příchozí HTTP notifikace ve třídě PaymentGopayFull, funkce PaymentNotification. viz 16.3, kontrola parametrů přesměrování a stavu platby naleznete ve skriptu callback.asp. Kontrola na základě příchozí notifikace je obsažena ve skriptu notify.asp. viz 16.4, kontrola po přesměrování zpět na platební bránu, nebo po příchodu HTTP notifikace je připravena ve tříděsimplepayment, metoda callback.. 5.5 URL platební brány GoPay URL pro přesměrování na platební bránu je uvedeno níže. V průběhu integrace používejte testovací instanci, která Vám umožní plné ověření veškerých funkcionalit systému. Nastavení test aplikace je nutné i při používání API funkcionalit. Více informací naleznete vždy v příkladech užití jednotlivých API. Prostředí Test Produkce URL https://testgw.gopay.cz/zaplatit-plna-integrace https://gate.gopay.cz/zaplatit-plna-integrace Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 15
6 U-U integrace U-U integrace je speciálním řešením platebního procesu, které umožňuje platby na GoPay peněženku. Integrace je vhodná pro aplikace, kde uživatelé systému obchodují mezi sebou samostatně a aplikace obchodníka vytváří pouze prostředí pro realizaci obchodu (Např. Aukční portály). Platební brána GoPay zde funguje jako platební nástroj mezi uživateli GoPay. Jako doplňující funkcionalita U-U integraci je možnost založení GoPay uživatele (viz 11 - Založení uživatele). 6.1 Princip komunikace Na diagramu je zobrazen scénář užití U-U integrace na aukčním portálu. Scénář vykresluje situaci, kdy uživatel A provádí platbu uživateli B prostřednictvím aukčního portálu, resp. GoPay platební brány. deployment U-U integrace 2 - založení platby pomocí GoPayWS 4 - převod peněz na GoPay peněženku uživatele B gate.gopay.cz 3 - přesměrování uživatele A na platební bránu GoPay, provední platby. 5 - přesměrování uživatele A zpět na aukční portál Aukční portál 1 - ukončení aukce, domluva na dodání zboží a ceně Uživatel B Uživatel A Při realizaci vycházejte z principů Úplné integrace. Rozdíl v implementacích je pouze ve způsobu vytvoření platby a přesměrování na platební bránu. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 16
6.2 Vytvoření platby Platba je vytvářena voláním GoPay služby 8.1.2 - Vytvoření partnerské platby. Tato funkce je parametrizována elementem (viz 13.2 - Partnerský platební příkaz (partnerpaymentcommand)). Rozdílem proti standardní platbě je v uvedení GoID uživatele GoPay peněženky jako příjemce platby a GoID partnera jako partnerid. Partner je prostředí z něhož jsou platby vytvářeny a fakticky jde v rámci GoPay o standardní E-shop. Tento E-shop kromě zapojení do U-U integrace může přijímat platby mechanismem úplné integrace. Pro sestavování podpisů je použit šifrovací klíč přiřazený partnerovi. Vzorové implementace vytvoření partnerské platby naleznete v přiložených zdrojových kódech: Prostředí Java implementace založení platby viz 16.4, vytvoření platby naleznete ve třídě SimpleUUPayment, metoda pay. 6.3 Přesměrování na platební bránu GoPay Přesměrování obsahuje parametry (viz 13.4 - Platební session (paymentsession)). Jednotlivé parametry obsahují prefix sessioninfo. URL nastavte podle 6.5 - URL platební brány GoPay. Přesměrování na platební bránu GoPay https://gate.gopay.cz/u-u-integrace? sessioninfo.paymentsessionid=3803928540&sessioninfo.buyergoid=1803628540&sessioninfo.encrypt edsignature=25ee53a1eccc253a8317bc9487174d09ba6b00a0f5267d2de6b483f58af9676d883e26600 ce3316a" Upozornění: parametry obsahují prefix sessioninfo. Vzorové implementace pro sestavení přesměrování naleznete ve shodných zdrojových kódech s vytvořením platby. 6.4 Ověření stavu platby Ověření platby je prováděno shodným způsobem s úplnou integrací (viz 5.4 - Ověření stavu platby). 6.5 URL platební brány GoPay URL pro přesměrování na platební bránu je uvedeno níže. V průběhu integrace používejte testovací instanci, která vám umožní plné ověření veškerých funkcionalit systému. Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 17
Nastavení test aplikace je nutné i při používání API funkcionalit. Více informací naleznete vždy v příkladech užití jednotlivých API. Prostředí Test Produkce URL https://testgw.gopay.cz/u-u-integrace https://gate.gopay.cz/u-u-integrace Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 18
7 Přímá integrace Přímá integrace nabízí možnost provedení platby prostřednictvím on-line platebních metod (viz 2- Platební brána) bez nutnosti uživatelské interakce s platební bránou GoPay. Offline platební metody jsou obslouženy standardním způsobem. Přímá integrace je aktuálně v přípravě. Předpokládáné nasazení funkcionality je ve čtvrtém kvartálu 2011. 7.1 Princip komunikace Platba je založena ze serverové strany E-shopu pomocí GoPay služeb (viz 8 - GoPay služby). Zákazník je následně přesměrován na platební rozhraní dodavatele platební metody. Po provedení platby je zákazník přesměrován zpět na rozhraní E-shopu, na návratové URL (returnurl). Platební brána paralelně předává E-shopu informaci o změně stavu platby, na kterou E-shop reaguje dotazem na stav platby (viz 8 - GoPay služby). deployment Přímá integrace 7 - zjištění stavu platby prostřednictvím GoPayWS 6 - HTTP notifikace o změně stavu platby 5 - informace o provedení-neprovedení platby 1 - výběr zboží-služby Eshop 2 - vytvoření platby prostřednictvím GoPayWS, výběr platební metody gate.gopay.cz 3 - přesměrování na platební bránu poskytovatele platební metody prosřednictvím gate.gopay.cz Provozov atel platební metody 4 - přesměrování na returnurl prostřednictvím gate.gopay.cz, po provedení-neprovedení platby, Nakupující Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 19
Průběh platby s využitím úplné integrace je zobrazen níže: 1) Zákazník se pohybuje na E-shopu. Provádí výběr zboží/služby (plnění košíku). 2) E-shop vytvoření Platby Vytvoření platby je dostupné prostřednictvím GoPay služby (viz 7.2-Vytvoření platby). Oproti úplné integraci je předáván parametr určující platební metodu, na kterou je zákazník přesměrován. 3) Přesměrování na platební bránu poskytovatele Dále je zákazník přesměrován na URL platební brány GoPay (viz 7.5-URL platební brány GoPay). Resp. toto URL slouží pro okamžité přesměrování na platební bránu poskytovatele, bez interakce zákazníka. 4) Provedení platby, přesměrování na returnurl Na platební bráně poskytovatele provede zákazník platbu a je přesměrován zpět, prostřednictvím platební brány GoPay, na rozhraní E-shopu. Přesměrování je provedeno na returnurl, které je předáno v okamžiku vytvoření platby. 5, 6, 7) informace o změně stavu platby, HTTP notifikace Po příchodu informace od poskytovatele platební metody je platba na straně GoPay dokončena nebo zrušena. Na základě změny stavu platby je E-shopu předána HTTP notifikace o změně stavu. Doručení HTTP notifikace je provedeno do 15 vteřin od okamžiku změny stavu (viz 9 - GoPay notifikace). 7.2 Vytvoření platby Vytvoření platby je dostupné prostřednictvím GoPay služby, (viz 8.1.3 - Vytvoření přímé platby), předávané parametry odpovídají elementu 13.3 - Přímý platební příkaz (directpaymencommand). Jako výsledek je získán identifikátor platby v systému GoPay (paymentsessionid). Na straně E-shopu je nutné vytvořit relaci mezi objednávkou a platbou paymentsessionid. Od okamžiku vytvoření je možné zjišťovat stav platby pomocí GoPay služeb (viz 8.1.4 - Stav platby). Životní cyklus platby je popsán v 13.11 - Stav platby. Planá 67, 370 01, České Budějovice, tel. +420 387 685 160, e-mail integrace@gopay.cz 20
7.3 Přesměrování na platební bránu Přesměrování obsahuje parametry (viz 13.4 - Platební session (paymentsession)). URL nastavte podle 7.5 - URL platební brány GoPay. Přesměrování na platební bránu GoPay https://www.gopay.cz/prima-integrace? sessioninfo.paymentsessionid=3803928540&sessioninfo.eshopgoid=1803628540&sessioninfo.encryp tedsignature=25ee53a1eccc253a8317bc9487174d09ba6b00a0f5267d2de6b483f58af9676d883e26600 ce3316a Upozornění: parametry obsahují prefix sessioninfo. 7.4 Ověření stavu platby Ověření platby je prováděno shodným způsobem s úplnou integrací (viz 5.4 - Ověření stavu platby). Resp. po přesměrování zákazníka zpět na E-shop (returnurl) je nutné vyčkat na doručení informace o změně stavu platby. 7.5 URL platební brány GoPay URL pro přesměrování na platební bránu je uvedeno níže. V průběhu integrace používejte testovací instanci, která Vám umožní plné ověření veškerých funkcionalit systému. Nastavení test aplikace je nutné i při používání API funkcionalit. Více informací naleznete vždy v příkladech užití jednotlivých API. Prostředí Test Produkce URL https://testgw.gopay.cz/prima-integrace https://gate.gopay.cz/prima-integrace Planá 67, 370 01, České Budějovice, tel.: +420 387 685 160, e-mail: integrace@gopay.cz. 21