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]
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]