Uživatelská technická dokumentace. Verze 3.0

Transkript

1 Uživatelská technická dokumentace Verze 3.0

2 Revize Verze Datum Změny vytvoření dokumentu nový obsah kapitoly 3.7 (vytvoření nové platby s použitím šablony PayU) - hlavičkový papír oprava vzorce pro výpočet kontrolního součtu sig v kapitole oprava chyby v kapitole 3.7 (dodání www. do URL adres uvedených v příkladech) upřesnění popisu chyby 103 v Příloze 4 - nahrazení českých apostrof anglickými v kapitole úprava řádkování v kapitolách 4.2 a prolinkování všech řádků Obsahu s příslušnými kapitolami - oprava chybného odkazu v kapitole dodání informace o parametru pos_auth_key do kapitoly úprava zápatí (nahrazení kontaktních informací čísly stránek) - aktualizace doporučených oznámení pro online platební metody v Příloze 7 - rozšíření Přílohy 1 o popis volitelné funkce spojené s platbami typu bt a pt - přidání nového odstavce do kapitoly 3.7 (možnost použití tlačítka zpět Zákazníkem při platbě) - doplnění tabulky o provedených změnách dokumentu aktualizace obrázků (ukázek šablon č. 3 a 4) v kapitole úprava příkladových URL adres (odstranění mezer, doplnění chybějících znaků & a _ ) v kapitole úprava příkladu platebního formuláře v kapitole 3.7 (doplněny parametry , first_name a last_name ) - oprava chyby v příkladu platebního formuláře v kapitole 3.7 (řádek <! nahrazen řádkem <!-- ) - změna času automatického zrušení plateb platební kartou z pěti na deset dnů (Příloha 1) - aktualizace popisu Statusu 5 v Příloze 2 - doplnění hypertextových odkazů do této tabulky oprava popisu chyby 102 v Příloze 4 (parametr t nahrazen správným ts ) - aktualizace ukázkového php skriptu v Příloze 6 (nahrazení funkce eregi funkcí preg_match ) - aktualizace linku odkazujícího na webovou stránku PayU tamtéž - aktualizace loga, odstranění vodoznaku úprava ukázkového php skriptu v Příloze 6, korekce řádku s funkcí preg_match - nahrazení termínu kreditní karta přesnějším termínem platební karta - přidání parametru ext_calc do URL adresy šablony (PayU template), přidání informací o tomto parametru do kapitol 3.7 a 3.8 přidání informací o existenci templatů č. 3 a 4 do kapitoly 3.7 přidání kapitoly 5 (Testování) přidání platby typu cs do tabulky v Příloze 1, úprava popisů některých typů plateb tamtéž snížení minimálního limitu pro platbu typu sc ze 100 na 10 Kč (viz Příloha 1) nová struktura dokumentu, doprovázená rozšířením textu či změnou číslování některých kapitol 2

3 Obsah 1. Obecné informace Termíny a ustálené výrazy používané v aplikaci Integrace s PayU Konfigurační data Struktura návratových adres UrlPositive a UrlNegative URL adresy aplikace PayU a dostupné procedury Kódování Formát dat Kontrolní součty MD Vytvoření nové platby Kontrolní součet parametrů předávaných do nové platby Výměna informací o transakcích Oznámení změny statusu transakce Obchodu Rozeznávání statusu transakce Přijetí platby Zamítnutí platby Status dokončení operace Testování 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 PayU šablony (temlates) Příloha 6 Ukázka php skriptu, který zjišťuje stav transakce Příloha 7 Doporučená oznámení pro jednotlivé typy plateb

4 1. Obecné informace Na základě velkého zájmu o profesionální nástroje pro zpracování plateb za zboží a služby zakoupené na Internetu bychom rádi představili nový produkt platební systém PayU. PayU je systém zaměřený na platformy elektronických obchodů, které vyžadují profesionální platební řešení. PayU nabízí rychlé, bezpečné a jednoduché metody plateb za zboží a služby nabízené na Internetu, přičemž poskytuje uživatelům maximální komfort a pohodlí. Jako výsledek letitých zkušeností a profesionální technické a právní podpory můžeme nabídnout bezkonkurenční systém na zpracování online plateb. 4

