Uživatelská technická dokumentace Verze 1.0
Transkript
Uživatelská technická dokumentace Verze 1.0 © 2011 PayU Czech Republic s.r.o. PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín Obsah 1. Obecné informace .................................................................................................................................................... 3 2. Termíny a ustálené výrazy používané v aplikaci .................................................................................................. 3 2.1 Kódy chyb...................................................................................................................................................................... 3 2.2 Statusy transakcí ......................................................................................................................................................... 5 2.2.1 Přechody mezi statusy transakce ..................................................................................................................... 5 2.2.2 Další informace o statusech transakce ............................................................................................................ 7 2.3 Parametry nové platby.............................................................................................................................................. 7 2.4 Typy plateb .................................................................................................................................................................. 8 3. Integrace s PayU ........................................................................................................................................................ 9 3.1 Konfigurační data ........................................................................................................................................................ 9 3.2 Struktura adres UrlPositive, UrlNegative ............................................................................................................ .. 9 3.3 URL adresy aplikace PayU a dostupné procedury ................................................................................................ 10 3.3.1 Kódování ............................................................................................................................................................. 11 3.3.2 Formát dat ......................................................................................................................................................... 11 3.4 Kontrolní součty MD5................................................................................................................................................ 11 3.5 Vytvoření nové platby .............................................................................................................................................. 12 3.6 Označení parametrů předávaných do nové platby .............................................................................................. 15 3.7 Výměna informací o transakcích............................................................................................................................. 16 3.7.1 Oznámení změny statusu transakce Obchodu .............................................................................................. 16 3.7.2 Rozeznávání statusu transakce ....................................................................................................................... 17 3.7.3 Přijetí platby ..................................................................................................................................................... 19 3.7.4. Zamítnutí platby .............................................................................................................................................. 20 3.7.5. Status dokončení operace .............................................................................................................................. 20 Příloha 1 - doporučená oznámení pro jednotlivé typy plateb………………………………………………………………………………22 Příloha 2 - ukázka php skriptu, který zjišťuje stav transakce………………………………………………………………………………23 T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 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, který implementovalo Aukro, s.r.o. - PayU. Je to 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. 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í PayU pro příjem prostředků od Zákazníka. 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í platby. UrlPayU – adresa URL, na které byla nainstalována aplikace PayU https://www.payu.cz/paygw/ UrlPositive – URL adresa aplikace obchodu, kam bude Zákazník přesměrován po úspěšném zahájení transakce. UrNegativel - 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. 2.1 Kódy chyb kód popis 100 chybí parametr pos_id 101 chybí parametr session_id 102 chybí parametr t 103 chybí parametr sig anebo nesprávná hodnota parametru sig 104 chybí parametr desc T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 105 chybí parametr client_ip 106 chybí parametr first_name 107 chybí parametr last_name 108 chybí parametr street 109 chybí parametr city 110 chybí parametr post_code 111 chybí parametr amount 112 nesprávné číslo bankovního účtu 113 chybí parametr email 114 chybí parametr tel. číslo (phone) 200 jiná přechodná chyba 201 jiná přechodná chyba databáze 202 POS tohoto ID je blokován 203 neplatná hodnota pay_type pro dané pos_id 204 zvolený typ platby (pay_type) je dočasně zablokován pro dané pos_id, např. z důvodu servisní odstávky platební brány 205 částka transakce je nižší než minimální hodnota 206 částka transakce je vyšší než maximální hodnota 207 překročena hodnota všech transakcí pro jednoho zákazníka za poslední období 209 neplatný pos_id nebo pos_auth_key 210 částka transakce obsahuje nepovolené haléřové položky 500 neexistující transakce 501 chybí autorizace pro tuto transakci 502 transakce začala dříve 503 autorizace transakce již byla vykonána T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 504 transakce byla dříve zrušena 505 transakce byla dříve přijata 506 transakce byla vybrána 507 chyba při převodu prostředků zpět zákazníkovi 599 nesprávný status transakce, např. není možné přijmout transakci několikrát a jiné – prosím, kontaktujte nás 999 jiná kritická chyba – prosím, kontaktujte nás 2.2 Statusy transakcí status popis 1 nová - new 2 zrušena - cancelled 3 odmítnuta - rejected 4 zahájena - started 5 očekává se potvrzení (pro přijetí) – awaiting collection platba zamítnuta; prostředky byly však od zákazníka přijaty po zrušení transakce nebo nebylo 7 možné převést prostředky zpátky automaticky; takové situace monitoruje a objasňuje tým PayU – returning funds to client 99 platba přijata – skončena - finished 888 nesprávný status – prosím, kontaktujte nás 2.2.1 Přechody mezi statusy transakce V případě, že je možnost automatického přijetí plateb vypnuta: T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín V případě, že je možnost automatického přijetí plateb zapnuta: T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 2.2.2 Další informace o statusech transakce Status 2 - ―zrušena‖ se objeví automaticky po určitém počtu dnů (bod 2.4) po vytvoření nebo zahájení transakce (status 1 nebo 4), pokud není do dané doby uhrazena (žádné prostředky nebudou přijaty na účet PayU) Status 3 - ‖odmítnuta‖ se objeví, když Uživatel u transakce se statusem 5 - ‖očekává se potvrzení‖ – klikne na ―Zrušit‖ a vybraná platební metoda neumožňuje automatické převedení prostředků zákazníkovi. Status 3 - ‖odmítnuta‖ se objeví také v případě, že ―zrušená‖ transakce (status 2) je následně uhrazena (prostředky jsou převedeny na účet PayU). Pokud je transakce se statusem 3 ―odmítnuta‖ následně přijata a status transakce se změní na 5 – „očekává se potvrzení‖, v případě, že je možnost automatického přijímání plateb pro Uživatele vypnuta, je potřeba kliknout znovu na „Přijmout‖ pro dokončení transakce a změnu statusu na 99 – „skončena‖. Status 4 – „zahájena― je přechodný stav a nemusí se objevit. Transakce může změnit status na „očekává se potvrzení‖ nebo „skončena‖ (v případě, že je možnost automatického přijímání plateb pro zapnuta) přímo ze statusu 1 „nová‖. Status 5 – „očekává se potvrzení (pro přijetí)‖ se objeví pouze, když Uživatel deaktivoval možnost „Automatické přijetí‖. Potom by měl Obchod vybrat platbu do 5 dnů (přesněji do uplynutí 5*24 hodin po začátku transakce). Jestliže platba nebude vybrána do této doby, bude automaticky zrušena. Platby se vybírají prostřednictvím metody Payment/confirm nebo prostřednictvím uživatelského rozhraní platformy. Status 7 – „prostředky vráceny zákazníkovi‖ se objeví, když má transakce status 3 „odmítnuta‖ a uživatel klikne na „Zrušit.― 2.3 Parametry nové platby povinné pole typ dat 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} amount ano NUM {1,10} částka v haléřích STR {1,50} krátký popis – objeví se zákazníkovi, na výpisech z banky a jiných místech parametr desc ano popis ID platby – jedinečné pro každou transakci 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í T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín street ne STR {0,100} ulice street_hn ne STR {0,10} domovní číslo street_an ne STR {0,10} číslo bytu city ne STR {0,100} město post_code ne STR {0,20} PSČ STR {0,100} kód krajiny zákazníka (2 písmena) dle ISO-3166 http:www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html ne country email ano STR {0,100} e-mailová adresa phone ne STR {0,100} telefonní číslo, je možné zadat několik čísel oddělených čárkami ne language ENUM client_ip ano ne js STR {7,15} ENUM ( 0, 1 ) sig ne STR {32} ts ne STR kód jazyka dle ISO-639 http:www.ics.uci.edu/pub/ietf/http/related/iso639.txt (currently cs, en) IP adresa zákazníka v nasledují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 kontrolní součet parametrů formuláře zaslaného platformě časová známka použitá na výpočet hodnoty sig V závislosti na metodě platby může být nutné zadat hodnoty definované v tabulce jako nepovinné. Další informace naleznete vedle popisů konkrétních metod plateb v bodě 2.4. 2.4 Typy plateb název limity transakce (CZK) Čas automatického zrušení (dnů) popisy mp 3,00 – 999999,99 10 mPenize kb 3,00 – 999999,99 10 MojePlatba rf 3,00 – 999999,99 10 ePlatby pro eKonto T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín pg 3,00 – 999999,99 10 GE Money Bank pv 3,00 – 999999,99 10 Volksbank pf 3,00 – 999999,99 10 Fio banka c 3,00 – 999999,99 5 Kreditní karty přes GPE 15,00 – 25000,00 5 Kreditní karty přes Moneybookers bt 3,00 – 999999,99 14 Bankovní převod pt 3,00 – 999999,99 14 Převod přes poštu (poštovní poukázkou) sc 100,00 – 999999,99 10 superCASH t 1,00 – 1000,00 1 Testovací platba – zobrazí se formulář, kde bude možné změnit stav transakce Pořadí dostupných platebních kanálů v obchodě by mělo být takové jako v tomto dokumentu. 3. Integrace s PayU 3.1 Konfigurační data V aplikaci PayU může mít každý Obchod několik POS. Obchod uvádí následující údaje pro každý POS: UrlPositive, UrlNegative a UrlOnline. PayU poskytuje Obchodu spolu identifikátor vytvořeného POS, key1 a key2 řetězce kódů (bod 3.4). Tyto údaje jsou dostupné v uživatelském rozhraní PayU po zaregistrování příslušných služeb. Všechny požadované konfigurační údaje naleznete v „Moje obchody― „Název obchodu― „Seznam PoS― „Název místa― 3.2 Struktura adres UrlPositive, UrlNegative Po dokončení platby je možné přesměrovat Klienta na URL adresu, kterou uvede Obchod. V závislosti na statusu transakce se použije buď adresa UrlPositive nebo UrlNegative. Návratové adresy slouží pouze pro informativní účely, na jejich základě není možné vykonávat žádná rozhodnutí. T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín Návratové adresy mohou obsahovat následující konstanty, které se zamění za odpovídající hodnoty dle této tabulky: konstanta popis %transId% identifikátor nové transakce vytvořený v aplikaci PayU %posId% hodnoty pos_id %payType% hodnoty pay_type* %sessionId% hodnoty session_id %amountPS% hodnoty částky – oddělovač je tečka %amountCS% hodnoty částky – oddělovač je čárka %orderId% hodnoty order_id %error% Číslo chyby dle tabulky (bod 3.4), používá se pouze v případě UrlNegative * typ platby – na základě této informace lze specifikovat oznámení zobrazené na adrese URLPositive pro jednotlivé platební kanály (viz Příloha 1) 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% 3.3 URL adresy aplikace PayU a dostupné procedury URL adresa aplikace PayU se tvoří následovným způsobem: URL = URLpayu.cz/ Kodovani / NazevProcedury kde: Urlpayu.cz základ adresy aplikace PayU 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 T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 3.3.1 Kódování V závislosti na znakové sadě, kterou používá aplikace Obchodu, by se mělo vybrat příslušné kódování 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 3.3.2 Formát dat Pro následovné procedury: Payment/get, Payment/confirm, Payment/cancel můžeme také uvést formát na odesílání dat dle tohoto vzorce: URL = URLpayu.cz/ Kodovani / NazevProcedury /Format kde Format může být jedna z hodnot: „xml‖ nebo „txt‖; výchozí hodnotou je ―xml‖. 3.4 Kontrolní součty MD5 Po každém odeslání příkazu a vytvoření odpovědi PayU, je vytvořen kontrolní součt MD5, který umožňuje ověřit integritu dat. Kontrolní součty se používají následovně („+― znamená operaci spojení řetězce znaků): sig = md5(pos_id + session_id + value1 + value2 + ::: + valuen + ts + key) kde: pos_id hodnota, kterou přidělilo PayU session_id identifikátor platby – jedinečný pro každého zákazníka value1...valuen seznam dalších hodnot uváděných při popise konkrétních metod T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín ts libovolný řetězec znaků, doporučuje se aktuální čas v sekundách key řetězec, který zná PayU a Obchod V aplikaci PayU existují dvě hodnoty klíče přiřazené k danému pos_id: key1 key2 - klíč, který se používá během kontroly kontrolního součtu odeslaného Obchodem klíč, který se používá na vytvoření kontrolního součtu k odeslaní danému Obchodu 3.5 Vytvoření nové platby Zjednodušeně probíhá platba prostřednictvím systému PayU tak, jak je zobrazeno na schématu uvedeném níže: K vytvoření nové platby je nutné umístit příslušný formulář na webovou stránku, který přesměruje zákazníka na PayU na proceduru NewPayment (bod 3.3). Doporučuje se použít metodu POST; není-li to možné, můžete použít metodu GET. Seznam parametrů a jejich popis naleznete v bodě ( bod 2.3). Po dokončení platby bude zákazník přesměrován na adresu UrlPositive nebo UrlNegative metodou GET. Může se stát, že se zákazník nevrátí zpět na aplikaci Obchodu, a právě proto informace přenesené těmito adresami nejsou závazné a není možné na jejich základě vykonávat rozhodnutí týkající se plateb. Standardní způsob vytvoření platebního formuláře využívá tzv. PayU šablony (templates). 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: T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 1. Vložení JavaScript knihoven do <head> sekce HTML dokumentu 2. Vytvoření jednoduchého <form> s odpovídajícími parametry 3. Vložení úryvku JavaScriptu do <form> platby Systém PayU umožňuje výběr ze dvou typů předdefinovaných šablon. Knihovna JavaScript může být ze systému PayU načtena z této lokace: URLpayu.cz/Encoding/js/PosId/KK/template:x/paytype.js kde příslušné parametry znamenají následující: URLpayu.cz Základní adresa aplikace PayU Encoding Jedna z následujících hodnot: ISO, UTF, WIN PosId Identifikátor (číslo) POSu KK První dva znaky z klíče Key1 Template:x Identifikátor šablony, kde x znamená číselnou hodnotu z množiny {3,4} 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. 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='https://www.payu.cz/jsgenerator/js/jquerylatest.js'></script> <script language='javascript' type='text/javascript' src='https://www.payu.cz/paygw/UTF/js/PosId/KK/template:3/paytype.js'> </script> </head> V tomto případě bude použita šablona číslo 3, jelikož parametru definujícímu typ šablony byla přisouzena hodnota 3. Šablona číslo 3 vypadá takto: T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín Šablona číslo 4 nabízí seznam platebních metod v tzv. drop-down variantě. Tato šablona je dostupná po vložení následujícího odkazu do pole <head>: <head> <script language='JavaScript' type='text/JavaScript' src='https://www.payu.cz/jsgenerator/js/jquerylatest.js'></script> <script language='javascript' type='text/javascript' src='https://www.payu.cz/paygw/UTF/js/PosId/KK/template:4/paytype.js'> </script> </head> Šablona číslo 4 vypadá následovně: 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(); T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín </script> Příklad platebního formuláře s vloženým úryvkem (úryvek je zvýrazněn tučným písmem): <form action="https://www.payu.cz/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"> <script language='JavaScript' type='text/JavaScript'> PlnPrintTemplate(); </script> <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="submit" value="Pay with PayU.cz"> </form> <script language="JavaScript" type="text/javascript"> <!— document.forms['payform'].js.value=1; --> </script> 3.6 Označení parametrů předávaných do nové platby Volitelně může aplikace Obchodu přidat kontrolní sumu všech parametrů přenesených na formulář nové platby (NewPayment). Chcete-li využít tuto možnost, do formuláře je potřeba přidat další dva parametry: ts časová značka, hodnota potřebná na ověření kontrolního součtu, libovolný řetězec, např. čas v sekundách sig 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 +email + phone + language + client_ip + ts + key1) 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ů. T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín Nebyla-li hodnota sig správně vypočtena nebo se hodnoty jiný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. 3.7 Výměna informací o transakcích Aplikace Obchodu je povinna kontrolovat kontrolní součty přenášených informací. 3.7.1 Oznámení změny statusu transakce Obchodu Každá změna statusu transakce se oznamuje aplikaci Obchodu. Na danou adresu UrlOnline se pošle požadavek POST včetně následujících parametrů: název popis pos_id identifikátor PoS 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í - bod (bod 3.4) kde se hodnota sig počítá následujícím vzorcem: sig = md5(pos_id + session_id + ts + key2) Při zaslání zprávy o změně statusu transakce tato neobsahuje žádné informace. Podrobnosti transakce a její současný status MUSÍ být přečten a analyzován aplikací obchodu mechanismy popsanými v bodě ( bod 3.7.2). Po obdržení takového požadavku aplikace Obchodu MUSÍ poslat odpověď s řetězcem „OK―. Při obdržení jiné odpovědi se tato uloží do databáze a oznámení se bude považovat za nepřijaté. Aplikace Obchodu by měla počítat se situacemi, kdy se oznámení týkající se jedné transakce pošle několikrát se stejným statusem. Pro každé opakované oznámení by měla být odeslána také odpovídající odpověď „OK―. Pro POS je zároveň poslán požadavek POST, ale měli byste zvážit možnost poslat několik požadavků stejnému POS najednou. Oznámení se posílají okamžitě po změně statusu platby. Jestliže aplikace Obchodu nevyzvedne oznámení, bude oznámení znovu zasláno po době v souladu tabulkou: pokus prodleva 0 - 10 1 minuta 11 - 15 3 minuty T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 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.7.2 Rozeznávání statusu transakce Pro čtení aktuálního stavu transakce musíme vyvolat proceduru Payment/get bod ( bod 3.3) metodou POST s následujícími parametry: název popis pos_id identifikátor PoS session_id identifikátor transakce ts časová známka, hodnota potřebná k ověření kontrolního součtu sig kontrolní součet přenášených informací - bod ( bod 3.3) kde se hodnota sig počítá následujícím vzorcem: sig = md5(pos_id + session_id + ts + key1) V odpovědi obdržíme následovné stránky s informacemi: 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: 2009-12-23 10:39:52 trans_init: 2009-12-31 13:42:43 trans_sent: 2009-12-31 13:48:13 trans_recv: trans_cancel: T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 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>2010-12-23 10:39:52</create> <init>2010-12-31 13:42:43</init> <sent>2010-12-31 13:48:13</sent> <recv></recv> <cancel></cancel> <auth_fraud>0</auth_fraud> <ts>1094205828574</ts> <sig>a95dc2145079b16a3668175279c35736</sig> </trans> </response> Co se týče údajů, které posílá zpátky PayU, počítáme 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 oznam stavu 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 PoS, pro které byla transakce vytvořena 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 T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín trans_status response/transtatus aktuální stav transakce v souladu s bodem 2.2 trans_pay_type response/trans/pay_type typ platby v souladu s bodem 2.4 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 na 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 oznámení – výsledek funkce md5 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 3.7.3 Přijetí platby Pro přijetí platby, tj. potvrzení transakce, je potřeba zvolit proceduru Payment/confirm užitím metody POST a zadat stejné parametry jako v případě rozeznávání statusu transakce ( bod 3.7.2). T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín 3.7.4. Zamítnutí platby Pro zamítnutí platby vyvoláme proceduru Payment/ cancel a zadáme stejné parametry jako v případě čtení informací transakce (bod 3.7.2). 3.7.5. Status dokončení operace Jako odpověď na procedury Payment/confirm a Payment/cancel obdržíme následující stránky: 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 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>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í akceptování žá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: sig = md5(pos_id + session_id + ts + key2) Chyba – formát „txt“: status: ERROR error_nr: 503 error_message: Error – formát “xml”: <?xml version="1.0" encoding="UTF-8"?> <response> <status>ERROR</status> <error> <nr>503</nr> T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín <message></message> </error> </response> T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín Příloha 1 Uvedením konstanty payType v adrese URLPositive je možné získat informaci o tom, jaký platební kanál zákazník zvolil. Dle této informace lze pak zákazníka různým způsobem informovat o stavu jeho platby na stránce URLPositive. Níže jsou uvedena námi doporučená oznámení pro jednotlivé typy plateb: Pro platební metody: : kreditní karta : mPeníze : MojePlatba : ePlatby Oznámení: : Vaše platba byla úspěšně provedena. : Vaše platba proběhla úspěšně. Pro platební metody: : platba poštovní složenkou : superCASH Oznámení: : Nyní prosím proveďte úhradu platby na základě poskytnutých platebních údajů. Děkujeme. : Poskytnuté platební údaje nyní prosím použijte k uhrazení. Děkujeme. Pro platební metodu: : bankovní převod Oznámení: : Poskytnuté platební údaje použijte prosím k uhrazení. Pokud jste již platbu bankovním převodem provedli, po jejím přijetí bude Vaše objednávka zpracována. T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín Příloha 2 – ukázka php skriptu, který zjišťuje stav transakce (tento skript naleznete také na našich internetových stránkách zde: http://www.payu.cz/raport.phps ). <?php $server = 'www.payu.cz'; $server_script = '/paygw/ISO/Payment/get'; define(PAYU_POS_ID, 123); define(PAYU_KEY1, "1234567890123456"); define(PAYU_KEY2, "9123456789012345"); function get_status($parts){ if ($parts[1] != PAYU_POS_ID) return array('code' => false,'message' => 'incorrect POS number'); //--- chybné číslo POS ID v odpovědi (response) $sig = md5($parts[1].$parts[2].$parts[3].$parts[5].$parts[4].$parts[6].$parts[7].PAYU_KEY2); // --výpočet podpisu (signature) pro porovnání se sig odeslaným ze strany PayU if ($parts[8] != $sig) return array('code' => false,'message' => 'incorrect signature'); //--- chybný podpis (signature) v odpovědi v porovnání s podpisem spočítaným lokálně switch ($parts[5]) { // --- různé zprávy (messages) dle statusu transakce. Popisy jednotlivých statusů jsou uvedeny v technické dokumentaci case 1: return array('code' => $parts[5], 'message' => 'new'); break; case 2: return array('code' => $parts[5], 'message' => 'cancelled'); break; case 3: return array('code' => $parts[5], 'message' => 'rejected'); break; case 4: return array('code' => $parts[5], 'message' => 'started'); break; case 5: return array('code' => $parts[5], 'message' => 'awaiting receipt'); break; case 6: return array('code' => $parts[5], 'message' => 'no authorization'); break; case 7: return array('code' => $parts[5], 'message' => 'payment rejected'); break; case 99: return array('code' => $parts[5], 'message' => 'payment received - ended'); break; case 888: return array('code' => $parts[5], 'message' => 'incorrect status'); break; default: return array('code' => false, 'message' => 'no status'); break; } } if(!isset($_POST['pos_id']) || !isset($_POST['session_id']) || !isset($_POST['ts']) || !isset($_POST['sig'])) die('ERROR: EMPTY PARAMETERS'); //-- některé parametry chybějí if ($_POST['pos_id'] != PAYU_POS_ID) die('ERROR: INCORRECT POS ID'); //--- obdržené číslo POS ID je jiné, než bylo očekáváno $sig = md5( $_POST['pos_id'] . $_POST['session_id'] . $_POST['ts'] . PAYU_KEY2); // --- verifikace obdrženého podpisu (signature) if ($_POST['sig'] != $sig) die('ERROR: INCORRECT SIGNATURE'); //--- chybný podpis (signature) $ts = time(); $sig = md5( PAYU_POS_ID . $_POST['session_id'] . $ts . PAYU_KEY1); // --- podpis (signature), který bude odeslán do PayU spolu s požadavkem (request) $parameters = "pos_id=" . PAYU_POS_ID . "&session_id=" . $_POST['session_id'] . "&ts=" . $ts . "&sig=" . $sig; $fsocket = false; $curl = false; $result = false; if ( (PHP_VERSION >= 4.3) && ($fp = @fsockopen('ssl://' . $server, 443, $errno, $errstr, 30)) ) { $fsocket = true; } elseif (function_exists('curl_exec')) { $curl = true; } T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín if ($fsocket == true) { $header = 'POST ' . $server_script . ' HTTP/1.0' . "\r\n" . 'Host: ' . $server . "\r\n" . 'Content-Type: application/x-www-form-urlencoded' . "\r\n" . 'Content-Length: ' . strlen($parameters) . "\r\n" . 'Connection: close' . "\r\n\r\n"; @fputs($fp, $header . $parameters); $payu_response = ''; while (!@feof($fp)) { $res = @fgets($fp, 1024); $payu_response .= $res; } @fclose($fp); } elseif ($curl == true) { $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://" . $server . $server_script); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_TIMEOUT, 20); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $parameters); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $payu_response = curl_exec($ch); curl_close($ch); } else { die("ERROR: No connect method ...\n"); } if (eregi("<trans>.*<pos_id>([09]*)</pos_id>.*<session_id>(.*)</session_id>.*<order_id>(.*)</order_id>.*<amount>([09]*)</amount>.*<status>([0-9]*)</status>.*<desc>(.*)</desc>.*<ts>([0-9]*)</ts>.*<sig>([a-z09]*)</sig>.*</trans>", $payu_response, $parts)) $result = get_status($parts); if ( $result['code'] ) { //--- rozpoznaný status transakce $pos_id = $parts[1]; $session_id = $parts[2]; $order_id = $parts[3]; $amount = $parts[4]; //--v haléřích $status = $parts[5]; $desc = $parts[6]; $ts = $parts[7]; $sig = $parts[8]; /* TODO: změna statusu transakce v systému shopu */ /* například: if ( $result['code'] == '99' ) { if ( money_are_on_the_account ) { // platba je úspěšná, takže posíláme zpátky OK echo "OK"; exit; } } else if ( $result['code'] == '2' ) { // transakce zrušena, můžeme rovněž transakci zrušit } else { // jiné akce } */ T: 800 227 228 E: [email protected] PayU Czech Republic s.r.o. Danube House, Karolinská 650/1 Praha 8 - Karlín // pokud jsou všechny operace ukončené, posíláme nazpět OK // v opačném případě vygenerujeme error // if ( ewerything_ok ) { echo "OK"; exit; // } else { // // } } else { /* TODO: správa plateb se statusem error */ echo "ERROR: Data error ....\n"; echo "code=" . $result['code'] . " message=" . $result['message'] . "\n"; echo $payu_response; // informace o změně statusu bude z payu.cz odeslána znovu // můžeme zapsat informaci do logů (logs).... } ?> T: 800 227 228 E: [email protected]
Podobné dokumenty
Uživatelská technická dokumentace Verze 3.1
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...
VíceImplementační manuál PayU pro e
Kodovani – jedna z následujících hodnot: ISO, UTF, WIN NazevProcedury – jedna z následujících hodnot: NewPayment, Payment/get, Payment/confirm,
Více6 - TVOYO TV
Kodovani – jedna z následujících hodnot: ISO, UTF, WIN NazevProcedury – jedna z následujících hodnot: NewPayment, Payment/get, Payment/confirm,
VíceDokumentace k API SSLmarketu
1 - 3 pro certifikát THAWTE_SSL_123 1 - 3 pro certifikát THAWTE_WEB_SERVER 1 - 2 pro certifikát THAWTE_WEB_SERVER_EV 1 - 2 pro certifikát THAWTE_WEB_SERVER_WILDCARD 1 - 3 pro certifikát THAWTE_SGC_...
VíceDokumentace k API Balíkobot v1.75 2016-09-14
maximálně 40 znaků a přijímá alfanumerické hodnoty. Data bez tohoto vyplněného parametru nebudou přijata! Pokud odešlete opětovně data s již uloženým eid, nebudou nově příchozí data uložena, o čemž...
VíceAdaptace v algoritmu diferenciáln´ı evoluce
práce velikou trpělivost a která mi v tomto procesu byla neocenitelnou podporou. V neposlednı́ řadě také děkuji mému tatı́nkovi za přečtenı́ práce a pomoc při odstraněnı́ jazykových c...
Vícesocket_create()
Implementován v externí knihovně c-client (Linux) resp. rozšíření php_imap.dll (Windows). Knihovna obsahuje funkce pro vzdálenou správu poštovní schránky. Podporuje protokoly IMAP, POP3 a přístup d...
Víceaukro > obchodní podmínky provozu a užívání
modifikována, platí v ostatním pro vzájemné vztahy mezi Uživatelem a Provozovatelem tyto Obchodní podmínky.
VíceAudioweb.cz Fórum / VMA-I: Peerless SLS 10, SB15NRXC30
Biamp se zesilovači rozdílného výkonu není dobrý nápad. Střední hodnota výkonu v hudbě na středních a vyšších kmitočtech je sice zpravidla nižší než na basech, špičkové hodnoty jsou ale stejné. Nač...
Více