Uživatelská technická dokumentace Verze 1.0

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]


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



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



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:



V případě, že je možnost automatického přijetí plateb zapnuta:



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}


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í



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



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í.



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



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


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



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]


1.

Vložení JavaScript knihoven do sekce HTML dokumentu

2.

Vytvoření jednoduchého
s odpovídajícími parametry

3.

Vložení úryvku JavaScriptu do 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 sekce HTML dokumentu (krok č. 1. uvedený výše) následujícím způsobem: <script language='JavaScript' type='text/JavaScript' src='https://www.payu.cz/jsgenerator/js/jquerylatest.js'> <script language='javascript' type='text/javascript' src='https://www.payu.cz/paygw/UTF/js/PosId/KK/template:3/paytype.js'> 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:



Š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 : <script language='JavaScript' type='text/JavaScript' src='https://www.payu.cz/jsgenerator/js/jquerylatest.js'> <script language='javascript' type='text/javascript' src='https://www.payu.cz/paygw/UTF/js/PosId/KK/template:4/paytype.js'> Š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();



Příklad platebního formuláře s vloženým úryvkem (úryvek je zvýrazněn tučným písmem): <script language='JavaScript' type='text/JavaScript'> PlnPrintTemplate();
<script language="JavaScript" type="text/javascript">

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ů.



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



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:



trans_auth_fraud: 0 trans_ts: 1094205761232 trans_sig: b6d68525f724a6d69fb1260874924759 Formát „xml“: <status>OK 7 <pos_id>1 <session_id>417419 200 <status>5 <pay_type>t <pay_gw_name>pt <desc>Platba pro shopcz <desc2> 2010-12-23 10:39:52 2010-12-31 13:42:43 <sent>2010-12-31 13:48:13 0 1094205828574 <sig>a95dc2145079b16a3668175279c35736 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


trans_amount

response/transmount

aktuální hodnota transakce v haléřích



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


trans_desc2

response/trans/desc2


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).



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“: <status>OK 7 <pos_id>1 <session_id>417419 1094205828574 <sig>a95dc2145079b16a3668175279c35736 (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”: <status>ERROR <error> 503 T: 800 227 228 E: [email protected]


<message>



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.



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 ).

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; }



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(".*<pos_id>([09]*).*<session_id>(.*).*(.*).*([09]*).*<status>([0-9]*).*<desc>(.*).*([0-9]*).*<sig>([a-z09]*).*", $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 } */



// 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).... } ?>


Uživatelská technická dokumentace Verze 1.0

Recommend Documents