5 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: 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. 5

6 3. Integrace s PayU 3.1 Konfigurační data 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.2 Struktura návratových adres UrlPositive a UrlNegative 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, složenkou nebo prostřednictvím metody supercash, 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čena (Zákazník např. nemusí mít na svém účtu dostatek prostředků pro provedení platby; v případě platby převodem, složenkou anebo přes supercash 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 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% 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 6

7 %amountcs% %orderid% %error% 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: Informace o hodnotách výše uvedených konstant mohou být aplikací Obchodu využity mnoha různými způsoby. Podle informací o použitém typu platby (pay_type) je například možné specifikovat oznámení zobrazované Zákazníkovi na adrese URLPositive pro jednotlivé platební kanály (viz Příloha 7). Na základě hodnoty parametru session_id může zase aplikace Obchodu vytvořit Zákazníkovi odkaz na novou platba za tutéž objednávku (ovšem s použitím nové hodnoty session_id, protože ta musí být vždy jedinečná)v případech, kdy původní platba zůstane nedokončena. Číslo chyby (viz Příloha 4)umožňuje zjistit, z jakého důvodu nebyla platba vytvořena (funkci doporučujeme využívat např. ve fázi testování, kdy je jejím prostřednictvím možné velmi rychle nalézt a odstranit příčiny nejčastějších problémů při vytváření nových plateb) atd. Třetí adresou, kterou je možné definovat pro daný POS, je UrlOnline. Na tuto adresu jsou ze strany PayU odesílány oznámení o změně statusu transakce (viz kapitola 4.1). 3.3 URL adresy aplikace PayU a dostupné procedury URL adresa aplikace PayU se tvoří tímto způsobem: kde: URL = UrlPayU/Kodovani/NazevProcedury UrlPayU Kodovani NazevProcedury základní adresa aplikace PayU, tj. jedna z následujících hodnot: ISO, UTF, WIN jedna z následujících hodnot: NewPayment, Payment/get, Payment/confirm, Payment/cancel 3.4 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: 7

8 název v PayU ISO UTF WIN použité kódování ISO UTF-8 Windows Formát dat 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.6 Kontrolní součty MD5 Po každém odeslání požadavku aplikací Obchodu a každém vytvoření odpovědi na straně PayU je vytvořen kontrolní součet MD5, který umožňuje ověřit integritu dat. Kontrolní součty se vytvářejí podle následujícího vzorce ( + znamená operaci spojení řetězců znaků): kde: sig = md5(pos_id + session_id + value 1 + value value n + ts + key) pos_id session_id value 1...value n hodnota, kterou přidělilo PayU ID platby jedinečné pro každou transakci seznam dalších hodnot uvedených v popisech konkrétních metod ts libovolný řetězec znaků, např. aktuální čas v sekundách (doporučujeme) key řetězec znaků, který zná PayU a Obchod V aplikaci PayU jsou ke každému pos_id přiřazeny dvě hodnoty klíče: key1 (Klíč) - používá se pro vytvoření kontrolního součtu, který je odesílán ze strany Obchodu key2 (Druhý klíč) - používá se pro vytvoření kontrolního součtu, který je odesílán ze strany PayU 8

9 3.7 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: 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). Doporučuje se použití metody POST; není-li to možné, lze použít také metodu GET. Parametry nové platby jsou následující: 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 desc ano STR {1,50} krátký popis objeví se zákazníkovi, na výpisech z banky a jiných místech 9

