Uživatelská technická dokumentace
Verze 3.0
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Revize
Verze
Datum
Změny
1.0
23. 2. 2010
- vytvoření dokumentu
2.0
7. 6. 2011
- nový obsah kapitoly 3.7 (vytvoření nové platby s použitím šablony PayU)
- hlavičkový papír
2.1
27. 6. 2011
- oprava vzorce pro výpočet kontrolního součtu sig v kapitole 3.8
2.2
29. 6. 2011
- oprava chyby v kapitole 3.7 (dodání „www.“ do URL adres uvedených v příkladech)
2.3
20. 7. 2011
- upřesnění popisu chyby 103 v Příloze 4
- nahrazení českých apostrof anglickými v kapitole 3.7
- úprava řádkování v kapitolách 4.2 a 4.5
2.4
1. 12. 2011
-
prolinkování všech řádků Obsahu s příslušnými kapitolami
oprava chybného odkazu v kapitole 3.2
dodání informace o parametru pos_auth_key do kapitoly 3.1
ú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
2.5
6. 3. 2012
- aktualizace obrázků (ukázek šablon č. 3 a 4) v kapitole 3.7
- úprava příkladových URL adres (odstranění mezer, doplnění chybějících znaků „&“ a
„_“) v kapitole 3.2
- úprava příkladu platebního formuláře v kapitole 3.7 (doplněny parametry „email“,
„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
2.6
26. 4. 2012
- 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
3.0
20. 8. 2012
- ú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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Obsah
1. Obecné informace .................................................................................................................................... 4
2. Termíny a ustálené výrazy používané v aplikaci ......................................................................................... 5
3. Integrace s PayU .......................................................................................................................................... 6
3.1 Konfigurační data ......................................................................................................................................... 6
3.2 Struktura návratových adres UrlPositive a UrlNegative .............................................................................. 6
3.3 URL adresy aplikace PayU a dostupné procedury ........................................................................................ 7
3.4 Kódování ....................................................................................................................................................... 7
3.5 Formát dat ................................................................................................................................................... 8
3.6 Kontrolní součty MD5 ................................................................................................................................... 8
3.7 Vytvoření nové platby .................................................................................................................................. 9
3.8 Kontrolní součet parametrů předávaných do nové platby ......................................................................... 13
4. Výměna informací o transakcích .................................................................................................................... 15
4.1 Oznámení změny statusu transakce Obchodu ............................................................................................ 16
4.2 Rozeznávání statusu transakce .................................................................................................................. 16
4.3 Přijetí platby .............................................................................................................................................. 19
4.4 Zamítnutí platby ........................................................................................................................................ 19
4.5 Status dokončení operace .......................................................................................................................... 19
5. Testování ................................................................................................................................................... 21
Příloha 1 - Typy plateb .................................................................................................................................. 22
Příloha 2 - Statusy transakcí .......................................................................................................................... 23
Příloha 3 – Přechody mezi statusy transakce ................................................................................................. 24
Příloha 4 – Kódy chyb ..................................................................................................................................... 26
Příloha 5 – PayU šablony (temlates) ............................................................................................................... 28
Příloha 6 – Ukázka php skriptu, který zjišťuje stav transakce ...................................................................... 32
Příloha 7 – Doporučená oznámení pro jednotlivé typy plateb ....................................................................... 35
3
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 – 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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
2. Termíny a ustálené výrazy používané v aplikaci
PayU – aplikace na zpracování plateb.
Společnost – společnost používající aplikaci PayU pro příjem plateb od Zákazníků.
Obchod – online obchod přijímající platby; jedna Společnost může provozovat několik Obchodů.
POS – platební místo (point of sale) zpracovávající obdržené platby; pro daný POS jsou definovány všechny
parametry služby; jeden Obchod může provozovat několik POS.
Zákazník – osoba vykonávající platbu.
UrlPayU – URL adresa, na které je nainstalována aplikace PayU: https://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.
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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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é
odpovídajícími hodnotami dle následující 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
6
jsou
po přesměrování nahrazeny
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
%amountCS%
hodnoty částky – oddělovač je čárka
%orderId%
hodnoty order_id
%error%
Číslo chyby dle tabulky (viz Příloha 4), používá se pouze v případě UrlNegative
Příklady:
http://www.shop.cz/status_ok.html?pos_id=%posId%&session_id=%sessionId%
http://www.shop.cz/status_error.html?pos_id=%posId%&session_id=%sessionId%&error=%error%
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:
URL = UrlPayU/Kodovani/NazevProcedury
kde:
UrlPayU
základní adresa aplikace PayU, tj. https://www.payu.cz/paygw/
Kodovani
jedna z následujících hodnot: ISO, UTF, WIN
NazevProcedury
jedna z následujících hodnot: NewPayment, Payment/get, Payment/confirm,
Payment/cancel
3.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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
název v PayU
použité kódování
ISO
ISO-8859-2
UTF
UTF-8
WIN
Windows-1250
3.5 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ů):
sig = md5(pos_id + session_id + value1 + value2 + … + valuen + ts + key)
kde:
pos_id
hodnota, kterou přidělilo PayU
session_id
ID platby – jedinečné pro každou transakci
value1...valuen
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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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í:
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 – musí být pro každou transakci jedinečné
9
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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Č
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
country
ne
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
client_ip
js
ENUM
ano
ne
STR {7,15}
ENUM ( 0, 1 )
sig
ne
STR {32}
ts
ne
STR
kód jazyka dle ISO-639
http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt
(aktuálně je možné uvádět buďto kód „cs“ anebo „en“)
IP adresa Zákazníka v následujícím formátu
D{1,3}.D{1,3}.D{1,3}.D{1,3}
tato hodnota definuje, jestli má prohlížeč Zákazníka povolený
JavaScript
kontrolní součet parametrů odesílaných ve formuláři
č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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
https://www.payu.cz/paygw/Encoding/NewPayment je tak nutné zajistit, aby použité session_id bylo
jedinečné také v těch případech, kdy Zákazník změnil zvolenou metodu platby pro realizaci téže objednávky.
Jednoduchým mechanismem, zajišťujícím jedinečnost hodnoty parametru session_id, může být např. propojení
interního čísla objednávky z příslušného Obchodu s časovým razítkem vygenerovaným s milisekundovou
přesností (session_id = order_id + ’-’ + časové razítko).
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
základní adresa aplikace PayU
Encoding
jedna z následujících hodnot: ISO, UTF, WIN
pos_id
hodnota, kterou přidělilo PayU, číslo (ID) POSu
11
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
KK
první dva znaky z klíče Key1
template:x
identifikátor šablony, kde x znamená číselnou
hodnotu z množiny {3,4,5,6}
ext_calc:y
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='https://www.payu.cz/jsgenerator/js/jquerylatest.js'></script>
<script language='javascript' type='text/javascript'
src='https://www.payu.cz/paygw/UTF/js/pos_id/KK/template:3/ext_calc:1/paytype.js'>
</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='https://www.payu.cz/jsgenerator/js/jquerylatest.js'></script>
<script language='javascript' type='text/javascript'
src='https://www.payu.cz/paygw/UTF/js/pos_id/KK/template:4/ext_calc:1/paytype.js'>
</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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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="hidden" name="email" value="[email protected]">
<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
č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)
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)
13
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
popis
pos_id
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
0 - 10
1 minuta
15
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
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
popis
pos_id
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: 417419
trans_order_id:
trans_amount: 200
trans_status: 5
trans_pay_type: t
trans_pay_gw_name: pt
16
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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“:
<?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á 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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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: 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>
19
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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:
sig = md5(pos_id + session_id + ts + key2)
Chyba – formát „txt“:
status: ERROR
error_nr: 503
error_message:
Chyba – formát “xml”:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>ERROR</status>
<error>
<nr>503</nr>
<message></message>
</error>
</response>
20
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 1
Typy plateb
název
limity transakce
(CZK)
čas automatického
zrušení (dny)
popis
cs
3,00 – 999999,99
10
PLATBA 24 – Česká spořitelna
mp
3,00 – 999999,99
10
mPenize - mBank
kb
3,00 – 999999,99
10
MojePlatba – Komerční banka
rf
3,00 – 999999,99
10
ePlatby pro eKonto - Raiffeisenbank
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
10
Platební karty přes GPE
15,00 – 25000,00
10
Platební karty přes Skrill (bývalé
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
10,00 – 999999,99
10
superCASH (platba přes terminály Sazky)
t
1,00 – 1000,00
1
Testovací platba – je zobrazena stránka
umožňující volit mezi přesměrováním na
UrlPositive a UrlNegative
* U těchto platebních metod je nutné, aby Zákazník realizoval platbu na základě zobrazených pokynů, které
zahrnují číslo bankovního účtu, variabilní symbol, specifický symbol a přesnou částku. Aby měl Zákazník tyto
údaje k dispozici i po opuštění příslušné internetové stránky, je možné aktivovat funkci, která informace
potřebné k provedení platby odešle Zákazníkovi prostřednictvím emailu. Pro aktivaci této funkce na Vašem
Obchodu prosím kontaktujte pracovníky PayU. V případě Vašeho zájmu je u těchto zpráv také možné uvádět
jako odchozí adresu Vámi uvedený email.
22
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 2
Statusy transakcí
status popis
1 nová - new
2 zrušena - cancelled
3 odmítnuta - rejected
4 zahájena - started
5 pro přijetí – awaiting collection
7 vrácena – reject done
99 skončena - ended
888 nesprávný status – prosím, kontaktujte nás
-
Status 1 – „nová“ se objeví ve chvíli, kdy aplikace Obchodu úspěšně vyvolá proceduru NewPayment.
-
Status 2 - “zrušena” se objeví automaticky po určitém počtu dnů (viz Příloha 1) od vytvoření nebo
zahájení transakce (status 1 nebo 4), nedojde-li v tomto termínu k uhrazení platby (prostředky nejsou
převedeny na účet PayU).
-
Status 3 - ”odmítnuta” se objeví v případě, že je “zrušená” transakce (status 2) dodatečně uhrazena
(prostředky jsou převedeny na účet PayU).
Status 3 - ”odmítnuta” se objeví také v případě, když je transakce se statusem 5 - ”pro přijetí”
zrušena a vybraná platební metoda neumožňuje automatické vrácení prostředků Zákazníkovi.
Pokud je transakce se statusem 3 přijata a automatické přijímání plateb je vypnuto, získává transakce
status 5 – „pro přijetí”. Pro dokončení transakce a změnu jejího statusu na 99 – „skončena” je nutné
transakci ještě jednou přijmout.
-
-
Status 4 – „zahájena“ je přechodný stav a nemusí se objevit. Transakce může změnit status na „pro
přijetí” nebo „skončena” (v případě, že je automatické přijímání plateb zapnuto) přímo ze statusu 1 „nová”.
Status 5 – „pro přijetí” se objeví pouze tehdy, je-li možnost automatického přijímání plateb vypnuta.
Obchod by měl přijmout platbu do tolika dnů (přesněji do uplynutí tolikrát 24 hodin), kolik trvá
automatické zrušení transakce (viz Příloha 1). Není-li platba přijata do této doby, je automaticky
zrušena.
Status 7 – „vrácena” se objeví, pokud je transakce se statusem 3 zrušena.
Status 99 – „skončena“ označuje úspěšně skončenou transakci. Jde o konečný, neměnný status
transakce. V okamžiku, kdy je transakci přidělen status 99, může Obchod informovat Zákazníka o tom,
že je jeho platba uhrazena (doporučujeme).
Platby je možné přijímat a rušit pomocí procedur Payment/confirm a Payment/cancel (viz kapitoly 4.3 a 4.4).
Přijímání a rušení plateb je možné provádět také prostřednictvím uživatelského rozhraní PayU, pomocí nástrojů
na stránce „Seznam transakcí“.
23
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 3
Přechody mezi statusy transakce
Je-li automatické přijímání plateb vypnuto:
24
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Je-li automatické přijímání plateb zapnuto:
25
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 4
Kódy chyb
kód popis
100 chybí parametr pos_id
101 chybí parametr session_id
102 chybí parametr ts
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
26
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
27
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 5
PayU šablony (templates)
Šablona č. 3:
28
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Šablona č. 4:
29
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Šablona č. 5:
30
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Šablona č. 6:
31
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 6
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/ke-stazeni.
<?php
// adresy pro server PayU a metodu Payment/get
$server = "www.payu.cz";
$server_script = "/paygw/ISO/Payment/get";
// parametry požadované pro odeslání požadavku
define("PAYU_POS_ID", 123);
define("PAYU_KEY1", "1234567890123456");
define("PAYU_KEY2", "9123456789012345");
// vrací pole s indexy: "code" (číslo statusu transakce nebo false v případě chyby), "message" (popis statusu
transakce nebo popis chyby)
function get_status($parts)
{
// chybné číslo POS ID v odpovědi
if($parts[1] != PAYU_POS_ID)
return array("code" => false, "message" => "incorrect POS number");
// výpočet podpisu pro porovnání se sig odeslaným ze strany PayU
$sig = md5($parts[1].$parts[2].$parts[3].$parts[5].$parts[4].$parts[6].$parts[7].PAYU_KEY2);
// chybný podpis v odpovědi v porovnání s podpisem spočítaným lokálně
if($parts[8] != $sig)
return array("code" => false, "message" => "incorrect signature");
// různé zprávy dle statusu transakce. Popisy jednotlivých statusů jsou uvedeny v technické dokumentaci
switch($parts[5])
{
case 1: return array("code" => $parts[5], "message" => "new");
case 2: return array("code" => $parts[5], "message" => "cancelled");
case 3: return array("code" => $parts[5], "message" => "rejected");
case 4: return array("code" => $parts[5], "message" => "started");
case 5: return array("code" => $parts[5], "message" => "awaiting receipt");
case 6: return array("code" => $parts[5], "message" => "no authorization");
case 7: return array("code" => $parts[5], "message" => "payment rejected");
case 99: return array("code" => $parts[5], "message" => "payment received - ended");
case 888: return array("code" => $parts[5], "message" => "incorrect status");
default: return array("code" => false, "message" => "no status");
}
}
// některé parametry chybějí
if(!isset($_POST["pos_id"]) || !isset($_POST["session_id"]) || !isset($_POST["ts"]) || !isset($_POST["sig"]))
die("ERROR: EMPTY PARAMETERS");
32
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
// obdržené číslo POS ID je jiné, než bylo očekáváno
if($_POST["pos_id"] != PAYU_POS_ID)
die("ERROR: INCORRECT POS ID");
// verifikace obdrženého podpisu
$sig = md5($_POST["pos_id"].$_POST["session_id"].$_POST["ts"].PAYU_KEY2);
// chybný podpis
if($_POST["sig"] != $sig)
die("ERROR: INCORRECT SIGNATURE");
// podpis, který bude odeslán do PayU spolu s požadavkem
$ts = time();
$sig = md5(PAYU_POS_ID.$_POST["session_id"].$ts.PAYU_KEY1);
// příprava řetězce (string) parametrů k odeslání do PayU
$parameters = "pos_id=".PAYU_POS_ID."&session_id=".$_POST["session_id"]."&ts=".$ts."&sig=".$sig;
// určení metody spojení (socket nebo CURL)
$fsocket = false;
$curl = false;
if((PHP_VERSION >= 4.3) && ($fp = @fsockopen("ssl://".$server, 443, $errno, $errstr, 30)))
$fsocket = true;
elseif (function_exists("curl_exec"))
$curl = true;
// odesílání požadavku pomocí socket
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 ([email protected]($fp))
{
$res = @fgets($fp, 1024);
$payu_response .= $res;
}
@fclose($fp);
}
// odesílání požadavku pomocí CURL
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);
33
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
curl_setopt($ch, CURLOPT_POSTFIELDS, $parameters);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$payu_response = curl_exec($ch);
curl_close($ch);
}
// není k dispozici žádná použitelná metoda spojení
else
die("ERROR: No connect method ...\n");
// získávání odpovědi od PayU
$result = false;
if (preg_match("/<trans>.*<pos_id>([0-9]*)<\/pos_id>.*<session_id>(.*)<\/session_id>.*<order_id>(.*)".
"<\/order_id>.*<amount>([0-9]*)<\/amount>.*<status>([0-9]*)<\/status>.*<desc>(.*)<\/desc>.*<ts>".
"([0-9]*)<\/ts>.*<sig>([a-z0-9]*)<\/sig>.*<\/trans>/is", $payu_response, $parts))
$result = get_status($parts);
// rozpoznaný status transakce
if ($result["code"])
{
$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
}
*/
34
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 (everything_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)....
}
?>
35
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Příloha 7
Uvedením konstanty payType v adrese UrlPositive je možné získat informaci o tom, jaký platební kanál
zákazník zvolil (viz kapitola 3.2). 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:
: platební karta, PLATBA 24 (Česká spořitelna), mPeníze (mBank), MojePlatba (Komerční banka), ePlatby pro
eKonto (Raiffeisenbank), GE Money Bank, Volksbank a Fio banka
Oznámení:
: Vaše platba byla úspěšně zadána.
: Vaši platbu jsme přijali ke zpracová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.
36
Download

Uživatelská technická dokumentace Verze 3.0