Příručka pro použití platební brány
Transcription
Příručka pro použití platební brány
Příručka pro použití Platební brány PaySec Verze dokumentu 1.20 Upozornění: ČSOB si vyhrazuje právo dokument upravovat, měnit adresy (umístění) a rozhraní služeb systému PaySec. V případě dotazů prosím kontaktujte Helpdesk PaySec. Příručka pro použití Platební brány PaySec verze 1.20 Obsah 1. Platební brána PaySec - obecné podmínky používání 4 1.1. Základní pojmy 1.1.1. Platební řešení PaySec e-commerce 1.1.2. Elektronická peněženka PaySec 1.1.3. PaySec 1.1.4. Platební brána platebního řešení PaySec 1.1.5. Mobilní platební brána platebního řešení PaySec 1.1.6. Brána pro chytré telefony platebního řešení PaySec 1.1.7. Webová služba MAPI (Merchant API) 1.1.8. Typy platebních metod 4 4 4 4 4 5 6 6 7 2. 8 Platba prostřednictvím Platební brány PaySec 2.1. Ve prospěch internetového obchodu z Konta PaySec 8 2.2. Ve prospěch internetového obchodu běžným bankovním převodem z běžného účtu jiné banky (QR platbou) nebo složenkou (Offline platba) 9 2.3. Ve prospěch internetového obchodu on-line z běžného účtu u ČSOB nebo Poštovní spořitelny / Era 10 2.4. 2.4 Ve prospěch internetového obchodu platebními kartami 11 2.5. Ve prospěch internetového obchodu MasterCard Mobile 12 2.6. Možné kolize a jejich řešení 13 2.6.1. Zákazník se nevrátil zpět do e-shopu z platební brány PaySec 13 2.6.2. Transakci se nepodařilo zrealizovat 13 2.6.3. Stav transakce se nepodařilo ověřit 13 2.6.4. Přerušení transakce před přijetím do systému 14 2.6.5. Automatická periodická kontrola stavu nedokončených objednávek 14 3. Integrace PaySec se stránkami obchodníka 3.1. 3.2. 3.3. 3.4. 3.4.1. 3.4.2. 3.4.3. 3.4.4. 4. Vstupní parametry pro platební bránu Vstupní parametry pro Mobilní platební bránu Jakou platební metodu zvolit Platba z Internetového obchodu Příklad formuláře e-shopu – klasická verze (test) Příklad formuláře e-shopu – klasická verze (produkce) Příklad formuláře e-shopu – mobilní verze (test) Příklad formuláře e-shopu – mobilní verze (produkce) 16 16 19 20 21 21 21 22 22 Rozhraní Merchant API (MAPI) 23 4.1. Testovací a produkční prostředí 4.2. Zabezpečení komunikace 4.3. Metody 4.3.1. VerifyTransactionIsPaid 4.3.2. GetStatement a GetStatementWithBalance 4.3.3. PaymentReturn 4.3.4. RepeatPayment 4.3.5. depositBlockedTransaction 4.3.6. cancelBlockedTransaction 23 24 24 25 27 32 34 35 36 5. 5.1. 5.2. Testovací platební brána – uživatelské rozhraní Přihlášení do uživatelského rozhraní Platební brána – menu po přihlášení © 2007-2014 Československá obchodní banka, a.s. 37 37 38 Příručka pro použití Platební brány PaySec verze 1.20 5.3. 5.4. 5.5. 5.6. Platební Platební Platební Platební brána brána brána brána – – – – MAPI detail volání MAPI Transakce detail transakce 38 39 40 41 6. FAQ – nejčastější dotazy 42 7. Označení internetového obchodu logem PaySec 43 8. Přílohy 44 8.1. Bezpečná komunikace 8.1.1. Nastavení serverového certifikátu jako důvěryhodného 8.2. Příklady volání webové služby MAPI z různých technologií 8.2.1. Definice SOAP zpráv 8.2.2. C# 2.0 pomocí SOAP zpráv 8.2.3. PHP 5.2.5 8.2.4. ASP.NET 2.0 8.2.5. ASP 3.0 – Visual Basic 8.2.6. Python © 2007-2014 Československá obchodní banka, a.s. 44 44 45 45 46 47 47 49 50 Příručka pro použití Platební brány PaySec verze 1.20 1. Platební brána PaySec - obecné podmínky používání Použití platební brány k přijímání plateb v systému PaySec je vázáno na vlastnictví Konta pro obchodníky a vztahují se na ně Obchodní podmínky PaySec. Konto pro obchodníky si může založit Fyzická osoba-podnikatel nebo Právnická osoba. Identifikační formulář majitele Konta pro obchodníky je k dispozici na adrese www.paysec.cz. 1.1. Základní pojmy 1.1.1. Platební řešení PaySec e-commerce Platební řešení PaySec e-commerce je univerzální on-line platební řešení umožňující obchodníkovi (e-shopu nebo neziskové organizaci) příjem plateb na Internetu z několika platebních metod v jednom řešení. 1.1.2. Elektronická peněženka PaySec Elektronická peněženka PaySec je univerzální on-line platební nástroj pro platby na Internetu na bázi předplaceného konta. Pomocí Konta PaySec je možné platit u obchodníků, kteří platbu PaySec podporují, nebo provádět platby mezi Konty PaySec. 1.1.3. PaySec Systém serverů, který nabízí obchodníkům (e-shopům a neziskovým organizacím) platební řešení PaySec e-commerce a klientům elektronickou peněženku PaySec. 1.1.4. Platební brána platebního řešení PaySec Platební brána (uživatelské rozhraní) je samostatná část portálu PaySec, která slouží k realizaci jedné transakce mezi klientem (platí) a obchodníkem (přijímá platbu). Pomocí platební brány může nakupující pohodlně a rychle autorizovat transakci a zaplatit tak obchodníkovi. Platební brána funguje na serveru PaySec a sama o sobě nevyžaduje žádnou instalaci. Obchodník si realizuje pouze jednu implementaci platební brány a díky ní může zákazníkům nabídnout několik platebních metod. Na tuto stránku se můžete dostat výhradně přesměrováním ze stránek obchodníka v případě, že klient zvolil platbu pomocí PaySec. Platební brána umožňuje klientovi výběr mezi více platebními metodami PaySec (platba z Konta PaySec klienta na Konto PaySec obchodníka) ČSOB (platba z běžného účtu klienta u ČSOB na Konto PaySec obchodníka) Poštovní spořitelna / Era (platba z běžného účtu klienta u Poštovní spořitelny / Era na Konto PaySec obchodníka) Platební karty (platby platebními kartami asociací MasterCard, VISA a Diners Club na Konto PaySec obchodníka) MasterCard Mobile (platba platebními kartami asociací MasterCard a VISA prostřednictvím smart aplikace MasterCard Mobile) Běžný bankovní převod / složenka / QR platba (offline platba) (platba převodem z běžného účtu v libovolné bance pomocí internetového bankovnictví nebo Smartbankignu nebo složenkou na Konto PaySec obchodníka) Klient tedy nemusí vlastnit Konto PaySec a přesto může obchodníkovi zaplatit z běžného účtu u ČSOB nebo Poštovní spořitelny / Era, pomocí platební karty libovolné banky nebo platebním příkazem z běžného účtu libovolného banky v ČR, případně složenkou na České poště. Platební brána existuje v testovací a produkční verzi. Testovací verze: https://testgateway.paysec.cz/GateWay.aspx Produkční verze: https://gateway.paysec.cz/GateWay.aspx © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Platební brána z pohledu klienta 1.1.5. Mobilní platební brána platebního řešení PaySec Mobilní platební brána je zjednodušenou verzí klasické platební brány a je vhodná pro e-shopy, které mají mobilní webovou verzi webu / e-shopu. Od klasické platební brány se mobilní verze odlišuje následujícími vlastnostmi: Produkční verze je provozována na adrese: https://gateway.paysec.cz/MobileGateWay.aspx Testovací verze je provozována na adrese https://testgateway.paysec.cz/MobileGateWay.aspx Její GUI je zjednodušené Nabízí pouze tyto platební metody: o Platební karty (platby platebními kartami asociací MasterCard, VISA a Diners Club na Konto PaySec obchodníka) o PaySec (platba z Konta PaySec klienta na Konto PaySec obchodníka) Uživatel PaySec nemůže provádět platby vyžadující autorizaci SMS o ČSOB Smartbanking (platba z běžného účtu klienta u ČSOB na Konto PaySec obchodníka prostřednictvím ČSOB Smartbankingu) o Era Smartbanking (platba z běžného účtu klienta u Poštovní spořitelny / Era na Konto PaySec obchodníka prostřednictvím Era Smartbankingu) o MasterCard Mobile (platba platebními kartami asociací MasterCard a VISA prostřednictvím smart aplikace MasterCard Mobile) Platební metody ČSOB Smartbanking, Era Smartbanking a MasterCard Mobile se zobrazí uživateli pouze v tom případě, že je mobilní brána zobrazena ze zařízení s operačním systémem Android nebo Apple iOS. Upozornění: vstupní parametry pro klasickou a mobilní verzi platební brány se liší především v parametru Sessionless. Rozdíl v implementaci mezi klasickou a mobilní platební brány je v adrese a dodatečném parametru Sessionless pro mobilní bránu. E-shop používající mobilní bránu nesmí být závislý na session, ale rozpoznat zákazníka vracejícího se z brány pomocí parametru zaslaného eshopem do parametru BackURL. Blíže viz kapitola 3.2. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Mobilní platební brána z pohledu klienta 1.1.6. Brána pro chytré telefony platebního řešení PaySec Platební řešení PaySec nabízí pro e-shopy poskytující své zboží nebo služby prostřednictvím nativních smart aplikací pro telefony nebo tablety s operačním systémem Google Android nebo Apple iOS speciální PaySec bránu pro chytré telefony. Technická specifikace PaySec brány pro chytré telefony je popsána v samostatné dokumentaci. 1.1.7. Webová služba MAPI (Merchant API) MAPI je webová služba (aplikační rozhraní - API) platebního řešení PaySec, které umožňuje majitelům Konta pro obchodníky ověřit provedení transakce zadané prostřednictvím Platební brány, Mobilní platební brány i Brány pro chytré telefony. Toto rozhraní je určeno obchodníkům, kteří expedují zboží nebo službu. Pro využití rozhraní MAPI je nutné napojit internetový obchod na webovou službu PaySec. To umožní e-shopu automaticky ověřovat provedení transakcí klientů všemi platebními metodami. Případně automatizovaně provádět vratky. Použití MAPI vyžaduje základní programátorské zkušenosti. MAPI existuje v testovací a produkční verzi a vždy ve dvou variantách. Viz kapitola Rozhraní Merchant API (MAPI). © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 1.1.8. Typy platebních metod Online platební metody Platby těmito metodami jsou prováděny v reálném čase. Tzn. po provedení platby a návratu z platební brány zpět do e-shopu je již známo, zda byla platba provedena či nikoli. Pouze ve výjimečných případech (výpadky externích systémů, výpadky síťového spojení, atp.) může být platba dokončena až později. Metody: PaySec, ČSOB, Poštovní spořitelna / Era, Platební karty, MasterCard Mobile Offline platební metody Ověření provedení platby není možné provést ihned po přesměrování z platební brány zpět do e-shopu. Toto je případ platební metody Běžný bankovní převod / složenka / QR platba, kdy musí nejdříve proběhnout převod mezi bankou zákazníka a ČSOB (platba je připisována na sběrný účet PaySec). To trvá typicky od několika hodin až po několik dnů v závisti na tom, jak rychle odešle platbu banka zákazníka. Připsání plateb je ihned po jejich obdržení z jiné banky. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 2. Platba prostřednictvím Platební brány PaySec Platba pomocí platebního řešení PaySec s využitím platební brány probíhá následovně: 2.1. Ve prospěch internetového obchodu z Konta PaySec 5 internetový obchod PaySec 61 4 2 3 Uživatel Přehled komunikace při platbě v internetovém obchodě 1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány PaySec. 2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak, aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo uvedeno URL platební brány PaySec. 3. Zákazník si na platební bráně vybere platební metodu PaySec. Zákazník bude přesměrován na přihlášení do svého PaySec Konta. Po zadání přihlašovacího jména a hesla do systému PaySec potvrdí transakci. V případě transakce vyšší než limit, který si zákazník nastavil ještě autorizuje transakci pomocí SMS. Peníze jsou převedeny na Konto obchodníka. 4. Internetový prohlížeč uživatele je přesměrován zpět na adresu, která byla předána platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené platby (nebo informaci o zamítnutí platby zákazníkem). 5. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu provedení transakce. Ověření transakce musí být provedeno ihned po zavolání návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund. 6. Zákazníkovi je zobrazena informace o úspěšném nebo neúspěšném provedení transakce a zaplacené zboží (služba, obsah) je předáno k odeslání (stažení a podobně). © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 2.2. Ve prospěch internetového obchodu běžným bankovním převodem z běžného účtu jiné banky (QR platbou) nebo složenkou (Offline platba) 1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány PaySec. 2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak, aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo uvedeno URL platební brány PaySec. 3. Zákazník si na platební bráně vybere platební metodu Bankovní převod/QR platba. 4. Uživateli jsou zobrazeny údaje pro provedení platebního příkazu. (Číslo sběrného účtu systému PaySec. specifický a variabilní symbol, atd.). Tyto údaje jsou zobrazeny jednak textově a jednak pomocí mezibankovního QR kódu. 5. Zákazník provede platbu ze svého internetového bankovnictví, podáním platebního příkazu ve své bance nebo podáním složenky na České poště nebo načtením QR kódu Smartbankingem své banky. Platba je připsána na Konto PaySec obchodníka až po připsání částky na sběrný účet systému PaySec, což může trvat od několika hodin až po 3 dny. Na Konto pro obchodníky je platba připsána ihned po obdržení platby z jiné banky přes clearing ČNB. 6. Internetový prohlížeč uživatele je po kliknutí na tlačítka Potvrdit platbu/Odmítnout platbu přesměrován zpět na adresu, která byla e-shopem předána platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět v URL identifikaci provedené platby (nebo informaci o zamítnutí platby zákazníkem), a dále parametr OfflinePayment=1. 7. Pokud bylo vráceno číslo provedené platby a parametr OfflinePayment=1, zobrazí e-shop zákazníkovi informaci o čekání na příchozí platbu pomocí běžného bankovního převodu. 8. Zákazníkovi e-shop může ještě jednou zobrazit parametry platby a pokud má k dispozici zákazníkův e-mailu, tak mu je ještě odešle e-mailem. Parametry platby jsou v ostrém prostředí: Číslo účtu: 72887288/0300 Částka: určuje e-shop Specifický symbol: číslo obchodnického PaySec Konta e-shopu Variabilní symbol: je předán e-shopu v návratovém URL jako TransactionID Platnost: do kdy musí být platba připsána na PaySec Konto obchodníka (délku platnosti si určuje obchodník v úvodním nastavení tohoto typu platby) 9. Pokud bylo vráceno číslo provedené platby a parametr OfflinePayment=1, internetový obchod začne periodicky volat webovou službu VerifyTransactionIsPaid (viz kapitola 4.3.1.), a to až do prvního úspěšného ověření, že byla transakce skutečně provedena (max. do doby platnosti transakce). Do doby úspěšného ověření je odpověď kód 11, který značí, že se jedná o čekající transakci běžným bankovním převodem. Tento krok je nezbytný k bezpečnému ověření skutečného stavu provedení transakce. Po připsání každé platby běžným bankovním převodem (offline platby) je zároveň obchodníkovi odeslán informační email, jehož přílohou je XML soubor s popisem transakce. Email ale není podepsaný elektronickým podpisem, a proto jej nelze považovat za důvěryhodné potvrzení platby. Nelze tedy přijetím a zpracováním tohoto emailu nahradit volání MAPI metody VerifyTransactionIsPaid. Pro přijetí tohoto e-mailu má možnost e-shop nastavit samostatnou e-mailovou adresu, na kterou jsou zasílány pouze informace o připsání tohoto typu transakcí. Ukázka XML souboru z informačního emailu o přijaté offline platbě: <?xml version="1.0" encoding="utf-16"?> <offlinePayment> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 <transactionId>101563547</transactionId> <ucetZakaznika>8857527/0300</ucetZakaznika> <merchandOrderId>1365773</merchandOrderId> <castka>100.00 Kč</castka> </offlinePayment> 2.3. Ve prospěch internetového obchodu on-line z běžného účtu u ČSOB nebo Poštovní spořitelny / Era 1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány PaySec. 2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak, aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo uvedeno URL platební brány PaySec. 3. Zákazník si na platební bráně vybere platební metodu ČSOB nebo Poštovní spořitelna / Era. 4. Platební brána přesměruje zákazníka do internetového bankovnictví. V rámci přesměrování jsou předány všechny informace k provedení platebního příkazu. 5. Zákazník se přihlásí do internetového bankovnictví a provede platební příkaz na sběrný účet systému PaySec. Do systému PaySec je odesláno avízo o provedení transakce, které umožní okamžité připsání částky na Konto PaySec obchodníka. 6. Internetové bankovnictví přesměruje zákazníka zpět do systému PaySec, kde proběhne ověření transakce vůči internetovému bankovnictví a v případě úspěchu připsání částky na Konto PaySec obchodníka. 7. Internetový prohlížeč uživatele je přesměrován zpět na adresu, která byla e-shopem předána platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené platby (nebo informaci o zamítnutí platby zákazníkem). 8. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu provedení transakce. Ověření transakce musí být provedeno ihned po zavolání návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund. 9. Zákazníkovi je zobrazena informace o úspěšném nebo neúspěšném provedení transakce a zaplacené zboží (služba, obsah je předáno k odeslání (stažení a podobně). © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 2.4. 2.4 Ve prospěch internetového obchodu platebními kartami 1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány PaySec. 2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak, aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo uvedeno URL platební brány PaySec. 3. Zákazník si na platební bráně vybere platební metodu Platební karta. 4. Platební brána přesměruje zákazníka na 3D Secure platební bránu GP webpay. V rámci přesměrování jsou předány všechny informace k provedení platby. 5. Zákazník vyplní údaje o platební kartě (číslo karty, platnost karty, CVV/CVC kód) a případně 3D secure heslo ke kartě, pokud mu ho jeho banka poskytka. Do systému PaySec je odesláno avízo o provedení transakce, které umožní okamžité připsání částky na Konto PaySec obchodníka. 6. Platební brána GP webpay přesměruje zákazníka zpět do systému PaySec, kde proběhne ověření transakce a v případě úspěchu připsání částky na Konto PaySec obchodníka. 7. Internetový prohlížeč uživatele je přesměrován zpět na adresu, která byla e-shopem předána platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené platby (nebo informaci o zamítnutí platby zákazníkem). 8. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu provedení transakce. Ověření transakce musí být provedeno ihned po zavolání návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund. 9. Zákazníkovi je zobrazena informace o úspěšném nebo neúspěšném provedení transakce a zaplacené zboží (služba, obsah) je předáno k odeslání (stažení a podobně). © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 2.5. Ve prospěch internetového obchodu MasterCard Mobile 1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány PaySec. 2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak, aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo uvedeno URL platební brány PaySec. 3. Zákazník si na platební bráně vybere platební metodu MasterCard Mobile. 4. Platební brána přesměruje zákazníka na stránku, kde je zobrazen QR kód pro načtení přes fotoaparát mobilního telefonu, který má nainstalovanou aplikaci MasterCard mobile. Aplikace je dostupná pro mobilní telefony s Android nebo Apple iOS. 5. Zákazník načte kód do aplikace MasterCard Mobile, případně ho přepíše do aplikace ručně. 6. V aplikaci se zákazníkovi zobrazí parametry platby, zákazník vybere kartu a potvrdí platbu. 7. Platební brána obdrží informaci o provedené platbě a systém PaySec okamžitě připíše částku na Konto PaySec obchodníka. 8. Platební brána přesměruje Internetový prohlížeč uživatele zpět na adresu, která byla e-shopem předána platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené platby (nebo informaci o zamítnutí platby zákazníkem). 9. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu provedení transakce. Ověření transakce musí být provedeno ihned po zavolání návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 2.6. Možné kolize a jejich řešení 2.6.1. Zákazník se nevrátil zpět do e-shopu z platební brány PaySec Kdy může nastat kolize Mezi Mezi Mezi Mezi Mezi krokem krokem krokem krokem krokem 3 2 3 3 3 a a a a a 4 6 7 7 8 u u u u u platby platby platby platby platby z peněženky PaySec běžným bankovním převodem on-line z běžného účtu ČSOB nebo Poštovní spořitelny / ERA platební kartou MasterCard Mobile Co zobrazit zákazníkovi Zákazník se již nevrátí na e-shop. Jak dále postupovat Internetový obchod implementuje automatickou periodickou kontrolu stavu nedokončených objednávek (2.6.5) pomocí volání webové služby. Na základě výsledku kontroly jsou objednávky automaticky zpracovány (transakce je ve stavu provedena) nebo zamítnuty (transakce neexistuje nebo je ve stavu zamítnutá). 2.6.2. Transakci se nepodařilo zrealizovat Kdy může nastat kolize Zákazník zamítl platbu Zákazník nesplnil podmínky pro vytvoření transakce, například má zablokovaný účet, nemá dostatek prostředků nebo pouze nedokončil autorizaci platby a přesměroval svůj prohlížeč na jinou adresu Účet obchodníka je blokovaný pro příjem plateb Co zobrazit zákazníkovi V případě zamítnutí zobrazí Internetový obchod zákazníkovi text: „Váš pokyn k zamítnutí platby byl proveden úspěšně.“ 1 V ostatních případech nedochází ke zpětnému přesměrování na Internetový obchod. Jak dále postupovat V případě nepřesměrování zákazníka zpět na Internetový obchod implementuje automatickou periodickou kontrolu stavu nedokončených objednávek pomocí volání webové služby z kapitoly 2.6.5. 2.6.3. Stav transakce se nepodařilo ověřit Kdy může nastat kolize 1 Přesměrování na Platební bránu PaySec selže. Nepodaří se dokončit platbu. Při přesměrování zpět na Internetový obchod. V kroku pro ověření platby: Webová služba pro ověření platby je nedostupná. U platby pomocí běžného bankovního převodu: platba zatím nebyla připsána na sběrný účet systému PaySec Obchodník je povinen zobrazit text v přesném znění © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Co zobrazit zákazníkovi V případě, že byl uživatel úspěšně přesměrován zpět na Internetový obchod s výjimkou běžného bankovního převodu, zobrazí se zákazníkovi následující text: „Stav transakce se nepodařilo ověřit. Pracujeme na nápravě.“2 Jak postupovat Internetový obchod implementuje automatickou periodickou kontrolu stavu nedokončených objednávek (2.6.5) pomocí volání webové služby3. Na základě výsledku kontroly jsou objednávky automaticky zpracovány (transakce je ve stavu provedena) nebo zamítnuty (transakce neexistuje nebo je ve stavu zamítnutá). 2.6.4. Přerušení transakce před přijetím do systému Pokud transakce nebyla dokončena nebo vůbec neexistuje, pak nemá obchodník vůči zákazníkovi žádný závazek a není nutná žádná akce. Transakce nemusí být dokončena zejména z těchto důvodů: Selhalo přesměrování klienta na platební bránu Data předané na platební bránu od obchodníka nebyla validní (formální chyba) Klientovi se nepodařilo přihlásit do systému (např. při zapomenutém heslu) Klient se rozhodl, že transakci nebude realizovat a neukončil transakci standardně stiskem tlačítka „Zamítnout platbu“ (například pouze zavřel okno internetového prohlížeče). Platební brána nepřijímá požadavky. V případě, že by takové situace nastávaly často, může to svědčit o chybě v platební bráně nebo jen o vysoké fluktuaci (zákazník si to při placení rozmyslí). Ujistěte se, že je platební brána z pohledu zákazníka funkční. Například používá URL adresu z produkčního prostředí spolu s číslem Konta z produkčního prostředí. Pozor, číslo Konta a URL adresy pro testovací a produkční prostředí jsou různé. 2.6.5. Automatická periodická kontrola stavu nedokončených objednávek V případech, kdy se nepodaří nebo není možné ověřit transakci voláním webové služby VerifyTransactionIsPaid (MAPI) ihned po návratu do e-shopu, popř. když k návratu nedojde, je potřeba aby internetový obchod implementoval a použil automatickou periodickou kontrolu stavu nedokončených objednávek („čekajících transakcí“) pomocí volání VerifyTransactionIsPaid. Na základě výsledku kontroly jsou objednávky automaticky zpracovány (transakce je ve stavu provedena) nebo zamítnuty (transakce je ve stavu zamítnutá) nebo se ve zvoleném intervalu volání zopakuje (transakce nebo číslo objednávky neexistuje). Ověření transakce je možné zkoušet ihned po té, co je zákazník přesměrován z e-shopu na platební bránu PaySec, kromě platební metody Běžný bankovní převod, kdy téměř určitě platba ještě nebude zaúčtovaná. Je možné ověřovat všechny objednávky libovolně staré a libovolně dlouho. Do doby provedení transakce odpovídá PaySec kódem 4 – transakce neexistuje. To znamená, že buď vůbec nebyla založeno nebo se čeká na dokončení platby. Po provedení transakce odpovídá PaySec kódem 0 - Transakce byla úspěšně zaúčtována. V případě použití platební metody platba běžným bankovním převodem odpovídá PaySec do doby zaplacení návratovým kódem 11 – Nezaplacená offline platba. V tomto případě provádí e-shop ověřování do konce doby platnosti 2 Obchodník je povinen zobrazit text v přesném znění Jakmile je webová služba dostupná, lze z chybových kódů určit, zda transakce vůbec proběhla, a pokud ano, tak s jakým výsledkem. 3 © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 tohoto typu transakce (dny) a ne pouze po dobu max. 60 minut jako u on-line transakcí. Další méně časté kódy a doporučenou reakci naleznete v odst. 4.3.1. Doporučujeme následující postup: 1. provést kontrolu každé objednávky cca 5 - 30 minut po té, co zákazník opustil e-shop a přešel na platební bránu PaySec (a pak každou minutu po maximálně 60 minut), v případě offline platby nejdříve za 60 minut (a pak každou hodinu do doby platnosti transakce). 1) v případě odpovědi, která transakci potvrzuje (kód 0) e-shop ihned označí objednávku za zaplacenou a připíše tuto transakci zákazníkovi v případě, že se zákazník následně vrátí na e-shop, tak mu ten zobrazí standardní zprávu o úspěšném přijetí platby – stejně, jako by to učinil bez periodického ověření 2) v případě odpovědi, která transakci NEpotvrzuje (kód 4) e-shop tuto objednávku zařadí do dalšího periodického ověření. Zamítavý kód neznamená, že zákazník během následujících několika minut transakci nedokončí. 2. V případě, že při první kontrole transakce byla získána odpověď, která transakci NEpotvrzuje, bude e-shop opakovat ověřování až do 60 minut po té, co zákazník opustil e-shop a přešel na platební bránu PaySec 1) v případě odpovědi, která transakci potvrzuje (kód 0) e-shop ihned označí objednávku za zaplacenou a připíše tuto transakci zákazníkovi v případě, že se zákazník následně vrátí na e-shop, tak mu ten zobrazí standardní zprávu o úspěšném přijetí platby – stejně, jako by to učinil bez periodického ověření 2) v případě odpovědi, která transakci NEpotvrzuje (kód 4) je již velice nepravděpodobné, že zákazník transakci na platební bráně dokončí. Eshop proto tuto objednávku může vyřadit z dalšího periodického ověření. Alternativní postupy periodického ověřování „čekajících transakcí“: Je možné ověřovat transakci například každou 1 minutu po opuštění e-shopu. Tím zajistíte maximální on-linovost transakce i případě výpadku internetového připojení zákazníka před návratem na e-shop. Ověřování provádějte maximálně 60 minut po opuštění e-shopu. Upozornění: Kontrolu, zda existuje transakce s Vaším číslem objednávky, má smysl provádět pouze po určitou dobu (maximálně 20 minut od potvrzení platby zákazníkem pro online platby (tedy maximálně do 60 minut i po započítání času, který by mohl zákazník strávit mezi přesměrování z e-shopu a potvrzením platby a pro offline platby počet dnů, který máte nastavený pro platnost platebních údajů - transakce) od vytvoření objednávky. Po uplynutí této doby je 100%, že transakce již nebude zrealizována. POZOR: pokud není on-line platba ve prospěch e-shopu úspěšně ověřena (s návratovým kódem 0) do 20 minut od jejího provedení, je platba automaticky stornována a plná částka je vrácena zpět zákazníkovi. V případě pokusu o ověření transakce následně je e-shopu vrácen návratový kód 1. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 3. Integrace PaySec se stránkami obchodníka Při realizaci platby na Internetu pomocí platebního řešení PaySec je klient přesměrován z obchodu / portálu na Platební bránu PaySec, kde autorizuje transakci, a následně je přesměrován zpět na obchod/portál obchodníka. Ten pak dle využívané služby (internetový obchod / darovací platební tlačítko) informuje klienta o dalším postupu. 3.1. Vstupní parametry pro platební bránu Platební brána přijímá požadavky prostřednictvím metody HTTP POST (viz specifikace W3C) s následujícími povinnými parametry: Parametr Popis MicroaccountNumber Číslo Konta internetového obchodu (sedmimístné číslo; musí jít o aktivní Konto pro obchodníky v systému PaySec). Amount Částka v CZK, která má být uhrazena (bez oddělení tisíců; dvě desetinná místa oddělená tečkou). MerchantOrderId (Tento parametr se používá v případě, že provozujete Internetový obchod) Číslo objednávky (obsahuje číslice, písmena abecedy a speciální znaky (! , . : ; ] ) % ( [ ‘ * / #_ - + \), musí být pro každou platbu v rámci Konta obchodníka unikátní). U platby v systému PaySec bude následně toto číslo uvedeno jako Identifikace platby (variabilní symbol). V GetStatement bude uvedeno v parametru ClientIdentifier Upozornění: Parametr MerchantOrderId může obsahovat maximálně 30 znaků. OrderId (Tento parametr se používá pouze pro darovací platební tlačítko, kde se neexpeduje žádné zboží nebo služba) Variabilní symbol platby (obsahuje číslice, písmena abecedy a speciální znaky obsahuje číslice, písmena abecedy a speciální znaky (! , . : ; ] ) % ( [ ‘ * / #_ - + \), nemusí být unikátní). U platby v systému PaySec bude následně toto číslo uvedeno jako Identifikace platby (variabilní symbol). V GetStatement bude uvedeno v parametru ClientIdentifier Upozornění: Budete-li posílat číslo objednávky v parametru OrderId, nebude možné ověřit skutečný stav transakce pomocí volání MAPI! Návratový kód bude vždy 4 (transakce nenalezena). Použijte parametr MerchantOrderId, chcete-li stav transakce ověřovat. V případě použití MerchantOrderId už nepoužívejte parametr OrderId. MessageForTarget Zpráva pro příjemce platby (obchodníka; zpravidla popis objednávky), které bude zobrazená klientovi a měla by charakterizovat nakupované zboží/obsah/služby. Plátce může zprávu upravit v průběhu platby. U platby bude uvedena jako Zpráva pro příjemce. BackURL Adresa, na kterou bude internetový prohlížeč přesměrován po provedení platby (například http://www.shop.cz/platba.php?tid={0}). © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Řetězec {0} bude nahrazen identifikátorem transakce, a to následovně: Pokud byla platba zákazníkem zamítnuta a nebyla uvedena URL adresa na kterou se má přesměrovat v případě odmítnutí, pak má identifikátor hodnotu 0 (např. http://www.shop.cz/platba.php?tid=0). Pokud byl proces zaplacení dokončen, pak má identifikátor hodnotu odpovídající číslu transakce v systému PaySec (větší než 0, např. http://www.shop.cz/platba.php?tid=1688). Jako volitelný parametr je možné do URL zadat navyše řetezec {1}, který bude nahrazen hodnotou MerchantOrderId (pokud byla tato hodnota platební bráně předána), např. http://www.shop.cz/platba.php?tid={0}&merchantOr derId={1}. Upozornění: Řetězec {0} je povinný jenom v případě, když je uveden i řetězec {1}. Upozornění: Nezapomeňte, že skutečný stav transakce zjistíte teprve po volání webové služby MAPI. Upozornění: Pro validaci zda je URL správné se používá následující regulární výraz: ^(?<Protocol>https?):\/\/(?<Domain>[\w@][\w.:@ \-]+)\/?((?<FT>[\w\.?=%&=\@/$,]*\{0\})|(?<FtM>(?<FT>[\w\.?=%&=\@/$,]*\{0\})(?<MerchantOrderId>[\w\.?=%&=\@/$,]*\{1\}))|(?<MFt>(?<MerchantOrderId>[\w\.? =%&=\-@/$,]*\{1\})(?<FT>[\w\.?=%&=\@/$,]*\{0\})))?(?<ParametersRest>[\w\.?=%&=\@/$,]*)$ CancelURL Adresa, na kterou bude internetový prohlížeč přesměrován po odmítnutí platby (například http://www.shop.cz/platba.php). Jako volitelné parametry je do URL možné zadat řetězce {0} a {1} (buď jenom řetezec {0} nebo oba, a teda {0} a {1}). Řetezec {0} bude nahrazen číslem transakce 0 (značí, že transakce byla odmítnuta) a řetězec {1} hodnotou MerchantOrderId, pokud byla tato hodnota platební bráně předána. Upozornění: Řetězec {0} je povinný jenom v případě, když je uveden i řetězec {1}. Upozornění: Pro validaci zda je URL správné se používá následující regulární výraz: © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 ^(?<Protocol>https?):\/\/(?<Domain>[\w@][\w.:@ \-]+)\/?((?<FT>[\w\.?=%&=\@/$,]*\{0\})|(?<FtM>(?<FT>[\w\.?=%&=\@/$,]*\{0\})(?<MerchantOrderId>[\w\.?=%&=\@/$,]*\{1\}))|(?<MFt>(?<MerchantOrderId>[\w\.? =%&=\-@/$,]*\{1\})(?<FT>[\w\.?=%&=\@/$,]*\{0\})))?(?<ParametersRest>[\w\.?=%&=\@/$,]*)$ Note (nepovinné) Popis objednávky, který by měl charakterizovat nakupované zboží/obsah/služby. Tento popis nebude zobrazen na detailu platby, ani z pohledu klienta, ani z pohledu obchodníka. Najdete ho pouze ve výpisu transakcí po přihlášení do systému nebo jako jeden z výstupních parametrů webové služby PaySec (metoda GetStatement). Upozornění: Popis objednávky není povinný a může obsahovat maximálně 100 znaků. RepeatTemplate (nepovinné) Nepovinný parametr, určen pro funkcionalitu opakované platby. Pokud je RepeatTemplate=1, proběhne daná platba standardním způsobem, navíc je označena jako šablona pro platbu opakovanou. Následnou platbu s využitím takto vytvořené šablony provádí obchodník přes MAPI rozhraní. Poznámka: V současné době lze funkcionalitu opakované platby použít pouze pro platbu platební kartou, navíc je použití této funkce podmíněno nastavením obchodního konta. BlockTransaction (nepovinné) Nepovinný parametr, určen pro funkcionalitu předautorizované (blokované) platby. Pokud je transakce označena jako předautorizovaná, tj. BlockTransaction=1, neproběhne zaúčtování částky na konto obchodníka, ale částka je pouze předautorizována ve prospěch konta obchodníka. Samotné zaúčtování, resp. zrušení autorizace provádí obchodník přes MAPI rozhraní. Poznámka: V současné době lze funkcionalitu předautorizované platby použít pouze pro platbu platební kartou. SkipToPaymentMeth od Nepovinný parametr, určen pro přeskočení rozcestníku na zvolenou platební metodu. Jako hodnota se udává číslo platební metody, která se má použít: 1 – PaySec 2 – Platba z účtu ČSOB/ČSOB Smartbanking 3 - Platba z účtu Poštovní spořitelny/ERA Smartbanking 4 – Platební karta 5 – Běžný bankovní převod/složenka 7 – MasterCard Mobile Příklad: SkipToPaymentMethod=2 (přeskočení přímo na platbu z účtu ČSOB) Tento parametr je podporován na platební i na mobilní platební bráně. Poznámka: Platební metoda musí být povolena, jinak bude zobrazena chybová hláška. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Sessionless (povinné pro mobilní bránu) Tento parametr je povinný na mobilní bráně a má vždy hodnotu 1. Tímto parametrem dává obchodník najevo, že funkčnost jeho implementace není ovlivněna zavřením prohlížeče v mobilním zařízení. Na desktopové webové bráně se tento parametr nevyžaduje. Podrobnosti jsou uvedeny v kapitole 3.2. Nebude-li požadavek úplný, nebo nebude validní, platební brána upozorní klienta (kupujícího) a transakci v tomto případě neuskuteční. Pokud je transakce uskutečněna, je klient přesměrován na URL adresu definovanou v parametru backURL. Důležité upozornění: Zpětné volání URL obchodníka (backURL) má pouze informativní charakter. Vzhledem k „bezestavovosti“ HTTP protokolu může volání přes prohlížeč klienta z různých důvodů selhat, resp. skutečný stav transakce je nutné dodatečně ověřit pomocí webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) – u e-shopu , nebo pomocí uživatelského rozhraní PaySec, v sekci přehledy - u darovací platby. Obchodník (e-shop) nesmí expedovat zboží nebo službu pouze na základě přesměrování uživatele zpět na BackURL. Obchodník (e-shop) si musí „převzít“ platbu do svého systému voláním VerifyTransactionIsPaid nebo výjimečně voláním GetStatement. 3.2. Vstupní parametry pro Mobilní platební bránu Vstupní parametry pro mobilní verzi jsou stejné jako u klasické platební brány, obsahují však jeden parametr navíc. Parametr Popis Sessionless (povinné pro mobilní bránu) Tento parametr je povinný na mobilní bráně a má vždy hodnotu 1. Tímto parametrem dává obchodník najevo, že funkčnost jeho implementace není ovlivněna zavřením prohlížeče v mobilním zařízení (viz následující text). Na desktopové webové bráně se tento parametr nevyžaduje. U nových platebních metod, kdy placení probíhá pomocí aplikace v mobilním telefonu, může dojít během platby k uzavření webového prohlížeče. V závislosti na tom, jak používáte session management ve Vaší implementaci e-shopu, může proto dojít ke zrušení session. Pokud používáte session s uložením údajů (např. čísla objednávky) do cookie s neuvedenou dobou platnosti, při přesměrování na BackUrl nebo CancelUrl po provedení platby bude tato cookie pravděpodobně vymazána. Je možné tento problém řešit změnou nastavení session managementu ve Vámi použité technologii (uložit např. session id do parametru), nebo si posílat číslo objednávky v parametrech BackUrl a CancelUrl, aby při přesměrování zpět na Váš e-shop bylo zřejmé, ke které objednávce request patří. Je to možné těmito způsoby: Poslat si v BackUrl a CancelUrl přímo číslo objednávky: Příklad: BackUrl http://eshop.cz/objednavka.php?ft_id={0}&id_objednavky=123 CancelUrl http://eshop.cz/zruseno.php?id_objednavky=123 V BackUrl a CancelUrl poslat parametr {1}. PaySec doplní při přesměrování zpět do eshopu hodnotu merchantOrderId. Příklad: BackUrl http://eshop.cz/objednavka.php?ft_id={0}&id_objednavky={1} CancelUrl http://eshop.cz/zruseno.php?ft_id={0}&id_objednavky={1} © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Nadále bude fungovat nahrazení hodnoty {0} za číslo finanční transakce. 3.3. Jakou platební metodu zvolit Majitel Konta pro obchodníky může využít dvou metod pro komunikaci. Oba způsoby vedou k vytvoření platby, kterou může následně klient autorizovat. S výběrem vhodné metody pro napojení vašich stránek/obchodu/portálu vám pomůže následující tabulka: Metoda Pro koho Co je potřeba Internetový obchod Obchodník expedující zboží nebo službu, kde je nutné provádět automatické ověřování transakcí bez zásahu obsluhy. Tento obchodník má typicky vlastní obchod/portál, který může upravovat, event. využívá hotového řešení třetí strany, které platby pomocí PaySec podporuje. HTML, programování ve skriptovacím nebo programovacím jazyce jako např. PHP, ASP.NET, Java, apod. Parametr MerchantOrderId musí být vyplněn a musí být unikátní. V případě implementace od třetí strany nebude programování nutné. V tomto případě už nepoužívejte parametr OrderId. Po uskutečnění transakce musí být platba ověřena pomocí webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) Obchodník musí mít zřízené Konto pro obchodníky a zákazníci mohou využít všechny platební metody. POZOR: pokud není on-line platba ve prospěch e-shopu úspěšně ověřena (s návratovým kódem 0) do 20 minut od jejího provedení, je platba automaticky stornována a plná částka je vrácena zpět zákazníkovi. Darovací platební tlačítko Příjem darů. Není určeno pro e-shopy expedující zboží nebo služby. Jedná se např. o stránky pro dobrovolné dary, sponzoring,charitativní organizace, sbírky nebo v případně osobního Konta PaySec o osobní stránky apod. Místo parametru MerchantOrderId je použit parametr OrderId, který nemusí být unikátní. V tomto případě už nepoužívejte parametr MechantOrderId. V případě Konta pro obchodníky přijímá obchodník všechny metody platby. U osobního Konta PaySec je možné přijímat platby pouze z jiných Kont PaySec. © 2007-2014 Československá obchodní banka, a.s. Základy HTML. Příručka pro použití Platební brány PaySec verze 1.20 3.4. Platba z Internetového obchodu Internetový obchod posílá na v HTML formuláři následující údaje na Platební bránu PaySec. Důležité je použít pro číslo objednávky parametr MerchantOrderId. Tato hodnota musí být unikátní. Pomocí této hodnoty následně e-shop ověřuje stav platby. Teprve po potvrzení zaplacení pomocí ověřovací metody obchodník expeduje zboží nebo službu. Viz kapitola MAPI. Na desktopové webové verzi platební brány se zákazníkovi zobrazí rozcestník následujících platebních metod, avšak v závislosti na tom, jestli má obchodník dané metody povolené, zda výše částky odpovídá limitům platebních metod a není nižší než poplatek za platbu: ČSOB, Poštovní spořitelny / ERA, elektronická peněženka PaySec, platební karta, MasterCard Mobile a běžný bankovní převod. Na mobilní webové verzi platební brány volané z počítače nebo mobilního zařízení s výjimkou mobilního zařízení s Android nebo Apple iOS se zákazníkovi pouze platba z elektronické peněženky PaySec a platební kartou, opět v závislosti na tom, jestli má obchodník obě metody povolené, zda výše částky odpovídá limitům platebních metod a není nižší než poplatek za platbu. Při volání brány z mobilního zařízení s Android nebo Apple iOS se zobrazí i další „smart“ platební metody ČSOB, Era a MasterCard Mobile. 3.4.1. Příklad formuláře e-shopu – klasická verze (test) <html> <head> <title>Zaplacení pomocí PaySec</title> </head> <body> <form action="https://testgateway.paysec.cz/GateWay.aspx" method="post"> <input type="submit" value="Zaplatit pomocí PaySec" /> <input type="hidden" name="MicroaccountNumber" value="1100000" /> <input type="hidden" name="Amount" value="250.50" /> <input type="hidden" name="MerchantOrderId" value="123456" /> <input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" /> <input type="hidden" name="BackURL" value="http://www.shop.cz/platba.php?TId={0}" /> <input type="hidden" name="CancelURL" value="http://www.shop.cz/platbaodmitnuta.php" /> </form> </body> </html> 3.4.2. Příklad formuláře e-shopu – klasická verze (produkce) <html> <head> <title>Zaplacení pomocí PaySec</title> </head> <body> <form action="https://gateway.paysec.cz/GateWay.aspx" method="post"> <input type="submit" value="Zaplatit pomocí PaySec" /> <input type="hidden" name="MicroaccountNumber" value="1100000" /> <input type="hidden" name="Amount" value="250.50" /> <input type="hidden" name="MerchantOrderId" value="123456" /> <input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" /> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 <input type="hidden" name="BackURL" value="http://www.shop.cz/platba.php?TId={0}" /> <input type="hidden" name="CancelURL" value="http://www.shop.cz/platbaodmitnuta.php" /> </form> </body> </html> 3.4.3. Příklad formuláře e-shopu – mobilní verze (test) <html> <head> <title>Zaplacení pomocí PaySec</title> </head> <body> <form action="https://testgateway.paysec.cz/MobileGateWay.aspx" method="post"> <input type="submit" value="Zaplatit pomocí PaySec" /> <input type="hidden" name="MicroaccountNumber" value="1100000" /> <input type="hidden" name="Amount" value="250.50" /> <input type="hidden" name="MerchantOrderId" value="123456" /> <input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" /> <input type="hidden" name="BackURL" value="http://www.shop.cz/platba.php?TId={0}" /> <input type="hidden" name="CancelURL" value="http://www.shop.cz/platbaodmitnuta.php" /> <input type="hidden" name="Sessionless" value="1" /> </form> </body> </html> 3.4.4. Příklad formuláře e-shopu – mobilní verze (produkce) <html> <head> <title>Zaplacení pomocí PaySec</title> </head> <body> <form action="https://gateway.paysec.cz/MobileGateWay.aspx" method="post"> <input type="submit" value="Zaplatit pomocí PaySec" /> <input type="hidden" name="MicroaccountNumber" value="1100000" /> <input type="hidden" name="Amount" value="250.50" /> <input type="hidden" name="MerchantOrderId" value="123456" /> <input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" /> <input type="hidden" name="BackURL" value="http://www.shop.cz/platba.php?TId={0}" /> <input type="hidden" name="CancelURL" value="http://www.shop.cz/platbaodmitnuta.php" /> <input type="hidden" name="Sessionless" value="1" /> </form> </body> </html> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 4. Rozhraní Merchant API (MAPI) V rámci služeb rozhraní pro obchodníky existuje webová služba MAPI, která umožňuje obchodníkům ověřit, zda transakce zadaná na Platební bránu PaySec z elektronického obchodu byla či nebyla zaplacena. Služba odpovídá standardu WebServices 1.1 (WS-I Basic Profile 1.1) a je možné jí bez problémů „volat“ z různých platforem. Popis rozhraní služby ve standardu WSDL je dostupný na těchto adresách: Produkční verze https://mapi.paysec.cz/mapi.svc?wsdl (WCF Web Service) https://mapi.paysec.cz/mapi.asmx?wsdl (ASP.NET Web Service) Testovací verze https://testmapi.paysec.cz/mapi.svc?wsdl (WCF Web Service) https://testmapi.paysec.cz/mapi.asmx?wsdl (ASP.NET Web Service) Volání MAPI je na těchto adresách Produkční verze https://mapi.paysec.cz/mapi.svc (WCF Web Service) https://mapi.paysec.cz/mapi.asmx (ASP.NET Web Service) Testovací verze https://testmapi.paysec.cz/mapi.svc (WCF Web Service) https://testmapi.paysec.cz/mapi.asmx (ASP.NET Web Service) Pro většinu e-shopů je vhodnější implementovat verzi ASMX. V případě, že je e-shop v PHP, je z důvodu kompatibility PHP vhodnější použít verzi SVC. 4.1. Testovací a produkční prostředí Obě prostředí mají z pohledu MAPI identická rozhraní. V testovacím prostředí má obchodník k dispozici testovací obchodnické PaySec Konto a testovací osobní PaySec Konto. Osobní Konto je přednabité na 50 000 Kč. Při platbě platební metodou PaySec se přihlásí do osobního Konta a z něj pošle na obchodnické Konto částku transakce. Osobní Konto se automaticky pravidelně dobíjí při poklesu zůstatku pod určitou částku. Z obchodnického Konta je možné také realizovat Vratky, kdy se prostředky vrací na zdrojové osobní Konto. Při platbě platební metodou z běžného účtu u ČSOB a Poštovní spořitelny / ERA, platební kartou a MasterCard Mobile je simulováno rozhraní internetového bankovnictví, kartová platební brána a platba přes smart aplikaci MasterCard Mobile. Z těchto simulátorů je platba ihned převedena na PaySec Konto obchodníka. Zde je neomezený limit na platbu. I zde může obchodník provádět vratku na zdrojový běžný účet nebo platební kartu. Pro simulátory není nutné používat žádné přihlašovací údaje ani testovací platební kartu. Obchodník – implementátor má možnost se přihlásit do testovacího Konta PaySec, kde si může ověřit stavy jednotlivých transakcí a to, jak jsou transakce obchodníkem ověřovány. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 V produkčním prostředí je limit na transakci z osobního PaySec Konta daný vždy aktuálním sazebníkem PaySec (http://www.paysec.cz/CmsPage.aspx?Id=feeList). V době vydání této verze příručky je maximální částka transakce přes platební bránu z osobního Konta PaySec 55 000 Kč. Při platbě z běžného účtu je limit na transakci nižší z následujících dvou limitů. Na straně obchodníka je to 1 mil. Kč. Na straně uživatele internetového bankovnictví je to jeho individuální limit, který může být stejný nebo i nižší například ve stovkách tisíc Kč. Při platbě platební kartou je držitel karty omezen limitem na platební kartě pro určité období. Limit pro platby kartou na Internetu může být oddělen od limitu pro platbu kartou v kamenných obchodech. Cílem testovací verze je umožnit obchodníkovi odladit komunikaci mezi obchodem/portálem a službami PaySec. Speciálně ověřit to, jak jsou jednotlivé transakce ověřovány pomocí MAPI metody VerifyTransactionIsPaid. Zde je nutné, aby byly transakce z PaySec Konta na platební bráně označeny tmavě zelenou barvou. Přehled transakcí na testovací platební bráně najdete po přihlášení na https://testgateway.paysec.cz/Login.aspx v sekci Platební brána – Transakce. Pro přístup do produkčního prostředí použijte uživatelské jméno a heslo pro MAPI, které si můžete nastavit po přihlášení ke svému Kontu v záložce Osobní nastavení. Nemáte-li nastavené heslo pro MAPI, požádejte majitele PaySec Konta o jeho nastavení. Pro přístup do testovací verze prosím kontaktujte pracovníky týmu PaySec na e-mailové adrese [email protected] 4.2. Zabezpečení komunikace Komunikace s webovou službou MAPI je zabezpečena pomocí protokolu HTTPS. Testovací i produkční používá certifikáty vydané certifikační autoritou GlobalSign. Ujistěte se, že prohlížeč, který používáte, má uvedenou tuto certifikační autoritu jako důvěryhodnou certifikační autoritu. Blíže kapitola 8.1. 4.3. Metody Webová služba MAPI obsahuje implementaci těchto metod: VerifyTransactionIsPaid – NEZBYTNĚ NUTNÉ pro ověření zaplacení nákupu v internetovém obchodě (e-shopu) – bez ověření transakce je platba po 20 minutách stornována a vrácena zpět zákazníkovi GetStatement – získání transakční historie (zaúčtovaných položek) k danému kontu – Vhodné pro větší e-shopy pro provádění například denní rekonciliace GetStatementWithBalance – jako GetStatement, navíc obsahuje informace o zůstatcích pro dané období PaymentReturn – vrácení peněz (vratka) z transakce uskutečněné pomocí platební brány. Vhodné pro možnost automatizovaného vracení transakcí systémem e-shopu. RepeatPayment – umožní realizovat opakovanou platbu ze šablony (nyní pouze platby platební kartou; šablonou se rozumí předchozí platba stejnou kartou, která je explicitně označena jako šablona) depositBlockedTransaction – umožní zaúčtování předautorizované transakce, tj. převod částky na konto obchodníka cancelBlockedTransaction – umožní zrušit již předautorizovanou transakci Vstupní, resp. výstupní parametry volání metod viz popis dále. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 4.3.1. VerifyTransactionIsPaid Metoda VerifyTransactionIsPaid se používá pro ověření zaplacení transakce při platbě v internetovém obchodě. Implementace této služby je nezbytně nutná pro všechny obchodníky - e-shopy expedující zboží nebo službu pro automatické ověření transakce systémem e-shopu. Po úspěšném ověření platby je požadováno na e-shopu automatické označení objednávky za zaplacenou. Ověření transakce by mělo být pro online platební metody provedeno ihned po zavolání návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund. U transakcí, kde se zákazník dlouho nevrací zpět na e-shop a pro offline platební metody je nutné implementovat „periodické ověřování čekajících transakcí“. Detailní postup je popsán v kapitole 2.6.5. POZOR: pokud není on-line platba ve prospěch e-shopu úspěšně ověřena (s návratovým kódem 0) do 20 minut od jejího provedení, je platba automaticky stornována a plná částka je vrácena zpět zákazníkovi. Služba vyžaduje čtyři vstupní parametry: Parametr Typ Popis userName string Uživatelské jméno obchodníka, kterým se hlásí na portál PaySec. Password string Heslo pro MAPI. Není-li nastaveno heslo pro MAPI, použijte heslo spojené s uživatelským jménem obchodníka. merchantOrderId string Unikátní identifikátor transakce obchodníka. Tento identifikátor musí být v unikátní v rámci transakcí daného obchodníka. Pomocí čísla objednávky je následně možné zjistit stav transakce. Může obsahovat všechny znaky ASCII s výjimkou znaků > <. Amount decimal Částka v CZK včetně desetinné části. Metoda ověří, zda existuje transakce se zadaným číslem objednávky, zda cílový účet patří zadanému obchodníkovi, zda zní na správnou částku a zda se váže k uvedené objednávce. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Návratová hodnota: Metoda vrací číselný identifikátor (int) v závislosti na stavu transakce: Popis Text pro zákazníka4 Akce 0 Transakce byla úspěšně zaúčtována. Platba prostřednictvím systému PaySec proběhla úspěšně Vydat zboží/službu zákazníkovi. 1 Transakce byla zamítnuta. Platbu se nepodařilo zrealizovat. Viz kapitola 2.6.2 2 Přihlašovací jméno či heslo není platné nebo přihlašovací jméno neexistuje. Stav platby se nepodařilo ověřit. Pracujeme na nápravě. Viz kapitola 2.6.3 3 Konto je blokováno nebo zrušeno. Stav platby se nepodařilo ověřit. Pracujeme na nápravě. Viz kapitola 2.6.3 4 Transakce s daným číslem objednávky (MerchantOrderId) neexistuje. Pro online metody: Platba zatím nebyla přijata. Stav bude ověřen později. Pro offline metody: Čeká se na přijetí platby. Pro online metody: Viz kapitola 2.6.4 5 Zadaná částka neodpovídá transakci. Platbu se nepodařilo zrealizovat. Viz kapitola 2.6.3 6 Systémová chyba (kontaktujte podporu). Stav platby se nepodařilo ověřit. Pracujeme na nápravě. Viz kapitola 2.6.3 7 Nevyplněný parametr MerchantOrderId 8 Nedostatečná oprávnění (zadané přihlašovací údaje nepatří mikroúčtu typu obchodník, ale osobnímu Kontu) Stav platby se nepodařilo ověřit. Pracujeme na nápravě. 9 Transakce typu Předautorizovaná platba byla zrušena. Předautorizace částky byla zrušena. 10 Transakce typu Předautorizovaná platba byla úspěšně předautorizována. Předautorizace částky byla provedena. 11 Nezaplacená offline platba (čeká se na přijetí platby) Čeká se na přijetí platby. Webová služba je nedostupná Stav platby se nepodařilo ověřit. Pracujeme na nápravě. Hodnota - 4 Obchodník je povinen zobrazit text v přesném znění © 2007-2014 Československá obchodní banka, a.s. Viz kapitola 2.6.3 Příručka pro použití Platební brány PaySec verze 1.20 4.3.2. GetStatement a GetStatementWithBalance Metoda slouží k získání výpisu pohybů na kontě. Implementace této metody je vhodná pro větší e-shopy k automatické rekonciliaci všech pohybů na PaySec Kontě pro obchodníky a to i takových, které nebyly provedeny přes platební bránu PaySec. Vyžaduje čtyři vstupní parametry: Parametr Typ Popis userName string Uživatelské jméno obchodníka, kterým se hlásí na portál PaySec. password string Heslo pro MAPI. Není-li nastaveno heslo pro MAPI, použijte heslo spojené s uživatelským jménem obchodníka. dateFrom date Datum od, od kterého se má výpis generovat. Pokud je datum zadán včetně času, je čas ignorován. Datum je ve formátu YYYY-MM-DD, kde: YYYY je rok (2008 až 2099) MM je měsíc (01 až 12) DD je den (01 až max. 31 – podle měsíce) Příklad: 2008-06-16 dateTo date Datum, do kterého se má výpis generovat (včetně). Návratové hodnoty: Metoda vrací dva výstupy: 1) Číselný identifikátor (int) v závislosti na stavu operace: Hodnota Popis 0 OK 2 Chybné uživatelské jméno nebo heslo. 3 Konto neexistuje nebo není aktivní . 6 Systémová chyba (kontaktujte podporu). 7 Chyba vstupních parametrů. (nezadaný parametr userName nebo password) - Webová služba je nedostupná. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 2) Seznam řádků výpisu (v případě, že operace proběhla v pořádku (OK)). POZOR, formát návratových informací je jiný ve verzi ASMX a SVC. Každý řádek obsahuje tyto údaje: Parametr Typ Popis Id long Identifikátor transakce Date datetime Datum a čas zaúčtování transakce TransactionType string Název typu transakce. AccountNumber string Číslo konta. Pro nabíjení a vybíjení je prázdné. AccountName string Jméno nebo číslo protistrany - konta. Pro nabíjení kartou je prázdné. Value decimal Částka transakce bez poplatků. TotalValue decimal Částka transakce včetně poplatků. Jedná se o částku, o kterou se změnil zůstatek Konta. FeeValue decimal Částka poplatků. ClientIdentifier string Klientský identifikátor transakce (např. číslo objednávky nebo variabilní symbol) Description string Popis vztahující se k transakci. DescriptionForTarget string V případě zaslání peněz obsahuje popis určený pro cílové Konto. IsStorno bool Indikuje, zda se jedná o storno transakci. OriginalFinancialTransactionId long V případě storna obsahuje id stornované transakce, které původní transakci přidělil systém PaySec Note string Popis objednávky. NoteDetail string U plateb provedených přes platební bránu obsahuje příznak GW značící, že platba proběhla přes platební bránu. 3) Metoda GetStatementWithBalance obsahuje navíc informace o zůstatcích na kontě a o výši obratů Parametr Typ Popis BalanceStart decimal Zůstatek na mikroúčtu na začátku výpisu BalanceEnd decimal Zůstatek na mikroúčtu ke konci výpisu Expenses decimal Suma všech výdajů za dané období Fees decimal Suma všech poplatků za dané období Income decimal Suma všech příjmů za dané období © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Verze ASMX: Příklad položky příchozí platby při volání GetStatement verze ASMX u platby z běžného účtu u ČSOB a Poštovní spořitelny / ERA <GetStatementItemResponse> <Id>101378975</Id> <Date>2011-05-05T11:48:15.72</Date> <TransactionType>ChargeFromBankAccount</TransactionType> <AccountNumber>1144</AccountNumber> <AccountName>123/0300</AccountName> <Value>250.0000</Value> <TotalValue>247.0000</TotalValue> <FeeValue>-3.0000</FeeValue> <ClientIdentifier>3250659</ClientIdentifier> <Description>Test platba</Description> <DescriptionForTarget/> <IsStorno>false</IsStorno> <OriginalFinancialTransactionId xsi:nil="true"/> <TransactionTypeName>Převod z běžného účtu</TransactionTypeName> <Note/> <NoteDetail>GW</NoteDetail> </GetStatementItemResponse> Příklad položky příchozí platby volání GetStatement verze ASMX u platby jiného PaySec Konta <GetStatementItemResponse> <Id>101419870</Id> <Date>2010-11-27T04:25:43.713</Date> <TransactionType>Transfer</TransactionType> <AccountNumber>10101010</AccountNumber> <AccountName>TestKonto</AccountName> <Value>5.0000</Value> <TotalValue>5.0000</TotalValue> <FeeValue>0</FeeValue> <ClientIdentifier>7066939</ClientIdentifier> <Description>Test produkce - prijemce</Description> <DescriptionForTarget/> <IsStorno>false</IsStorno> <OriginalFinancialTransactionId xsi:nil="true"/> <TransactionTypeName>Platba z Konta na Konto</TransactionTypeName> <Note/> <NoteDetail>GW</NoteDetail> </GetStatementItemResponse> Příklad položky příchozí platby volání GetStatement verze ASMX u platby platební kartou <GetStatementItemResponse> <Id>100582379</Id> <Date>2012-01-30T18:51:36.53</Date> <TransactionType>CardPayment</TransactionType> <AccountNumber>1122</AccountNumber> <AccountName>1122</AccountName> <Value>301.0000</Value> <TotalValue>293.9800</TotalValue> <FeeValue>-7.0200</FeeValue> <ClientIdentifier>301A</ClientIdentifier> <DescriptionForTarget/> <IsStorno>false</IsStorno> <OriginalFinancialTransactionId xsi:nil="true"/> <TransactionTypeName>Platba platební kartou</TransactionTypeName> <Note/> </GetStatementItemResponse> Příklad položky příchozí platby volání GetStatement verze ASMX u platby MasterCard Mobile <GetStatementItemResponse> <Id>100588106</Id> <Date>2013-02-01T11:28:38.61</Date> <TransactionType>PaymentFromMCM</TransactionType> <AccountNumber>1122</AccountNumber> <AccountName>RMAtest01 (2203883)</AccountName> <Value>10.0000</Value> <TotalValue>10.0000</TotalValue> <FeeValue>0</FeeValue> <ClientIdentifier>827833</ClientIdentifier> <Description>12345</Description> <DescriptionForTarget/> <IsStorno>false</IsStorno> <OriginalFinancialTransactionId xsi:nil="true"/> <TransactionTypeName>Platba z MasterCard Mobile</TransactionTypeName> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 <Note>paid by android application</Note> <NoteDetail/> </GetStatementItemResponse> Verze SVC: Příklad položky příchozí platby volání GetStatement verze SVC u platby běžným bankovním převodem <StatementItem> <accountName>1100</accountName> <accountNumber>1100</accountNumber> <clientIdentifier>1748417</clientIdentifier> <date>2012-07-20T12:07:23.817</date> <description>Test produkce - prijemce</description> <descriptionForTarget/> <feeValue>-1.1000</feeValue> <id>102697063</id> <isStorno>false</isStorno> <note/> <noteDetail>GW</noteDetail> <originalFinancialTransactionId i:nil="true"/> <totalValue>8.9000</totalValue> <transactionType>Offline</transactionType> <transactionTypeName>Platba offline převodem z BÚ</transactionTypeName> <value>10.0000</value> </StatementItem> Verze SVC – kompletní výpis XML volání GetStament <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <GetStatementResult xmlns="http://schemas.mapi.paysec.cz/2008/02">0</GetStatementResult> <ArrayOfStatementItem xmlns="http://schemas.mapi.paysec.cz/2008/02/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <StatementItem> <accountName>RMAtest01 (2203883)</accountName> <accountNumber>1122</accountNumber> <clientIdentifier>5099258</clientIdentifier> <date>2013-02-01T10:28:38.64</date> <description>Zprava pro prijemce</description> <descriptionForTarget/> <feeValue>0</feeValue> <id>100588102</id> <isStorno>false</isStorno> <note/> <noteDetail/> <originalFinancialTransactionId i:nil="true"/> <totalValue>54.4500</totalValue> <transactionType>PaymentFromMCM</transactionType> <transactionTypeName>Platba z MasterCard Mobile</transactionTypeName> <value>54.4500</value> </StatementItem> <StatementItem> <accountName>RMAtest01 (2203883)</accountName> <accountNumber>1122</accountNumber> <clientIdentifier>2241672</clientIdentifier> <date>2013-02-01T10:10:01.687</date> <description>Zprava pro prijemce</description> <descriptionForTarget/> <feeValue>-2.0700</feeValue> <id>100588101</id> <isStorno>false</isStorno> <note/> <noteDetail/> <originalFinancialTransactionId i:nil="true"/> <totalValue>51.2300</totalValue> <transactionType>CardPayment</transactionType> <transactionTypeName>Platba platební kartou</transactionTypeName> <value>53.3000</value> </StatementItem> <StatementItem> <accountName>RMAtest01 (2203883)</accountName> <accountNumber>1144</accountNumber> <clientIdentifier>3516849</clientIdentifier> <date>2013-02-01T10:08:57.233</date> <description>Zprava pro prijemce</description> <descriptionForTarget/> <feeValue>0</feeValue> <id>100588100</id> <isStorno>false</isStorno> <note/> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 <noteDetail/> <originalFinancialTransactionId i:nil="true"/> <totalValue>52.2000</totalValue> <transactionType>ChargeFromBankAccount</transactionType> <transactionTypeName>Převod z běžného účtu</transactionTypeName> <value>52.2000</value> </StatementItem> <StatementItem> <accountName>RMAtest01 (2203883)</accountName> <accountNumber>2203564</accountNumber> <clientIdentifier>2441296</clientIdentifier> <date>2013-02-01T10:05:43.877</date> <description>Zprava pro prijemce</description> <descriptionForTarget/> <feeValue>-2.0000</feeValue> <id>100588098</id> <isStorno>false</isStorno> <note/> <noteDetail/> <originalFinancialTransactionId i:nil="true"/> <totalValue>48.0000</totalValue> <transactionType>Transfer</transactionType> <transactionTypeName>Platba z Konta na Konto</transactionTypeName> <value>50.0000</value> </StatementItem> </ArrayOfStatementItem> </s:Body> </s:Envelope> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 4.3.3. PaymentReturn Metoda slouží k vrácení peněz (vratka) z transakce uskutečněné pomocí platební brány. Vracení probíhá na základě unikátního identifikátoru původní platby (MerchantOrderID) a je možné vrátit libovolnou částku maximálně do výše původní platby. Lze vracet ze všech druhů plateb. Jak platby přijaté transakcí typu „Platba z Konta na Konto“ , tak peníze přijaté transakcí typu „Platba z běžného účtu“ tak platby přijaté transakcí „Platba platební kartou“. Metoda vyžaduje šest vstupních parametrů: Parametr Typ Popis userName string Uživatelské jméno obchodníka, kterým se hlásí na portál PaySec. password string Heslo pro MAPI. Není-li nastaveno heslo pro MAPI, použijte heslo spojené s uživatelským jménem obchodníka. merchantOrderId string Unikátní identifikátor původní transakce obchodníka. Může obsahovat všechny znaky ASCII s výjimkou znaků > <. amount decimal Částka včetně desetinné části. Nesmí přesáhnout výši původní transakci. descriptionForSource (nepovinné) string Zpráva pro odesílatele platby (obchodníka), která by měla obsahovat popis původní objednávky a charakterizovat důvod vracení peněz. U platby bude uvedena jako Zpráva pro příjemce. V GetStatement je pak uveden v tagu <Description> descriptionForTarget (nepovinné) string Zpráva pro příjemce platby (klienta), která by měla obsahovat popis původní objednávky a charakterizovat důvod vracení peněz. U platby bude uvedena jako Zpráva pro příjemce. V GetStatement je pak uveden v tagu <DescriptionForTarget> Návratové hodnoty: Metoda vrací strukturu PaymentReturnResult, ve které je textový kód resultCode. Ten nabývá v závislosti na stavu transakce hodnot v následující tabulce. POZOR, návratové hodnoty se liší pro verzi ASMX (text před závorkou) a SVC (číslo v závorce). Hodnota Popis OK (0) OK – vracení proběhlo úspěšně. BadCredentials (2) Chybné uživatelské jméno nebo heslo. BadCredentials (2) Konto neexistuje nebo není aktivní. BadOrderIdOrNonexistingFinTran (4) SystemError (6) BadParameters (7) - Transakce s daným číslem objednávky (MerchantOrderId) neexistuje. Chyba vstupních parametrů. Není zadáno číslo objednávky (MerchantOrderId) nebo není zadáno userName, password. Webová služba je nedostupná. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Poznámka: výše uvedené platí pouze v případě volání metody PaymentReturn přes https://mapi.paysec.cz/mapi.asmx, v případě volání přes https://mapi.paysec.cz/mapi.svc jsou jako návratové hodnoty vraceny čísla uvedeny v závorce. Ukázka volání metody PaymentReturn z PHP Předání parametrů této metodě se liší od ostatních metod, je nutné ji proto volat jinak, než je uvedeno v kapitole 8.2.3. $userName = 'obchodnik01'; $password = 'heslo01'; $merchantOrderid = '1345653056'; $amount = 28; $descriptionForSource = 'Popis pro obchodnika'; $descriptionForTarget = 'Popis pro klienta'; $paysecMapi = new SoapClient("https://testmapi.paysec.cz/mapi.svc?wsdl"); $param_array = array( 'requestData' => array( 'Header' => array( 'LoginInfo' => array( 'password' => $password, 'userName' => $userName ) ), 'amount' => $amount, 'merchantOrderid' => $merchantOrderid, 'descriptionForSource' => $descriptionForSource, 'descriptionForTarget' => $descriptionForTarget ) ); $resultObject = $paysecMapi->PaymentReturn($param_array); echo $resultObject->PaymentReturnResult->resultCode; © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 4.3.4. RepeatPayment Metoda slouží k realizaci opakované platby. Principem opakované platby je to, že pouze první platba je autorizována konečným zákazníkem, tato autorizace je poté platná i pro následné opakované platby, platba je poté inkasována obchodníkem. Pro použití této funkcionality je potřeba splnit podmínky provozovatele PaySec a podepsat dodatek ke smlouvě mezi PaySec a obchodníkem. Funkcionalita opakované platby je v aktuální verzi určena pouze pro platby platební kartou. Opakovaná platba funguje následovně: 1. Během provádění standardní platby přes platební bránu je tato platba obchodníkem označena jako opakovaná, viz parametr RepeatTemplate, kapitola 3.1 2. Po zaúčtování transakce je tato v systému označena jako šablona pro opakovanou platbu 3. Opakovaná platba se provádí MAPI voláním, jedním z parametrů je identifikace prvotní platby, která byla označena jako šablona. 4. Po provedení metody RepeatPayment je nutné volat metodu VerifyTransactionIsPaid s novým merchantOrderId pro ověření zaúčtování této opakované platby. Toto volání se řídí popisem uvedeným v kapitole 2.6.5. Metoda vyžaduje tyto vstupní parametry: Parametr Typ Popis userName string Uživatelské jméno obchodníka, kterým se hlásí na portál PaySec. password string Heslo pro MAPI. Heslo spojené s uživatelským jménem obchodníka nelze použít. oldMerchantOrderId string Unikátní identifikátor původní transakce obchodníka, která byla označena jako šablona opakované platby. Může obsahovat všechny znaky ASCII s výjimkou znaků > <. merchantOrderId string Nový jedinečný identifikátor transakce v rámci transakcí na mikroúčtu obchodníka. merOrderNumber (nepovinné) string Číslo objednávky obchodníka, nemusí být jedinečné amount decimal Částka platby včetně desetinné části. Návratové hodnoty: Metoda vrací číselný kód v závislosti na stavu transakce: Hodnota Popis 0 OK – opakovaná platba byla úspěšně autorizována. 1 Opakovanou platbu se nepodařilo zrealizovat. 2 Chybné uživatelské jméno nebo heslo, nebo konto neexistuje. 3 Konto není aktivní. 4 5 Transakce s daným číslem objednávky (MerchantOrderId) neexistuje. Zadaná částka je menší nez poplatek za transakci. 6 Systémová chyba (kontaktujte podporu). 7 Chyba 8 Obchodnické konto nemá povolenu opakovanou platbu. 12 - vstupních parametrů. nezadaný parametr userName, password nebo merchantOrderId parametr merOrderNumber je zadán, ale není celé číslo merchantOrderId je delší než 30 znaků Číslo objednávky (MerchantOrderId) bylo již použito pro platbu pro toto obchodnické konto. Webová služba je nedostupná. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 4.3.5. depositBlockedTransaction Metoda slouží k realizaci zaúčtování předautorizované (blokované) platby na účet obchodníka. Pro každou předautorizovanou platbu lze tuto metodu volat pouze jednou, lze deponovat libovolnou částku až do výše původní předautorizace. Pokud je deponovaná částka nižší než předautorizace, je rozdíl uvolněn zpět na účet zákazníka. Metoda vyžaduje tyto vstupní parametry: Parametr Typ Popis userName string Uživatelské jméno obchodníka, kterým se hlásí na portál PaySec. password string Heslo pro MAPI. Heslo spojené s uživatelským jménem obchodníka nelze použít. merchantOrderId string Unikátní identifikátor předautorizované transakce. amount decimal Částka včetně desetinné části, která má být deponována. Musí být rovna nebo menší než původní předautorizovaná částka. Návratové hodnoty: Metoda vrací kód v závislosti na stavu transakce: Hodnota Popis 0 Operace proběhla v pořádku. 1 Finanční transakci pro dané merchantOrderId se nepodařilo zaúčtovat, protože platnost předautorizace vypršela. 2 Chybné uživatelské jméno nebo heslo. 3 Konto není aktivní. 4 Finanční transakce pro dané merchantOrderId neexistuje nebo není typu Platba platební kartou. 5 Chybná částka – chybný číselný formát, je záporná nebo nulová, nebo je větší než částka původní transakce. 6 Systémová chyba. 7 Chyba vstupních parametrů. (nezadaný parametr userName, password nebo merchantOrderId) © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 4.3.6. cancelBlockedTransaction Metoda slouží ke zrušení předautorizované (blokované) platby. Předautorizace bude zrušena a blokovaná částka bude uvolněna zpět ve prospěch účtu zákazníka. Metoda vyžaduje tyto vstupní parametry: Parametr Typ Popis userName string Uživatelské jméno obchodníka, kterým se hlásí na portál PaySec. password string Heslo pro MAPI. Heslo spojené s uživatelským jménem obchodníka nelze použít. merchantOrderId string Unikátní identifikátor předautorizované transakce. Návratové hodnoty: Metoda vrací kód v závislosti na stavu transakce: Hodnota Popis 0 Operace proběhla v pořádku. 2 Chybné uživatelské jméno nebo heslo. 3 Konto není aktivní. 4 Finanční transakce pro dané merchantOrderId neexistuje. 6 Systémová chyba. 7 Chyba vstupních parametrů. (nezadaný parametr userName, password nebo merchantOrderId) © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 5. Testovací platební brána – uživatelské rozhraní Pro otestování implementace na straně Internetového obchodu nabízí platební řešení PaySec Testovací platební bránu. Testovací platební brána umožňuje provádět všechny transakce stejně jako na ostrém prostředí. Umožňuje veškeré volání webových služeb MAPI. Pro manuální kontrolu transakcí a volání MAPI je k dispozici jednoduchý webový přístup do testovacího PaySec Konta pro obchodníky, kde je možné zkontrolovat provedené transakce včetně jejich správného ověření. Zde jsou k dispozici následující přehledy: Přehled volání rozhranní MAPI Přehled transakcí přijatých přes platební bránu se spárování příslušného volání VerifyTransactionIsPaid V testovacím prostředí má obchodník k dispozici testovací obchodnické PaySec Konto a testovací osobní PaySec Konto. Osobní Konto je přednabité na 50 000 Kč. Při platbě platební metodou PaySec se přihlásí do osobního Konta a z něj pošle na obchodnické Konto částku transakce. Osobní Konto se automaticky pravidelně dobíjí při poklesu zůstatku pod určitou částku. Z obchodnického Konta je možné také realizovat Vratky, kdy se prostředky vrací na zdrojové osobní Konto. Při platbě platební metodou z běžného účtu u ČSOB a Poštovní spořitelny je simulováno rozhraní internetového bankovnictví, ze kterého je platba ihned převedena na PaySec Konto obchodníka. Zde je neomezený limit na platbu. I zde může obchodník provádět vratku na zdrojový běžný účet. Při platbě platební kartou je simulováno rozhraní kartové brány, ze které je platba ihned převedena na PaySec Konto obchodníka. Zde je neomezený limit na platbu. I zde může obchodník provádět vratku na zdrojovou platební kartu. Pro platbu běžným bankovním převodem zatím není k dispozici simulátor. To znamená, že na testovací bráně není možné zaplatit a dokončit transakci offline platby. Proto bude volání VerifyTransactionIsPaid se správnými parametry vracet pro offline platby vždy návratový kód 4 (špatné číslo objednávky nebo neexistující transakce). Cílem testovací platební brány PaySec je umožnit obchodníkovi odladit komunikaci mezi obchodem/portálem a službami PaySec. Speciálně ověřit to, jak jsou jednotlivé transakce ověřovány pomocí MAPI metody VerifyTransactionIsPaid. Zde je nutné, aby byly transakce z PaySec Konta na platební bráně označeny tmavě zelenou barvou. Přehled transakcí na testovací platební bráně najdete po přihlášení na https://testgateway.paysec.cz/Login.aspx v sekci Platební brána – Transakce. 5.1. Přihlášení do uživatelského rozhraní Do uživatelského rozhranní testovací platební brány se lze přihlásit na adrese https://testgateway.paysec.cz/Login.aspx Pro přihlášení použijte přihlašovací jméno a heslo obdržené při od pracovníků prodejního teamu PaySec. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 5.2. Platební brána – menu po přihlášení Po přihlášení se zobrazí uživatelské rozhraní a v horní části obrazovky se zobrazí menu. Na tuto stránku je možné se opět dostat kliknutím na Platební brána – Základní informace Obrázek - menu uživatelského rozhraní Plat. brány 5.3. Platební brána – MAPI Záložka plat. brána-MAPI umožňuje procházet a filtrovat volání rozhraní platební brány MAPI (Merchant API). Jednotlivý řádek přehledu představuje jedno volání metody MAPI. V sloupci Název metody se zobrazuje název volané metody a v sloupci Návratová hodnota je zobrazena hodnota vrácená rozhraním. Filtr v horní části obrazovky umožňuje filtrovat volání MAPI podle období (výsuvné pole Období, pole Datum od a Datum do), volané metody (výsuvné pole Název metody) a návratové hodnoty (pole Návratová hodnota). Jednotlivé položky filtru lze mezi sebou kombinovat. Pro aktivaci filtru stiskněte tlačítko Vyhledat. Kliknutím na číslo v sloupci MapiId zobrazí detail volání Merchant API. Obrázek - přehled volání MAPI © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 5.4. Platební brána – detail volání MAPI Detail volání MAPI se zobrazí po kliknutí na MapiId a obsahuje následující informace: MapiId – unikátní identifikátor volání Název – název metody, která je na Merchant API volána Číslo konta PaySec – číslo konta v systému PaySec Číslo finanční transakce – číslo finanční transakce, ke které se volání MAPI vztahuje. Kliknutím na číslo se zobrazí Detail platby. Datum volání metody – čas kdy byla metoda volána Uživatelské jméno – jméno uživatele, který MAPI volal MerchantOrderId – identifikátor platby z internetového obchodu. Slouží pro identifikaci platby obchodníkovi v internetovém obchodě. Částka – částka volání Název nebo číslo konta Číslo mobilu Datum od Datum do Zpráva pro odesílatele Zpráva pro příjemce Návratová hodnota – návratová hodnota metody Merchant API. Obrázek - detail volání MAPI © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 5.5. Platební brána – Transakce Záložka obsahuje seznam transakcí přijatých přes platební bránu. Pomocí barevného zvýraznění je v přehledu zobrazeno, jak dlouho po vzniku transakce (od zadání a potvrzení platby uživatelem na platební bráně) byl stav transakce ověřen metodou VerifyTransactionIsPaid přes rozhraní MAPI. Barvy mají následující význam: · Šedá barva – transakce byla přes platební bránu byla označena parametrem OrderId, který se používá pro darovací platební tlačítko. U těchto transakcí není možné ověřovat stav finanční transakce pomocí metody VerifyTransactionIsPaid. · Tmavě zelená – transakce přijatá přes platební bránu byla ověřena do 1 minuty od vzniku transakce. U transakcí z Konta PaySec značí pouze tento stav správnou implementaci ověřování transakci. · Světle zelená –transakce přijatá přes platební bránu byla ověřena za více než 1 a méně než 5 minut od vzniku transakce. · Žlutá – transakce přijatá přes platební byla ověřena za více než 5 a méně než 15 minut od vzniku transakce. · Oranžová – transakce přijatá přes platební bránu byla ověřena za více než 15 minut od vzniku transakce. · Červená – transakce přijatá přes platební bránu nebyla vůbec ověřena voláním metody VerifyTransactionIsPaid. Každou transakci je nutné automatizovaně e-shopem ověřit. Implementujte metodu VerifyTransactionIsPaid · Fialová – poslední ověření stavu finanční transakce se nezdařilo, byl vrácen chybový kód Obrázek - barevný filtr transakcí Platební brány Kliknutím na Číslo platby v přehledu zobrazí Detail platby. Filtr přehledu transakcí přijatých přes platební bránu Přehled transakcí je možné filtrovat podle následujících kritérií: Období – zobrazí pouze transakce za poslední týden/2 týdny/měsíc Konta – zobrazí pouze transakce pro zadané konto Datum od/do – zobrazí pouze transakce provedené v zadaném časovém intervalu Částka od/do – zobrazí pouze transakce s částkou v zadaném intervalu Čísla transakce – zobrazí pouze transakci odpovídající zadanému identifikátoru Identifikace platby v internetovém obchodě (MerchantOrderId) – zobrazí pouze transakce založené za účelem zaplacení požadavku přijatého pod identifikátorem MerchantOrderId. Vyhledávání se potvrzuje stiskem tlačítka Zobrazit. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Obrázek - Přehled transakcí Platební brány 5.6. Platební brána – detail transakce Z přehledu plateb na Platební bráně je možné kliknutím na číslo ve sloupci Číslo platby přejít na detail platby. Detail platby obsahuje následující položky: Číslo platby – identifikátor platby Plátce – číslo konta plátce Variabilní symbol platby Typ – typ platby (např. převod z běžného účtu, převod z konta na konto, atd.) Poznámka pro příjemce – zpráva pro příjemce od odesílatele platby Stav – stav platby (např. nová, autorizovaná, odmítnutá, atd.) Obrázek - detail platby © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 6. FAQ – nejčastější dotazy Dotaz Nedaří připojit na testovací bránu PaySec. Odpověď Nejčastější problémem s připojením ke zkušební platební bráně je zabezpečení komunikace šifrováním. Téma je popsáno v kapitole 8.1 Bezpečná komunikace. Dotaz Máme internetový obchod. Opravdu musí být parametr MerchantOrderId unikátní? Jak máme vyřešit situaci, kdy si klient objedná, přistoupí k platbě s číslem objednávky a platba se nepodaří? Pak totiž klient nemá možnost pokusit se o platbu znovu, protože MerchantOrderId již „vyčerpal“ prvním pokusem. Kvůli tomu nemůžeme MerchantOrderId použít pro naše číslo objednávky a ztěžuje nám to párování transakcí a objednávek. Jaké navrhujete řešení? Odpověď Ano, parametr MerchantOrderId musí být jedinečný. Je to z důvodu možnosti později pomocí MAPI ověřit, zda se transakce zaúčtovala úspěšně. V případě platebního tlačítka k ověřování nedochází a parametr OrderId plní obecnou funkci variabilního symbolu (unikátnost není vyžadována). Případ opakovaného pokusu o zaplacení je však možný. Při placení na produkční platební bráně totiž dochází k validaci před tím, než je transakce předána k zaúčtování. Důsledkem toho je fakt, že transakce, která by selhala při účtování, vůbec nevznikne (a „nevyčerpá“ tak MerchantOrderId). Díky tomu pak opakovaný pokus neselže, neboť unikátnost MerchantOrderId nebude porušena. Pokud si však již uživatel na rozcestníku zvolí platební metodu, pak je transakce předána k zaúčtování a MerchantOrderId je tím použito. Dotaz Při platbě v internetovém obchodě je zákazník přesměrován na bránu PaySec. Tam zaplatí a pak je přesměrován zpět. V URL se zpět posílá i parametr "tid", tedy nějaké ID transakce. Dotaz zní: Pokud se transakce povedla, tak je "tid" vždy nenulové? Jinak řečeno, pokud přijde tid>0, dá se to s jistotou považovat za úspěšně provedenou transakci? Odpověď Číslo transakce tid má pouze informativní charakter. Slouží primárně jako informace pro dohledání v případě nějakých kolizí. Podmínka tid>0 pouze říká, zda má cenu ověřovat stav transakce, nebo je již jasné, že neproběhla: Tid = 0 ... Platba byla zamítnuta Tid > 0 ... Není jisté, je potřeba ověřit Skutečný stav transakce zjistíte až po volání webové služby MAPI. Kontrola tid je nedostatečná z důvodu možné modifikace parametru útočníkem - osobou snažící se zfalšovat platbu. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 7. Označení internetového obchodu logem PaySec Internetový obchod se uzavřením smlouvy zavazuje k označení webových stránek logy a bannery platebního řešení PaySec. Kroky k označení stránek e-shopu jsou následující: 1. Implementace PaySec na testovacím rozhraní 2. Úspěšné otestování platby a jejího ověření pracovníkem e-shopu (většinou implementátorem) vůči testovací platební bráně PaySec 3. Zprovoznění platební metody PaySec v ostrém e-shopu 4. Oznámení zprovoznění platební metody PaySec v ostrém e-shopu pracovníkům teamu PaySec 5. Provedení zkušebního nákupu a platby přes ostrou platební bránu PaySec pracovníkem teamu PaySec 6. Provedení vratky ze strany e-shopu 7. V případě úspěchu odsouhlasení implementace ze strany teamu PaySec 8. Obchodník označí e-shop požadovanými logy PaySec (do doby uvedené ve smlouvě) 9. Obchodník oznámí označení e-shopu pracovníkům teamu PaySec 10. Kontrola označení e-shopu logy Paysec pracovníky teamu PaySec 11. Odsouhlasení e-shopu ze strany pracovníků teamu PaySec 12. Zaslání loga e-shopu a krátkého textu o e-shopu pracovníkům teamu PaySec 13. Uvedení loga e-shopu spolu s textem v adresáři PaySec: http://adresar.paysec.cz/ Loga a bannery PaySec jsou ke stažení v sekci Pro obchodníky a v sekci Pro neziskovky na webu PaySec. U označení je nutné použít následující logo PaySec buď ve svislé nebo vodorovné verzi. Logo je dostupné v různých velikostech. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 8. Přílohy 8.1. Bezpečná komunikace Komunikace mezi elektronickým obchodem a systémem PaySec probíhá pomocí zabezpečeného kanálu. Veškerá komunikace je zašifrována tak, aby byla zajištěna integrita (nikdo zprávu nezmění) a důvěrnost (nikdo si zprávu nepřečte) dat. K zašifrování se používají certifikáty. Aby si byl elektronický obchod jistý, že posílá data správnému serveru, musí certifikát ověřit. Ověření většinou provádí hostující prostředí (iis/windows, apache/linux, …) samo. Za tímto účelem existuje v prostředí seznam s důvěryhodnými certifikáty. V okamžiku, kdy internetový obchod zahajuje komunikaci, prokazuje se server svým certifikátem. Prostředí pak samo tento certifikát porovná se svým seznamem, a pokud jej najde, komunikace pokračuje. V opačném případě komunikace selže. Typickým symptomem této situace je chyba: Could not establish an encrypted connection because certificate presented by testgateway.paysec.cz has an invalid signature. Pro úplnost je třeba dodat, že ke korektnímu ověření může dojít i jinak. Stačí, když se za určitý server (resp. jeho certifikát) zaváže (digitálně jej podepíše) tzv. certifikační autorita. Certifikační autorita se rovněž identifikuje svým certifikátem, který už pak v seznamu důvěryhodných být musí. 8.1.1. Nastavení serverového certifikátu jako důvěryhodného Operační systémy Windows Pro operační systémy Microsoft Windows je produkční certifikát podepsán GlobalSign CA, která je tzv. Microsoft Trusted. To znamená, že certifikáty podepsané touto CA jsou automaticky považovány za důvěryhodné. V případě, že by tomu tak na Vašem systému nebylo nebo potřebujete komunikovat se zkušební platební bránou, postupujte následovně: 1) Připravte si soubor s certifikátem. Oba certifikáty, testovací i produkční, lze vytvořit z informací uvedených v kapitole 4.2 Zabezpečení komunikace. 2) Klikněte na tlačítko Start – Spustit – pak napište a odešlete: mmc.exe 3) Objeví se okno. Z roletového menu vyberte: File – Add/Remove snap-in (Soubor – přidat nebo odebrat modul snap-in). 4) Klikněte na tlačítko Add (Přidat). 5) Nalistujte položku Certificates (Certifikáty) a potvrďte. 6) Zvolte Computer account (Účet počítače). 7) Potvrďte všechny otevřené dialogy 8) Rozbalte adresářovou strukturu certifikátů v levé části okna 9) Vyvolejte kontextové menu nad Trusted Root Certification Authorities (Důvěrné kořenové certifikační úřady) 10) Vyberte All Tasks – Import (Všechny úkoly - importovat) 11) Nalistujte soubor s příslušným certifikátem a naimportujte jej. Tip: Používáte-li ASP.NET 2.0, lze pouze pro testovací účely toto ověření obejít. Viz kapitola 8.2.4. Jiné operační systémy Doporučujeme prostudovat stránky společnosti GlobalSign, kde je popis instalace certifikátů pro různá prostředí: http://www.globalsign.com/support/root-certificate/domainserversign.html © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 8.2. Příklady volání webové služby MAPI z různých technologií V této kapitole nejprve uvedeme definici SOAP zpráv, které si mezi sebou klient a služba vyměňují. Tato znalost stačí k tomu, aby bylo možno službu volat z široké palety technologií, které v zásadě musí podporovat pouze zaslání textového řetězce přes https protokol. Ukážeme Vám vzorovou implementaci v jazyku C# 2.0, která tento způsob využívá. Jakkoli je volání přímo na úrovni zpráv možné, existují efektivnější způsoby. Uvidíte způsob implementace v technologiích PHP a ASP.NET 2.0. 8.2.1. Definice SOAP zpráv Vstupní SOAP zpráva <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <userName xmlns="http://schemas.mapi.paysec.cz/2008/02">OBCHODNIK123</userName> <password xmlns="http://schemas.mapi.paysec.cz/2008/02">P@SSWORD</password> <merchantOrderId xmlns="http://schemas.mapi.paysec.cz/2008/02">111</merchantOrderId> <amount xmlns="http://schemas.mapi.paysec.cz/2008/02">222</amount> </soap:Body> </soap:Envelope> Nahraďte zvýrazněné hodnoty vlastními. Výstupní SOAP zpráva <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <VerifyTransactionIsPaidResult xmlns="http://schemas.mapi.paysec.cz/2008/02">4</VerifyTransactionIsPaidResult> </s:Body> </s:Envelope> Získejte zvýrazněnou hodnotu. © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 8.2.2. C# 2.0 pomocí SOAP zpráv V tomto případě je využita třída System.Net.HttpWebRequest, pomocí které je zaslána webové službě SOAP zpráva. Tato zpráva musí být poslána metodou POST a odpovědí na ní je opět SOAP zpráva, ze které je následné vyčten návratový kód Merchant API. using using using using using System; System.Net; System.Text; System.IO; System.Xml; namespace GateWayTest { class Program { static string request = @" <soap:Envelope xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xmlns:xsd=""http://www.w3.org/2001/XMLSchema""> <soap:Body> <userName xmlns=""http://schemas.mapi.paysec.cz/2008/02"">obchodnik123</userName> <password xmlns=""http://schemas.mapi.paysec.cz/2008/02"">P@ssword</password> <merchantOrderId xmlns=""http://schemas.mapi.paysec.cz/2008/02"">111</merchantOrderId> <amount xmlns=""http://schemas.mapi.paysec.cz/2008/02"">222</amount> </soap:Body> </soap:Envelope> "; static void Main(string[] args) { HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("https://testmapi.paysec.cz/mapi.svc?wsdl"); webRequest.Headers.Add("SOAPAction", "http://schemas.mapi.paysec.cz/2008/02/ShoppingService/VerifyTransactionIsPaid"); webRequest.ContentType = "text/xml;charset=utf-8"; webRequest.Method = "POST"; byte[] postDataBytes = Encoding.UTF8.GetBytes(request); using (Stream stream = webRequest.GetRequestStream()) { stream.Write(postDataBytes, 0, postDataBytes.Length); } HttpWebResponse res = (HttpWebResponse)webRequest.GetResponse(); StreamReader str = new StreamReader(res.GetResponseStream(), true); XmlDocument xmlResponse = new XmlDocument(); xmlResponse.LoadXml(str.ReadToEnd()); res.Close(); str.Close(); XmlNamespaceManager nsmgr = new XmlNamespaceManager(xmlResponse.NameTable); nsmgr.AddNamespace("ab", "http://schemas.mapi.paysec.cz/2008/02"); XmlNode resultNode = xmlResponse.SelectSingleNode("//ab:VerifyTransactionIsPaidResult", nsmgr); string retVal = resultNode.InnerText; Console.WriteLine("Result code: " + retVal); } } } © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 8.2.3. PHP 5.2.5 V případě PHP lze využít rozšíření php_soap (komunikace s webovými službami) a php_openssl (protokol HTTPS). Tyto rozšíření lze zapnout editací konfiguračního souboru php.ini. Tento soubor musí obsahovat následující dvě řádky. extension=php_soap.dll extension=php_openssl.dll Poté lze s webovou službou komunikovat jako v následujícím příkladu. <?php $paysecMapi = new SoapClient("https://testmapi.paysec.cz/mapi.svc?wsdl"); $resultCode = $paysecMapi->VerifyTransactionIsPaid("obchodnik123", " P@ssword", " 111", " 222"); echo "Result code: $resultCode"; ?> 8.2.4. ASP.NET 2.0 Příklad předpokládá, že jste pro volání webové služby vygenerovali proxy třídu s názvem MerchantAPI.ShoppingService. // Input parameters string username = "obchodnik123"; string password = "P@ssw0rd"; string merchantOrderId = PregeneratedMerchantOrderId; decimal amount = decimal.Parse(Request.QueryString["Amount"]); // Result int verificationResult; // Call Web service MerchantAPI.ShoppingService shoppingService = new MerchantAPI.ShoppingService(); verificationResult = shoppingService.VerifyTransactionIsPaid(username, password, merchantOrderId, amount); // Process result if (verificationResult==0) { // Paid } else { // Not paid yet } © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 Pouze pro testování – nedůvěryhodná CA Potřebujete-li ověřit implementaci v ASP.NET 2.0 na serveru, kde nemáte možnost nainstalovat testovací certifikát, můžete využít níže uvedené implementace. Příklad je vhodný pouze pro testovací účely. Máte-li možnost, volte raději cestu instalace testovacího certifikátu. /// <summary> /// Ověří platbu pomocí MAPI. /// </summary> public void ValidatePayment() { // Vstupni parametry string username = "obchodik123"; string password = "P@ssw0rd"; string merchantOrderId = PregeneratedMerchantOrderId; decimal amount = decimal.Parse(Request.QueryString["Amount"]); // Vysledek int verificationResult; // Nastavení pravidel pro validaci serverových certifikátů. Nastavení je provedeno // obecně pro všechny ServicePoint instance, vzniklé po provedení následující řádky ServicePointManager.ServerCertificateValidationCallback = new RemoteCertificateValidationCallback(myCertificateValidation); // Volani Web service MerchantAPI.ShoppingService shoppingService = new MerchantAPI.ShoppingService(); verificationResult = shoppingService.VerifyTransactionIsPaid(username, password, merchantOrderId, amount); // Zpracovat vysledek if (verificationResult==0) { // Paid } else { // Not paid yet } } /// <summary> /// Tato implementace VŽDY POVOLÍ komunikaci. /// NEPOUŽÍVAT PRO PRODUKČNÍ PROSTŘEDÍ. /// </summary> /// <returns><c>True</c>, pokud se má komunikace povolit. Jinak <c>False</c>.</returns> public bool myCertificateValidation(Object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors) { // Vždy povolí komunikaci!!! return true; } © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 8.2.5. ASP 3.0 – Visual Basic V tomto případě je využit COM objekt MSXML2.XMLHTTP.6.0, pomocí kterého je zaslána webové službě SOAP zpráva. Tato zpráva musí být poslána metodou POST a odpovědí na ní je opět SOAP zpráva, ze které je následné vyčten návratový kód Merchant API. To je realizováno pomocí COM objektu MSXMLl2.DOMDOCUMENT.3.0, který je určen pro práci s XML. <%@ Language="VBScript" %> <%Option Explicit%> <% Dim soapRequest soapRequest = "<soap:Envelope xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xmlns:xsd=""http://www.w3.org/2001/XMLSchema"">" & _ " <soap:Body>" & _ " <userName xmlns=""http://schemas.mapi.paysec.cz/2008/02"">Login</userName>" & _ " <password xmlns=""http://schemas.mapi.paysec.cz/2008/02"">Heslo</password>" & _ " <merchantOrderId xmlns=""http://schemas.mapi.paysec.cz/2008/02"">111</merchantOrderId>" & _ " <amount xmlns=""http://schemas.mapi.paysec.cz/2008/02"">222</amount>" & _ " </soap:Body>" & _ "</soap:Envelope>" Dim xmlhttp Set xmlhttp = server.Createobject("MSXML2.XMLHTTP.6.0") xmlhttp.open "POST", "https://testmapi.paysec.cz/mapi.svc", false xmlhttp.setRequestHeader "Content-Type","text/xml;charset=utf-8" xmlhttp.setRequestHeader "SOAPAction", "http://schemas.mapi.paysec.cz/2008/02/ShoppingService/VerifyTransactionIsPaid" xmlhttp.send soapRequest Dim xml_document Set xml_document = server.Createobject("Msxml2.DOMDocument.3.0") xml_document.loadXML xmlhttp.responseText Response.Write "Result code: " & xml_document.text %> © 2007-2014 Československá obchodní banka, a.s. Příručka pro použití Platební brány PaySec verze 1.20 8.2.6. Python from ZSI.client import Binding from ZSI import TC PAYSEC_USER = "login" PAYSEC_PASS = "password" PAYSEC_MAPI = "https://testmapi.paysec.cz/mapi.svc" """ VerifyTransactionIsPaid """ class VerifyTransactionIsPaidParameters: def __init__(self, merchantOrderId, amount): self.userName = PAYSEC_USER self.password = PAYSEC_PASS self.merchantOrderId = merchantOrderId self.amount = amount class TC_VerifyTransactionIsPaidParameters(TC.SimpleType): def get_formatted_content(self, pyobj): return str(pyobj) def serialize(self, elt, sw, pyobj, name=None, orig=None, **kw): ns = "http://schemas.mapi.paysec.cz/2008/02" el = elt.createAppendElement(ns, self.serialize_text_node(el, sw, el = elt.createAppendElement(ns, self.serialize_text_node(el, sw, el = elt.createAppendElement(ns, self.serialize_text_node(el, sw, el = elt.createAppendElement(ns, self.serialize_text_node(el, sw, "userName") pyobj.userName) "password") pyobj.password) "merchantOrderId") pyobj.merchantOrderId) "amount") pyobj.amount) return None typecode = TC_VerifyTransactionIsPaidParameters() class VerifyTransactionIsPaidResult: typecode = TC.Integer("VerifyTransactionIsPaidResult") def VerifyTransactionIsPaid(merchantOrderId, amount): SOAPAction = "http://schemas.mapi.paysec.cz/2008/02/ShoppingService/VerifyTransactionIsPaid" params = VerifyTransactionIsPaidParameters(merchantOrderId, amount) b = Binding(url=PAYSEC_MAPI) b.Send(PAYSEC_MAPI, None, params, soapaction=SOAPAction) return b.Receive(VerifyTransactionIsPaidResult) if __name__ == "__main__": print VerifyTransactionIsPaid("ABCDEF", 256.00) © 2007-2014 Československá obchodní banka, a.s.