10 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 ano STR {0,100} ová adresa phone ne STR {0,100} telefonní číslo, je možné zadat několik čísel oddělených čárkami language ne ENUM kód jazyka dle ISO (aktuálně je možné uvádět buďto kód cs anebo en ) client_ip ano STR {7,15} IP adresa Zákazníka v následujícím formátu D{1,3}.D{1,3}.D{1,3}.D{1,3} js ne ENUM ( 0, 1 ) tato hodnota definuje, jestli má prohlížeč Zákazníka povolený JavaScript sig ne STR {32} kontrolní součet parametrů odesílaných ve formuláři ts ne STR časová známka použitá na výpočet hodnoty parametru sig Uvádění parametrů sig a ts ve formuláři nové platby není povinné, doporučujeme však tyto parametry používat. Označování nových plateb kontrolními součty představuje mechanismus, jehož využití zvyšuje bezpečnost systému proti napadení zvnějšku a zajišťuje hladký a bezproblémový průběh transakcí. Rozhodneteli se ve formuláři nové platby používat tyto parametry a zvýšit tak bezpečnost Vašich transakcí, kontaktujte prosím pracovníky PayU, kteří provedou potřebné nastavení platebního systému na straně PayU. Povinně není ve formuláři nové platby nutné uvádět ani parametry obsahující údaje o adrese plátce. Rádi bychom však upozornili na to, že použití těchto parametrů velmi zjednoduší proces platby v případě, kdy Zákazník provádí úhradu platební kartou prostřednictvím stránky společnosti Skrill (bývalé Moneybookers). 10

11 Nejsou-li totiž tyto kontaktní údaje obsaženy ve formuláři nové platby, musí je Zákazník před provedením platby vyplnit přímo na stránce Skrillu, což pro něj může představovat zbytečné zdržení a komplikaci. V nejzazším případě může tento požadavek na vyplnění kontaktních údajů vést některé Zákazníky i k tomu, že svou započatou platbu nedokončí. 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 adres nejsou závazné a není možné na jejich základě vyvozovat žádné závěry ohledně výsledných statusů plateb. 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 platební metodu jinou. V těchto případech je nutné zajistit, aby před tím, než je na PayU odeslán nový požadavek typu NewPayment, bylo 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 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). Standardní způsob vytvoření platebního formuláře využívá tzv. PayU šablony (templates). Systém PayU umožňuje výběr ze dvou typů předdefinovaných šablon. Vytvoření formuláře nové platby prostřednictvím těchto šablon je velice jednoduché a může být provedeno ve třech krocích: 1. Vložení JavaScript knihoven do <head> sekce HTML dokumentu 2. Vytvoření jednoduchého formuláře s odpovídajícími parametry 3. Vložení úryvku JavaScriptu do formuláře platby Knihovna JavaScript může být ze systému PayU načtena z této lokace: UrlPayU/Encoding/js/pos_id/KK/template:x/ext_calc:y/paytype.js kde příslušné parametry znamenají následující: UrlPayU Encoding pos_id základní adresa aplikace PayU jedna z následujících hodnot: ISO, UTF, WIN hodnota, kterou přidělilo PayU, číslo (ID) POSu 11

