Uživatelská technická dokumentace
Verze 2.4
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
Verze
Datum
Změny
1.0
23. 2. 2010
- vytvoření dokumentu
2.0
7. 6. 2011
- nový obsah kapitoly 3.5 (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.6
2.2
29. 6. 2011
- oprava chyby v kapitole 3.5 (dodání „www.“ do URL adres uvedených v příkladech)
2.3
20. 7. 2011
- upřesnění popisu chyby 103 v kapitole 2.1
- nahrazení českých apostrof anglickými v kapitole 3.5
- úprava řádkování v kapitolách 3.7.2 a 3.7.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 1
- rozšíření kapitoly 2.4 o popis volitelné funkce spojené s platbami typu „bt“ a „pt“
- přidání nového odstavce do kapitoly 3.5 (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
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 ......................................................................................... 4
2.1 Kódy chyb ..................................................................................................................................................... 4
2.2 Statusy transakcí .......................................................................................................................................... 6
2.2.1 Přechody mezi statusy transakce ......................................................................................................... 6
2.2.2 Další informace o statusech transakce ................................................................................................. 8
2.3 Parametry nové platby ................................................................................................................................ 8
2.4 Typy plateb .................................................................................................................................................. 9
3. Integrace s PayU ........................................................................................................................................ 10
3.1 Konfigurační data ....................................................................................................................................... 10
3.2 Struktura adres UrlPositive, UrlNegative .................................................................................................. 11
3.3 URL adresy aplikace PayU a dostupné procedury ...................................................................................... 11
3.3.1 Kódování ............................................................................................................................................. 12
3.3.2 Formát dat .......................................................................................................................................... 12
3.4 Kontrolní součty MD5 ................................................................................................................................. 12
3.5 Vytvoření nové platby ................................................................................................................................ 13
3.6 Označení parametrů předávaných do nové platby ..................................................................................... 17
3.7 Výměna informací o transakcích ................................................................................................................ 17
3.7.1 Oznámení změny statusu transakce Obchodu .................................................................................... 17
3.7.2 Rozeznávání statusu transakce ........................................................................................................... 18
3.7.3 Přijetí platby ...................................................................................................................................... 21
3.7.4. Zamítnutí platby................................................................................................................................ 21
3.7.5. Status dokončení operace ................................................................................................................. 21
Příloha 1 - doporučená oznámení pro jednotlivé typy plateb………………………………….………………………………….23
Příloha 2 - ukázka php skriptu, který zjišťuje stav transakce…………………….………………………………………………24
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, 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
4
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
5
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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:
6
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:
7
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í
8
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
9
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
* 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.
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) a autorizační
klíč pos_auth_key. 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“
10
„Seznam PoS“
„Název místa“
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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 (viz kapitola 2.1), 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:
11
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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:
12
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
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).
13
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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.
Důležité! 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é situaci se Zákazník obvykle zkusí vrátit o krok zpě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áno nové session_id (a to
navzdory faktu, ž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 systém payu.cz vytváří transakční záznam obsahující
také tento parametr. Opakované použití stejné hodnoty session_id způsobí rozpor v systému, který vyústí v
zamítnutí transakce. Před odesláním požadavky typu https://www.payu.cz/paygw/UTF/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 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). 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 <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
14
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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:
Š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ě:
15
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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>
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>
16
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
17
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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:
18
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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“:
<?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>
19
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
<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
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
20
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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
21
PayU Czech Republic s.r.o.
Danube House, Karolinská 650/1
Praha 8 - Karlín
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>
<message></message>
</error>
</response>
22
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ě 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.
23
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;
}
24
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 ([email protected]($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
}
*/
25
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)....
}
?>
26
Download

Uživatelská technická dokumentace Verze 2.4