2.2 Implementační manuál PayU pro developery www.payu.cz
Obsah 1. Úvod 2. Od registrace po spuštění provozu platební brány 2.1 Začínáme, testujeme 2.2 Aktivace e-shopů 2.3 Jak vypadá akvizice e-shopů developera? 2.4 Jak probíhá proces platby prostřednictvím platební brány Payu? 2.5 Co je potřeba zajistit na straně developera 2.6 Šablona pro platby procesované prostřednictvím platební brány Payu 2.7 Zásady pro umístění PayU v nákupním košíku 2.8 Povinné podmínky spolupráce 2.9 Propagace platební brány PayU developerem 3. Implementace PayU 3.1 Obecné informace 3.2 Termíny a ustálené výrazy používané v aplikaci 3.3 Integrace s PayU 3.3.1 Konfigurační data 3.3.2 URL adresy aplikace PayU a dostupné procedury 3.3.3 Kódování 3.3.4 Formát dat 3.3.5 Vytvoření nové platby 3.4 Výměna informací o transakcích 3.4.1 Oznámení změny statusu transakce Obchodu 3.4.2 Rozeznávání statusu transakce 3.4.3 Přijetí platby 3.4.4 Zamítnutí platby 3.4.5 Status dokončení operace 3.5 Struktura návratových adres UrlPositive a UrlNegative 3.6 Kontrolní součty MD5 3.6.1 Kontrolní součet parametrů předávaných do nové platby 3.7 Testování 4. Vzhled platební brány PayU na e-shopu 4.1 Vizualizace a popis platebních metod 4.2 Implementace 4.3 Nákupní proces a uživatelsky přívětivá implementace 4.4 Optimalizace nákupního procesu 4.5 Navigace a vizualizace 4.6 Rychlost a konverze 4.7 Edukace zákazníků a marketing 5. Povinné parametry implementace 6. Přílohy Příloha 1 Typy plateb Příloha 2 Statusy transakcí Příloha 3 Přechody mezi statusy transakce Příloha 4 Kódy chyb Příloha 5 Ukázka php skriptu, který zjišťuje stav transakce Příloha 6 PayU šablony (templates) Příloha 7 Ukázka implementace PayU Příloha 8 Kontakty Příloha 9 Případová studie Příloha 10 Změny v manuálu podle verzí 3 4 5 6 7 8 8 9 10 11 12 15 16 16 17 17 17 17 18 18 23 23 24 27 27 27 29 30 31 32 33 34 34 35 35 35 36 37 38 40 41 42 43 45 46 50 51 52 53 57 2
Úvod 1 PayU je nejrychleji rostoucí poskytovatel on-line plateb v České republice. Je českou verzí úspěšné služby, která funguje v Evropě již od r. 2005. Využívá jedinečné know-how a několikaletou zkušenost z e-commerce trhu ve střední a východní Evropě. Společnost PayU Czech Republic, s.r.o. byla založena v roce 2011 technologickou společností Naspers, která působí na on-line trhu v USA, Číně, Brazílii, Africe, Rusku nebo Polsku a mnoha dalších zemích včetně České republiky. Díky tomuto silnému mezinárodnímu zázemí nabízí PayU kompletní platební služby spojené se zpracováním transakcí, přináší inovativní technologie, bezpečnost a kontinuální vývoj služeb. Cílem PayU je neustále přinášet rychlé a bezpečné platební řešení, které umožní zjednodušovat proces platby pro nakupující a přispívat tak k zvyšování konverze na prodejních platformách. Tato příručka má usnadnit developerům implementaci platební brány PayU. V několika jednoduchých krocích je zde vysvětleno jak se do PayU registrovat, jak probíhá technická integrace a jaké jsou možnosti vizualizace nabízených platebních metod. Cílem této příručky je dát návod k co nejlepší implementaci platební brány PayU. Ta je předpokladem k tomu využít všech vlastností a funkcí, které Vám PayU na Vaši obchodní platformu přináší. Příručka je složena z šesti barevně odlišených částí. Každá část přináší ucelený set informací o konkrétní oblasti implementace nebo práce se systémem PayU. 3
Od registrace 2 po spuštění provozu platební brány 4
Praktický průvodce implementací platební brány PayU. Manuál obsahuje popis klíčových situací developera při práci s PayU, které následují po uzavření smlouvy. 2 2.1 Začínáme, testujeme Co se děje na straně developera Registrace na www.payu.cz kvůli zřízení testovacího účtu. Co zajišťuje PayU Zřízení PayU účtu. Založení testovacího SHOPu a POSu v PayU účtu. Implementace podle technické dokumentace v tomto manuálu. Provedení testovací platby. Aktivace testovací platby. Kontrola úspěšné testovací platby, nákupního procesu a umístění PayU v něm. 5
2 2.2 Aktivace e-shopů Co se děje na straně developera Vytvořit stránku na webu developera s informacemi o PayU, na tuto URL budou klienti developera směřováni. Co zajišťuje PayU Kontrola na straně PayU Obchodní zástupce Vložit do této stránky odkazy na automaticky registrační proces, pomocí kterého budou s klienty zpracovávány smlouvy. Dodání vzoru návratových adres obchodnímu zástupci PayU. (Ve vzoru se bude měnit pouze doména e-shopu). Vytvoření webové aplikace se zabezpečeným přístupem pro PayU. Jedná se o jednoduchý formulář obsahující pole pro IČO, číslo POSu (pos_id) a konfigurační klíče POSu (key1, key2 a pos_auth_key), potřebné pro pozdější propojení plateb u jednotlivých e-shopů na PayU. Automatická implementace a zprovoznění plateb přes PayU na e-shopu. Vložení klíčů Zákaznický servis PayU Finální kontrola Obchodník PayU Smlouva uzavřena Platební brána PayU naimplementována Testovací platba provedena Nákupní proces schválen obchodníkem PayU 6
2 2.3 Jak vypadá akvizice e-shopů developera? a. b. c. d. Developer informuje prostřednictvím svých komunikačních kanálů e-shopy o možnostech a výhodách online plateb nabídka na aktivaci platební brány PayU. Zájemci jsou směřováni na stránku s odkazy do automatického registračního procesu na stránkách developera. Po vyplnění základních údajů se klientovi zobrazí provizní nabídka a posléze může uzavřít smlouvu. V případě větších klientů se zobrazí zpráva, že je budeme do jednoho pracovního dne kontaktovat. Následuje AML ověření a v případě větších klientů vyjednání podmínek a podpis smlouvy. e. f. g. h. i. j. V případě větších klientů následuje doručení podepsané smlouvy do sídla PayU. U menších klientů došlo v rámci kroku b. k uzavření elektronické smlouvy. Zákaznický servis PayU založí e-shopu PayU účet a informuje e-shop o přístupových údajích. Následně založí zákaznický servis na PayU účtu e-shopu SHOP a POS. Aktivace platebních metod dle smlouvy. Zákaznický servis PayU se přihlásí do zabezpečeného prostředí developera, kde vyplní IČ, číslo POSu a přístupové klíče. Developer zajistí automatické přijetí a uložení klíčů pro daný e-shop a aktivaci plateb. 7
2.4 Jak probíhá proces platby prostřednictvím platební brány PayU 2 Proces nákupu na internetu se standardně skládá z následujících po sobě jdoucích kroků: 1. 2. 3. 4. 5. 6. 7. Nákupní košík. Výběr adresy pro doručení zboží, způsobu dopravy a platby. V tomto kroku by měly být zobrazeny jednotlivé platební metody, které PayU nabízí. Rekapitulace objednávky. Přesměrování na banku / platební bránu. V případě nezdaru zaslání e-mailu s návratovou URL adresou s výběrem platebních metod, nebo vložit možnost výběru přímo na negativní návratovou adresu. Provedení platby. Přesměrování na správnou či chybnou návratovou adresu, která by měla obsahovat: a) OK Potvrzení objednávky s informací o jejím přijetí a úspěšném zahájení platby v případě správné návratové adresy. b) NOK Potvrzení objednávky s informací o tom, že objednávka byla přijata, ale NEBYLA zaplacena, včetně seznamu dostupných platebních metod pro opětovnou platbu v případě chybné návratové adresy. 2.5 Co je potřeba zajistit na straně developera Správnou prezentaci PayU v šabloně. PayU není platební metoda, a tudíž nemůže být jako platební metoda prezentována. Zákazník nikdy nevybírá PayU, ale vždy platební metodu, kterou PayU zprostředkovává. (např. svou banku, přes kterou bude platit) Uskutečňování plateb prostřednictvím šablony PayU. Odesílání požadavku na platbu do PayU a přesměrování zákazníka na platební bránu okamžitě po potvrzení objednávky zákazníkem. 8
2 2.6 Šablona pro platby procesované prostřednictvím platební brány PayU Platební šablona PayU je poskytována všem developerům a e-shopům ve formě JavaScript kódu. Tento kód je nutné vložit do zdrojového kódu webových stránek tak, jak je popsáno v technické dokumentaci PayU. JavaScriptem je zajištěna jednotná prezentace PayU v platebních šablonách všech e-shopů, které online platby prostřednictvím PayU nabízejí. Pokud dojde k jakékoliv změně v šabloně PayU, bude okamžitě promítnuta ve všech nákupních košících e-shopů stejně. Šablonu lze zároveň přizpůsobit potřebám e-shopů a nastavit si v nákupním košíku na míru její velikost, texty, fonty. Co není možné měnit jsou loga a pořadí platebních metod v šabloně. 9
2 2.7 Zásady pro umístění PayU v nákupním košíku Umístění online platebních metod na prvním místě, další v pořadí následují platební metody jiných poskytovatelů. Pořadí platebních metod: rychlé online převody bank, platba platebními kartami a přes Mobito, ostatní platební metody. Proces výběru platební metody musí být z pohledu kupujícího co nejjednodušší. Po výběru platební metody kupující v ideálním případě už jen potvrdí celou objednávku jediným klikem. Kupující je po potvrzení objednávky přesměrován přes PayU přímo na banku případně jinou platební bránu nezbytnou pro dokončení platby. Developer je povinen poskytnout PayU vzor návratových adres tak, aby bylo možné je použít pro každý e-shop, který používá systém developera a uzavře smlouvu s PayU o poskytování online plateb. V tomto vzoru bude následně upravena doména jednotlivých e-shopů. V administraci developera ani e-shopu není možno zapínat nebo vypínat platební metody PayU. Veškeré informace v administraci developera týkající se PayU podléhají schválení PayU. 10
2 2.8 Povinné podmínky spolupráce Klíčové kroky, které musí být splněny proto, aby mohl developer nabízet řešení s platbami PayU pro své e-shopy: 1. Smlouva s PayU (Developer PayU). 2. Správná implementace platební brány a alespoň 1 uskutečněná (ostrá) transakce na testovacím rozhraní developera. 3. Vytvořená informační stránky o PayU na webu developera, informující o platební bráně nabízených platbách přes PayU, společně s odkazem na automatický registrační proces. 4. Vytvoření odkazu na bod 3 v administračním rozhraní developera (správa e-shopu v sekci plateb). 5. Zajištění formuláře na straně developera dostupného pro zákaznický servis PayU po zalogování (https stránka, login a heslo jen pro PayU), kde bude moci zákaznický servis PayU vkládat informace potřebné ke spuštění plateb. 6. Nastavení automatického zpracování údajů developerem a nastavení do administračního rozhraní e-shopu. 7. Dodání vzorové návratové URL adresy PayU adresy pro oznámení a typu kódování (např. UTF8, WIN-1250 atd.). 8. Dohoda s obchodníkem či zástupcem marketingu PayU na komunikační strategii vůči e-shopům (mailingy, newslettery), případně předání akvizičního seznamu obchodníků (e-shopů) pro kontaktování ze strany PayU. 9. Implementace modulu PayU dle manuálu, autorizace implementace pověřeným pracovníkem PayU. 11
2.9 Propagace platební brány PayU developerem 2 Za účelem jednotné prezentace značky podléhají veškeré výstupy corporate design manuálu skupiny PayU a musejí být odsouhlaseny zástupcem společnosti PayU. V administraci e-shopu je na straně developera povinnost uvádět PayU v sekci plateb jako: Platební brána PayU jednoduché a bezpečné online platby. Pro propagaci a aktivní nabízení online plateb prostřednictvím platební brány PayU může developer využít následující komunikační nástroje a materiály: Logo PayU Webové bannery PayU E-mailing Newsletter Microsite o online platbách Tyto formy propagace může developer využít jak na svém webu, tak při komunikaci směrem ke svým klientům a provozovatelům e-shopů. Další formy propagace a společných marketingových aktivit jsou ze strany PayU vždy vítány a podporovány V případě zájmu o zaslání výše uvedených podkladů kontaktujte svého obchodního zástupce nebo přímo marketing@payu.cz. 12
www.payu.cz Ukázky e-mailingu: 2 13
Ukázky bannerů: 2 14
Implementace 3 PayU 15
3.1 Obecné informace 3 Tento praktický průvodce implementací platební brány PayU obsahuje informace pro technickou integraci s obchodní platformou. 3.2 Termíny a ustálené výrazy používané v aplikaci PayU Aplikace na zpracování plateb. Společnost Společnost používající aplikaci PayU pro příjem plateb od Zákazníků. Obchod Online obchod přijímající platby; jedna Společnost může provozovat několik Obchodů. POS Platební místo (point of sale) zpracovávající obdržené platby; pro daný POS jsou definovány všechny parametry služby; jeden Obchod může provozovat několik POS. Zákazník Osoba vykonávající platbu. UrlPayU URL adresa, na které je nainstalována aplikace PayU: https://secure.payu.com/paygw/ UrlPositive URL adresa aplikace Obchodu, kam bude Zákazník přesměrován po úspěšném zahájení transakce. UrNegative URL adresa aplikace Obchodu, kam bude Zákazník přesměrován po neúspěšném zahájení transakce. UrlOnline URL adresa aplikace Obchodu, kam budou zasílány oznámení o změně statusu platby prostřednictvím metody POST. 16
3.3 3.3.1 Integrace s PayU Konfigurační data 3 V aplikaci PayU může mít každý Obchod několik POS. Pro každý POS mohou být definovány následující URL adresy: UrlPositive (Správná návratová adresa), UrlNegative (Chybná návratová adresa) a UrlOnline (Adresa pro oznámení). PayU přiděluje každému vytvořenému POSu sadu konfiguračních klíčů, která se skládá z identifikátoru POSu (pos_id), řetězců kódů key1 a key2 (viz kapitola 3.6) a autorizačního klíče (pos_auth_key). Všechny tyto údaje jsou dostupné v uživatelském rozhraní PayU po vytvoření POSu. Uvedené konfigurační klíče můžete nalézt po kliknutí na: Moje obchody > Název obchodu > Seznam POS > Název POSu 3.3.2 URL adresy aplikace PayU a dostupné procedury URL adresa aplikace PayU se tvoří tímto způsobem: URL = UrlPayU/Kodovani/NazevProcedury kde UrlPayU základní adresa aplikace PayU, tj. https://secure.payu.com/paygw/ Kodovani jedna z následujících hodnot: ISO, UTF, WIN NazevProcedury jedna z následujících hodnot: NewPayment, Payment/get, Payment/confirm, Payment/cancel 3.3.3 Kódování V závislosti na znakové sadě, kterou používá aplikace Obchodu, volí Obchod kódování znaků také při odkazování na procedury PayU: název v PayU použité kódování ISO ISO-8859-2 UTF UTF-8 WIN Windows-1250 17
3.3.4 Formát dat 3 Pro následující procedury: Payment/get, Payment/confirm a Payment/cancel může být níže uvedeným způsobem specifikován také formát odesílaných údajů. URL = UrlPayU/Kodovani/NazevProcedury/Format Format může nabývat hodnot xml nebo txt. Výchozí hodnotou je xml. 3.3.5 Vytvoření nové platby Zjednodušeně probíhá platba prostřednictvím systému PayU způsobem, který je zobrazen na níže uvedeném schématu: 7. PayU informuje e-shop o změně statusu transakce PayU 3. E-shop zasílá do PayU formulář nové platby E-shop 1. Výběr zboží/služby na stránkách e-shopu 2. Výběr platební brány 6. Banka informuje PayU o provedení platby Banka 4. Zákazník je přesměrován do banky, kde zaplatí 5. Po provedení platby je zákazník přesměrován zpět na stránku e-shopu K vytvoření nové platby je na webovou stránku Obchodu potřeba umístit formulář, který přesměruje Zákazníka na PayU na proceduru NewPayment (seznam procedur PayU viz kapitola 3.3.2). Doporučuje se použití metody POST; není-li to možné, lze použít také metodu GET. 18
Parametry nové platby jsou následující: 3 parametr povinné pole typ dat popis pos_id ano INT hodnota, kterou přidělilo PayU pos_auth_key ano STR {7,7} hodnota, kterou přidělilo PayU session_id ano STR {1,1024} ID platby musí být pro každou transakci jedinečné amount ano NUM {1,10} částka v haléřích pay_type ano ENUM desc ano STR {1,50} definice zvolené platební metody, jednotlivé hodnoty jsou uvedeny v Příloze 1 ve sloupci název krátký popis objevuje se Obchodu ve výpisech transakcí order_id ne STR {1,1024} číslo objednávky desc2 ne STR {0,1024} libovolná informace first_name ano STR {0,100} jméno last_name ano STR {0,100} příjmení street ne STR {0,100} ulice street_hn ne STR {0,10} číslo popisné street_an ne STR {0,10} číslo orientační city ne STR {0,100} město post_code ne STR {0,20} PSČ country ne STR {0,100} kód krajiny zákazníka (2 písmena) dle ISO-3166 https://www.iso.org/obp/ui/#iso:code:3166:cz email ano STR {0,100} e-mailová adresa phone ne STR {0,100} language ano ENUM client_ip ano STR {7,15} js ne ENUM ( 0, 1 ) telefonní číslo, je možné zadat několik čísel oddělených čárkami kód jazyka dle ISO-639 http://www-01.sil.org/iso639-3/ codes.asp?order=639_1&letter=c (aktuálně je možné uvádět buďto kód cs anebo en ) IP adresa zákazníka v následujícím formátu D{1,3}.D{1,3}.D{1,3}.D{1,3} tato hodnota definuje, jestli má prohlížeč zákazníka povolený JavaScript sig ano STR {32} kontrolní součet parametrů odesílaných ve formuláři ts ano STR časová známka použitá na výpočet hodnoty parametru sig Ujistěte se, že nám v rámci parametrů nové platby zasíláte pouze znaky, které existují ve znakové sadě kódování daného POS (obchodním místě v systému PayU). Např. Pokud je v POS nastaveno kódování UTF-8, ale v některém z parametrů zasíláte nějkaký znak nebo znaky, které ve znakové sadě UTF-8 neexistují, bude systém v takových případech generovat chybu 103. 19
Ve formuláři nové platby není povinné uvádět parametry obsahující údaje o adrese plátce, pokud je to však možné, doporučujeme tyto parametry používat. Uvádění těchto informací totiž umožňuje jednodušší identifikaci plátce v případě, že je nutné spárovat platbu manuálně. Identifikace plátce má v konkrétních případech nespárování platby vliv na konverzi. Po vytvoření platby bude zákazník metodou GET přesměrován na adresu UrlPositive nebo UrlNegative. Jelikož se může stát, že se zákazník zpátky na webové stránky Obchodu nevrátí (např. zavře-li okno svého prohlížeče dříve, než může dojít k přesměrování), informace získané prostřednictvím těchto URL adres nejsou závazné a není možné na jejich základě vyvozovat žádné závěry ohledně výsledných statusů plateb. 3 Pozor! Někdy může dojít k tomu, že Zákazník omylem zvolí nevhodnou platební metodu (např. vybere banku, ve které nevlastní účet, rozhodne se pro platbu kartou, kterou ale nemá u tu chvíli u sebe atp.). Chybu si Zákazník často uvědomí až ve chvíli, kdy je přesměrován na stránku banky či zprostředkovatele karetních transakcí. V takové chvíli se Zákazník často pokusí vrátit o krok nazpět s použitím příslušného tlačítka svého internetového prohlížeče a následně zvolit jinou platební metodu. V těchto případech je nutné zajistit, aby před tím, než je na PayU odeslán nový požadavek typu NewPayment, byla vygenerována nová hodnota parametru session_id (a to navzdory tomu, že z pohledu Obchodu jde stále o jednu a tutéž objednávku). Vytvoření nového session_id je nezbytné, jelikož před přesměrováním Zákazníka do banky vytváří systém PayU transakční záznam, který obsahuje také tento parametr. Opakované použití stejné hodnoty session_id způsobí v systému chybu, která vede k zamítnutí transakce. Před odesláním požadavku typu https://secure.payu.com/paygw/encoding/newpayment je tak nutné zajistit, aby použité session_id bylo jedinečné také v těch případech, kdy Zákazník změnil zvolenou metodu platby pro realizaci téže objednávky. Jednoduchým mechanismem, zajišťujícím jedinečnost hodnoty parametru session_id, může být např. propojení interního čísla objednávky z příslušného Obchodu s časovým razítkem vygenerovaným s milisekundovou přesností (session_id = order_id + - + časové razítko). K vytvoření platebního formuláře je zapotřebí standardní HTML formulář s příslušnými atributy (viz parametry nové platby uvedené výše). Proměnné hodnoty, které jsou požadovány k vytvoření platebního formuláře, mohou být staženy prostřednictvím požadavku na vzdálený server PayU. 20
XML soubor je možné ze systému PayU načíst z tohoto místa: 3 UrlPayU/Encoding/xml/pos_id/KK/paytype.xml Jednotlivé parametry mají následující význam: UrlPayU Encoding pos_id KK základní adresa aplikace PayU jedna z následujících hodnot: ISO, UTF, WIN hodnota, kterou přidělilo PayU, číslo (ID) POSu první dva znaky z klíče Key1 Příklad XML souboru: <?xml version= 1.0 encoding= UTF-8?> <paytypes> <paytype> <type>c</type> <name>payment card</name> <enable>true</enable> <img>https://secure.payu.com/paygw/images/paytype/on-c.gif</img> <min>1.01</min> <max>4000.0</max> </paytype> <paytype> <type>m</type> <name>mtransfer</name> <enable>true</enable> <img>https://secure.payu.com/paygw/images/paytype/on-m.gif</img> <min>0.5</min> <max>999999.99</max> </paytype>... </paytypes> 21
Tento soubor obsahuje atributy, které se mohou v průběhu času měnit, proto ho není možné používat stále, ale je potřeba jej pravidelně obnovovat (s doporučenou frekvencí jednou za hodinu). 3 Po stažení XML souboru jej aplikace Obchodu může zpracovat za účelem vytvoření platebního formuláře. Příklad: <form action= https://secure.payu.com/paygw/utf/newpayment method= POST name= payform > <input type= hidden name= pos_id value= 12345 > <input type= hidden name= pos_auth_key value= wq2io3q > <input type= hidden name= session_id value= 1234565 > <input type= hidden name= amount value= 1000 > <!--php, js nebo jiný jazyk, který na základě údajů ze staženého XML souboru vytvoří záznam definující hodnotu parametru pay_type--> <input type= hidden name= desc value= Payment description > <input type= hidden name= client_ip value= 123.123.123.123 > <input type= hidden name= js value= 0 > <input type= hidden name= email value= example@example.cz > <input type= hidden name= first_name value= Petr > <input type= hidden name= last_name value= Novák > <input type= hidden name= language value= cs > <input type= hidden name= ts value= 251013105655 > <input type= hidden name= sig value= 9075ed67df1c3a4e5686ee7bbb78ad64 > <input type= submit value= Paywith PayU.cz > </form> <scriptlanguage= JavaScript type= text/javascript > <!-- document.forms[ payform ].js.value=1; --> </script> Platební formulář by měl být vytvořen v souladu s aktuálními Obchodními podmínkami a dalšími platnými smlouvami. 22
3.4 3.4.1 Výměna informací o transakcích Aplikace Obchodu je povinna ověřovat kontrolní součty přenášených informací. Oznámení změny statusu transakce Obchodu Každá změna statusu transakce se oznamuje aplikaci Obchodu. Na danou adresu UrlOnline pošle PayU požadavek POST včetně následujících parametrů: 3 pos_id session_id ts hodnota, kterou přidělilo PayU, identifikátor (ID) POSu hodnota zadaná Obchodem při vytvoření platby časová známka, hodnota potřebná k ověření kontrolního součtu sig kontrolní součet přenášených informací (viz kapitola 3.6) sig_ext sig_ext_order interní údaj systému PayU interní údaj systému PayU Hodnota sig počítá následujícím vzorcem: sig = md5(pos_id + session_id + ts + key2) Zpráva o změně statusu transakce neobsahuje žádné další informace. Podrobnosti transakce a její současný status MUSÍ být přečten a analyzován aplikací Obchodu mechanismy popsanými v kapitole 3.4.2. Po obdržení zmíněného požadavku MUSÍ aplikace Obchodu poslat v odpovědi nazpět řetězec OK. Pokud aplikace PayU obdrží jinou odpověď než tuto, uloží se odpověď do databáze a oznámení o změně statusu transakce se považuje za nedoručené. Aplikace Obchodu by měla počítat se situacemi, kdy je oznámení týkající se jedné transakce odesláno několikrát navzdory tomu, že se status transakce nezměnil. Odpověď OK by měla být standardně odeslána na každé takto opakovaně přijaté oznámení. Na konkrétní POS bývá v jednu chvíli zasílán vždy jeden požadavek POST, může ale dojít také k odeslání několik požadavků stejnému POS najednou. 23
Oznámení se posílají okamžitě po změně statusu transakce. Jestliže aplikace Obchodu nepotvrdí přijetí oznámení požadovaným způsobem, bude oznámení zasláno aplikaci Obchodu znovu v těchto časových periodách: 3 pokus prodleva 0-10 1 minuta 11-15 3 minuty 16-20 5 minut 21-25 10 minut 26-50 15 minut 51-75 30 minut 75-99 60 minut >=100 odesílání zastaveno 3.4.2 Rozeznávání statusu transakce Pro čtení aktuálního stavu transakce je nutné prostřednictvím metody POST vyvolat proceduru Payment/get (seznam procedur PayU viz kapitola 3.3.2) s následujícími parametry: pos_id session_id ts hodnota, kterou přidělilo PayU, identifikátor (ID) POSu hodnota zadaná Obchodem při vytvoření platby časová známka, hodnota potřebná k ověření kontrolního součtu sig kontrolní součet přenášených informací (viz kapitola 3.6) Hodnota sig se v tomto případě počítá následujícím vzorcem: sig = md5(pos_id + session_id + ts + key1) 24
V odpovědi obdrží aplikace Obchodu následující informace: 3 Formát txt : status: OK trans_id: 7 trans_pos_id: 1 trans_session_id: 417419 trans_order_id: trans_amount: 200 trans_status: 5 trans_pay_type: t trans_pay_gw_name: pt trans_desc: Platba pro shop.cz trans_desc2: trans_create: 2012-12-21 10:39:52 trans_init: 2012-12-21 10:41:03 trans_sent: 2012-12-21 10:41:44 trans_recv: trans_cancel: trans_auth_fraud: 0 trans_ts: 1094205761232 trans_sig: b6d68525f724a6d69fb1260874924759 Formát xml : <?xml version= 1.0 encoding= UTF-8?> <response> <status>ok</status> <trans> <id>7</id> <pos_id>1</pos_id> <session_id>417419</session_id> <order_id></order_id> <amount>200</amount> <status>5</status> <pay_type>t</pay_type> <pay_gw_name>pt</pay_gw_name> <desc>platba pro shopcz</desc> <desc2></desc2> <create>2012-12-21 10:39:52</create> <init>2012-12-21 10:41:03</init> <sent>2012-12-21 10:41:44</sent> <recv></recv> <cancel></cancel> <auth_fraud>0</auth_fraud> <ts>1094205828574</ts> <sig>a95dc2145079b16a3668175279c35736</sig> </trans> </response> 25
Co se týče údajů, které posílá zpátky PayU, počítá se hodnotu sig následujícím vzorcem: 3 sig = md5(pos_id + session_id + order_id + status + amount + desc + ts + key2) Popis jednotlivých polí oznámení je následující: Základní pole: pole txt pole xml popis Status responsetatus označuje stav zpracování - správně OK trans_id response/trans/id jedinečné id transakce, které přiděluje PayU trans_pos_id response/trans/pos_id id POSu, pro který byla transakce vytvořena trans_session_id trans_order_id response/transession_id response/transorder_id hodnota přidělena aplikací Obchodu při vytvoření transakce hodnota přidělena aplikací Obchodu při vytvoření transakce trans_amount response/transmount aktuální hodnota transakce v haléřích trans_status response/transtatus aktuální stav transakce v souladu s Přílohou 2 trans_pay_type response/trans/pay_type typ platby v souladu s Přílohou 1 trans_pay_gw_name trans_desc trans_desc2 response/trans/pay_gw_ name response/trans/desc response/trans/desc2 název brány vykonávající transakci interní informace aplikace PayU hodnota přidělena aplikací Obchodu při vytvoření transakce hodnota přidělena aplikací Obchodu při vytvoření transakce trans_create response/trans/create datum vytvoření transakce trans_init response/trans/init datum začátku transakce trans_sent response/trans/sent datum, kdy byla transakce předána k vybrání trans_recv response/trans/recv datum přijetí transakce trans_cancel response/trans/cancel datum zrušení transakce trans_auth_fraud response/trans/auth_fraud interní informace aplikace PayU trans_ts response/trans/ts hodnota potřebná na výpočet kontrolního součtu trans_sig response/trans/sig kontrolní součet přenášených informací 26
Další pole pro vybrané metody plateb: 3 testovací platba pole txt pole xml popis add_test response/trans/add_test vždy hodnota 1 add_testid response/trans/add_testid id transakce 3.4.3 Přijetí platby Pro přijetí platby, tj. potvrzení transakce, je potřeba vyvolat proceduru Payment/confirm použitím metody POST a zadat stejné parametry jako v případě rozeznávání statusu transakce (viz kapitola 3.4.2). Platby je nutné přijímat tehdy, je-li funkce automatického přijímání plateb vypnuta (v opačném případě probíhá přijímání plateb automaticky). Přijímat je tímto způsobem možné také platby, které mají status 5 pro přijetí. Alternativně je možné platby přijímat také prostřednictvím uživatelského rozhraní PayU na stránce nazvané Seznam transakcí. 3.4.4 Zamítnutí platby Pro zamítnutí platby je potřeba vyvolat proceduru Payment/cancel a zadat stejné parametry jako v případě rozeznávání statusu transakce (viz kapitola 3.4.2). Zamítání plateb je používáno tehdy, pokud je funkce automatického přijímání plateb vypnuta. Není-li platba zamítnuta v čase kratším než jaký je čas automatického zrušení platby (viz Příloha 1), dojde ke zrušení automaticky. Zamítat tímto způsobem je možné také platby, které mají status 5 pro přijetí. Platby je možné zamítat také prostřednictvím uživatelského rozhraní PayU, na stránce nazvané Seznam transakcí. 3.4.5 Status dokončení operace Odpovědi, které obdrží aplikace Obchodu po vyvolání procedur Payment/confirm a Payment/cancel vypadají následovně: Správné vykonání formát txt : status: OK trans_id: 7 trans_pos_id: 1 trans_session_id: 417419 trans_ts: 1094206530505 trans_sig: 9da7c868407fedae6f1b6aca9054632b 27
Správné vykonání formát xml : 3 <?xml version= 1.0 encoding= UTF-8?> <response> <status>ok</status> <trans> <id>7</id> <pos_id>1</pos_id> <session_id>417419</session_id> <ts>1094205828574</ts> <sig>a95dc2145079b16a3668175279c35736</sig> </trans> </response> Obdržení statusu OK v těchto případech neznamená, že transakce byla úspěšně potvrzena/zrušena. Tyto odpovědi pouze potvrzují přijetí žádosti ke zpracování. Potvrzení o změně statusu transakce je posíláno zvlášť standardním způsobem prostřednictvím adresy UrlOnline. Co se týče údajů, které posílá zpátky PayU, počítáme hodnotu sig následujícím vzorcem: Chyba formát txt : status: ERROR error_nr: 503 error_message: Chyba formát xml : <?xml version= 1.0 encoding= UTF-8?> <response> <status>error</status> <error> <nr>503</nr> <message></message> </error> </response> sig = md5(pos_id + session_id + ts + key2) 28
3.5 Struktura návratových adres UrlPositive a UrlNegative 3 Po dokončení platby je možné přesměrovat Zákazníka na URL adresu uvedenou v nastavení příslušného POSu. V závislosti na aktuálním statusu transakce je pro toto přesměrování použita buď adresa UrlPositive anebo UrlNegative. Na UrlPositive je Zákazník přesměrován poté, co úspěšně zadá platbu na stránkách svého internetového bankovnictví (v případě tzv. rychlých online převodů) anebo na stránce zpracovatele karetních transakcí (při platbě kartou). Jedná-li se o platbu převodem anebo složenkou, je Zákazník na UrlPositive přesměrován poté, co obdrží informace potřebné k provedení platby. K přesměrování na adresu UrlNegative dojde v případě, že platba není zahájena správně. Návratové adresy UrlPositive a UrlNegative slouží pouze pro informativní účely, na základě přesměrování na tyto adresy tak není možné vyvozovat žádné závěry ohledně výsledných statusů plateb. I v případě přesměrování na UrlPositive může totiž platba zůstat nedokončená (Zákazník např. nemusí mít na účtu dostatek prostředků pro provedení platby; v případě platby převodem anebo složenkou nemusí Zákazník vygenerované platební údaje vůbec použít atd.). Pro zjištění statusu transakce je tak vždy nutné vyvolat proceduru Payment/get (viz kapitola 3.4.2). Informace o aktuálních statusech transakcí je případně možné nalézt také v uživatelském rozhraní PayU. Návratové adresy mohou obsahovat následující konstanty, které jsou po přesměrování nahrazeny odpovídajícími hodnotami dle následující tabulky: konstanta %transid% %posid% %paytype% %sessionid% %amountps% %amountcs% %orderid% %error% popis identifikátor nové transakce vytvořený v aplikaci PayU hodnoty pos_id hodnoty pay_type hodnoty session_id hodnoty částky oddělovač je tečka hodnoty částky oddělovač je čárka hodnoty order_id Číslo chyby dle tabulky (viz Příloha 4), používá se pouze v případě UrlNegative Příklady: http://www.shop.cz/status_ok.html?pos_id=%posid%&session_id=%sessionid% http://www.shop.cz/status_error.html?pos_id=%posid%&session_id=%sessionid%&error=%error% 29