12 KK template:x ext_calc:y první dva znaky z klíče Key1 identifikátor šablony, kde x znamená číselnou hodnotu z množiny {3,4,5,6} informace o tom, jestli do kalkulace hodnoty parametru sig má nebo nemá být zahrnut parametr pay_type: 1 = ano, 0 = ne Parametr template označuje, který typ předdefinované šablony bude použit. V případě potřeby je Obchodu povoleno užívanou šablonu upravit tak, aby vyhovovala jeho specifickým požadavkům. Jakékoliv úpravy šablony musí být schváleny ze strany provozovatele platebního systému PayU. Názvy a loga jednotlivých platebních kanálů a logo PayU není možné odstraňovat ani jakkoliv měnit. Parametr ext_calc označuje, jestli do kalkulace hodnoty parametru sig má být zahrnut parametr pay_type. Pokud je hodnota parametru ext_calc 0, pak parametr pay_type není zahrnutý do kalkulace parametru sig a jeho hodnota není zasílána v podobě parametru pay_type. Pokud je hodnota parametru ext_calc 1, pak parametr pay_type je zahrnutý do kalkulace parametru sig a jeho hodnota v podobě parametru pay_type zasílána je. JavaScript knihovny by měly být umístěny do <head> sekce HTML dokumentu (krok č. 1. uvedený výše) následujícím způsobem: <head> <script language='javascript' type='text/javascript' src=' <script language='javascript' type='text/javascript' src=' </script> </head> V tomto případě bude použita šablona číslo 3 (viz Příloha 5), jelikož parametru definujícímu typ šablony byla přisouzena hodnota 3. Šablona číslo 4 nabízí seznam platebních metod v tzv. drop-down variantě (viz rovněž Příloha 5). Tato šablona je dostupná po vložení následujícího odkazu do pole <head>: <head> <script language='javascript' type='text/javascript' src=' <script language='javascript' type='text/javascript' src=' </script> </head> Anglická verze šablony číslo 3 má číslo 5, anglická verze šablony číslo 4 je označena číslem 6. Rovněž anglické verze šablon naleznete v Příloze 5. V souladu s krokem 3 uvedeným výše by měl být do platebního formuláře vložen tento úryvek JavaScriptu: <script language='javascript' type='text/javascript'> PlnPrintTemplate(); </script> 12

13 Příklad platebního formuláře s vloženým úryvkem (úryvek je zvýrazněn tučným písmem): <form action=" 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=" "> <input type="hidden" name="amount" value="1000"> <script language='javascript' type='text/javascript'> PlnPrintTemplate(); </script> <input type="hidden" name="desc" value="payment description"> <input type="hidden" name="client_ip" value=" "> <input type="hidden" name="js" value="0"> <input type="hidden" name=" " value="example@example.cz"> <input type="hidden" name="first_name" value="petr"> <input type="hidden" name="last_name" value="novák"> <input type="submit" value="pay with PayU.cz"> </form> <script language="javascript" type="text/javascript"> <!-- document.forms['payform'].js.value=1; --> </script> 3.8 Kontrolní součet parametrů předávaných do nové platby Volitelně může aplikace Obchodu do formuláře nové platby (NewPayment) přidat kontrolní součet všech přenášených parametrů. Označování plateb kontrolními součty není povinné, za účelem zvýšení bezpečnosti transakcí však doporučujeme tuto možnost využívat. Pro vytvoření kontrolního součtu je do formuláře nové platby potřeba přidat další dva parametry: ts sig časová značka, hodnota potřebná na ověření kontrolního součtu, libovolný řetězec znaků, např. aktuální čas v sekundách (doporučujeme) kontrolní součet přenášených informací Hodnota sig se počítá následovním vzorcem: sig = md5(pos_id + pay_type + session_id + pos_auth_key + amount + desc + desc2 + order_id + firs_ name + last_name + street + street_hn + street_an + city + post_code + country + + phone + language + client_ip + ts + key1) 13

14 Není-li daná hodnota přenášena ve formuláři používaném na vytvoření nové platby, použijeme prázdný řetězec znaků. Pokud v okamžiku kalkulace hodnoty parametru sig není známa hodnota parametru pay_type, měl by být parametr ext_calc v URL adrese PayU šablony (viz kapitola 3.7) nastaven na hodnotu 0. Není-li hodnota parametru sig vypočtena správně anebo pokud se hodnoty ostatních přenášených parametrů změní, nová platba se nevytvoří (Zákazník bude přesměrován na adresu UrlNegative s kódem chyby 103). Používání kontrolního součtu tak funguje jako bezpečnostní pojistka, která zajišťuje, že žádná neautorizovaná změna hodnot parametrů platby nezůstane nepovšimnuta. S ohledem na zajištění maximální bezpečnosti transakcí doporučujeme tuto funkci využívat. 14

15 4. Výměna informací o transakcích Aplikace Obchodu je povinna ověřovat kontrolní součty přenášených informací. 4.1 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ů: název pos_id popis hodnota, kterou přidělilo PayU, identifikátor (ID) POSu session_id hodnota zadaná Obchodem při vytvoření platby ts č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 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 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 v tutéž, může ale dojít také k odeslání několik požadavků stejnému POS najednou. Oznámení se posílají okamžitě po změně statusu platby. 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: pokus prodleva minuta 15

16 minuty minut minut minut minut minut >=100 odesílání zastaveno 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) s následujícími parametry: název pos_id popis hodnota, kterou přidělilo PayU, identifikátor (ID) POSu session_id hodnota zadaná Obchodem při vytvoření platby ts č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) V odpovědi obdrží aplikace Obchodu následující informace: Formát txt : status: OK trans_id: 7 trans_pos_id: 1 trans_session_id: trans_order_id: trans_amount: 200 trans_status: 5 trans_pay_type: t trans_pay_gw_name: pt 16

17 trans_desc: Platba pro shop.cz trans_desc2: trans_create: :39:52 trans_init: :42:43 trans_sent: :48:13 trans_recv: trans_cancel: trans_auth_fraud: 0 trans_ts: trans_sig: b6d68525f724a6d69fb 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> :39:52</create> <init> :42:43</init> <sent> :48:13</sent> <recv></recv> <cancel></cancel> <auth_fraud>0</auth_fraud> <ts> </ts> <sig>a95dc b16a c35736</sig> </trans> </response> Co se týče údajů, které posílá zpátky PayU, počítá se hodnotu sig následujícím vzorcem: 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 17

18 trans_session_id response/transession_id hodnota přidělena aplikací Obchodu při vytvoření transakce trans_order_id response/transorder_id 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 response/trans/pay_gw_name název brány vykonávající transakci interní informace aplikace PayU trans_desc response/trans/desc hodnota přidělena aplikací Obchodu při vytvoření transakce trans_desc2 response/trans/desc2 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í Další pole pro vybrané metody plateb: - 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 18

19 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 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í. 4.4 Zamítnutí platby Pro zamítnutí platby je potřeba vyvolat proceduru Payment/cancel a zadate stejné parametry jako v případě rozeznávání statusu transakce (viz kapitola 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í. 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: trans_ts: trans_sig: 9da7c868407fedae6f1b6aca b Správné vykonání 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> <ts> </ts> <sig>a95dc b16a c35736</sig> </trans> </response> 19

20 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: sig = md5(pos_id + session_id + ts + key2) Chyba formát xml : <?xml version="1.0" encoding="utf-8"?> <response> <status>error</status> <error> <nr>503</nr> <message></message> </error> </response> 20

21 5. Testování K otestování implementace platebního systému PayU slouží tzv. testovací platby (typ platby t, viz Příloha 1). Tyto platby se chovají stejně jako skutečné transakce, ovšem s tím rozdílem, že při nich nedochází k manipulaci s žádnými reálnými finančními prostředky. Testovací platby umožňují zkontrolovat integritu údajů předávaných aplikaci PayU ze strany Obchodu. Pomocí testovacích plateb je možné ověřit přesměrování na návratové adresy UrlNegative a UrlPositive, stejně jako komunikaci na UrlOnline. Kromě procedury NewPayment je s testovacími platbami možné provádět také procedury Payment/get, Payment/confirm a Payment/cancel. S použitím testovacích plateb lze vytvářet různé statusy transakcí (viz Příloha 2) a přechody mezi nimi (viz Příloha 3). Při testovacích platbách se nemění zůstatek Obchodu, lze jich proto vytvářet libovolné množství. Dochází-li při vytváření testovacích plateb k přesměrování na UrlNegative, je možné umístěním konstanty %error% do této adresy (viz kapitola 3.2) zjistit číslo chyby. Na základě tabulky umístěné v Příloze 4 je pak možné zjistit příčinu problému a následně problém odstranit. Jelikož testovací platby fungují na stejném principu jako platby skutečné, je v případě jejich bezproblémového fungování možné přistoupit ke spuštění platebního systému PayU v ostrém provozu. 21