Implementační manuál PayU pro e

2.2
Implementační manuál
PayU pro e-shopy
s využitím šablony
www.payu.cz
www.payu.cz
Obsah
1. Úvod
4
2. Od registrace po spuštění PayU
2.1 Obecné informace
2.2 Popis jednotlivých kroků
5
6
7
3. Implementace PayU
3.1 Obecné informace
3.2 Termíny a ustálené výrazy používané v aplikaci
3.3 Integrace s PayU
3.3.1 Konfigurační data
3.3.2 URL adresy aplikace PayU a dostupné procedury
3.3.3 Kódování
3.3.4 Formát dat
3.3.5 Vytvoření nové platby
3.4 Výměna informací o transakcích
3.4.1 Oznámení změny statusu transakce Obchodu
3.4.2 Rozeznávání statusu transakce
3.4.3 Přijetí platby
3.4.4 Zamítnutí platby
3.4.5 Status dokončení operace
3.5 Struktura návratových adres UrlPositive a UrlNegative
3.6 Kontrolní součty MD5
3.6.1 Kontrolní součet parametrů předávaných do nové platby
3.7 Testování
13
14
14
15
15
15
15
16
16
21
21
22
25
25
25
27
28
29
30
4. Vzhled platební brány PayU na e-shopu
4.1 Vizualizace a popis platebních metod
4.2 Implementace
4.3 Nákupní proces a uživatelsky přívětivá implementace
4.4 Optimalizace nákupního procesu
4.5 Navigace a vizualizace
4.6 Rychlost a konverze
4.7 Funkční šablona
4.8 Edukace zákazníků a marketing
31
32
32
33
33
34
34
35
35
5. Povinné parametry implementace
37
6. Administrace PayU účtu
6.1 Obecné informace
6.2 Uživatelské rozhraní PayU
6.3 Vytvoření Obchodu a POSu
6.4 Transakce
6.5 Vyúčtování, Výběry a Vrácené platby
6.6 Výběry
6.7 Výpisy PDF/CSV/ABO
6.8 Statistiky
6.9 Nastavení oznámení
6.10 Uživatelské účty
39
40
40
41
47
54
56
59
65
67
67
www.payu.cz
7. Přílohy
Příloha 1 – Typy plateb
Příloha 2 – Statusy transakcí
Příloha 3 – Přechody mezi statusy transakce
Příloha 4 – Kódy chyb
Příloha 5 – Ukázka php skriptu, který zjišťuje stav transakce
Příloha 6 – PayU šablony (templates)
Příloha 7 – Ukázka implementace PayU
Příloha 8 – Případová studie
Příloha 9 – Změny v manuálu podle verzí
70
71
72
73
75
76
80
81
83
87
www.payu.cz
Úvod
1
PayU je nejrychleji rostoucí poskytovatel on-line plateb v České republice. Je českou verzí úspěšné
služby, která funguje v Evropě již od r. 2005. Využívá jedinečné know-how a několikaletou zkušenost
z e-commerce trhu ve střední a východní Evropě.
Společnost PayU Czech Republic, s.r.o. byla založena v roce 2011 technologickou společností
Naspers, která působí na on-line trhu v USA, Číně, Brazílii, Africe, Rusku nebo Polsku a mnoha dalších
zemích včetně České republiky.
Díky tomuto silnému mezinárodnímu zázemí nabízí PayU kompletní platební služby spojené se
zpracováním transakcí, přináší inovativní technologie, bezpečnost a kontinuální vývoj služeb. Cílem
PayU je neustále přinášet rychlé a bezpečné platební řešení, které umožní zjednodušovat proces
platby pro nakupující a přispívat tak k zvyšování konverze na prodejních platformách.
Tato příručka má usnadnit e-shopům a partnerům implementaci platební brány PayU. V několika
jednoduchých krocích je zde vysvětleno jak se do PayU registrovat, jak probíhá technická integrace,
jaké jsou možnosti vizualizace nabízených platebních metod, popisuje a vysvětluje funkce
a administraci PayU účtu. Cílem této příručky je dát návod k co nejlepší implementaci platební brány
PayU. Ta je předpokladem k tomu využít všech vlastností a funkcí, které Vám PayU na Vaši obchodní
platformu přináší.
Příručka je složena ze sedmi barevně odlišených částí. Každá část přináší ucelený set informací
o konkrétní oblasti implementace nebo práce se systémem PayU.
4
Od registrace po
spuštění PayU
2
www.payu.cz
2
2.1 Obecné informace
V této části je v jednoduchých krocích popsán proces zavedení platební brány od registrace až po
úspěšné spuštění.
Schéma na obrázku přehledně znázorňuje kroky potřebné k zavedení platební brány PayU na e-shop:
registrace na
www.payu.cz
smlouva
technická
implementace
dle technické
dokumentace
IMPLEMENTACE PLATEBNÍ BRÁNY PAYU
spuštění
ostrého provozu
aktivace
platebních
metod dle
smlouvy
testovací platba
6
www.payu.cz
2
2.2 Popis jednotlivých kroků
Zákazník
(e-shop)
PayU
obchodní oddělení
PayU
zákaznický servis
1. informace o PayU
www.payu.cz
2. registrace,
vytvoření účtu PayU
(login a heslo)
5. login do účtu PayU,
založení SHOP a POS
a implementace
3. zaslání
smlouvy a smluvních
podmínek
6. podpis smlouvy
a zaslání do PayU
AML identifikace
4. aktivace účtu
a testovací platby
7. nastavení nasmlouvaných
platebních metod na založený
POS a aktivace
8. testovací platba
9. žádost o aktivaci
platebních metod
obchodní oddělení
10. ověření testovací platby,
aktivace a kontrola
1.
Webové stránky www.payu.cz obsahují všechny důležité informace týkající se společnosti PayU a jejího
platebního řešení.
2.
Nezávazná registrace na http://registrace.payu.cz/?p=6
Tato registrace slouží k získání informací pro pozdější vytvoření uživatelského účtu a první kontakt. Je
důležité uvést firemní údaje podle obchodního rejstříku a správné kontaktní informace.
3.
Na základě rozhovoru Vám obchodní zástupce připraví nabídku provizních hladin pro jednotlivé typy
plateb. Poté, co jsou Vámi odsouhlaseny, je zaslán návrh smlouvy k podpisu.
4.
Kopie smlouvy je zaslána na zákaznický servis PayU, který zkontroluje údaje ve smlouvě oproti registraci. Pokud údaje souhlasí, může být aktivován PayU účet. Údaje pro první přihlášení Vám budou
zaslány emailem. Následně je možné nastavit potřebné parametry účtu pro implementaci. Zároveň
můžete také využít funkce testovací platby. Správně provedená testovací platba je nedílnou součástí
implementace a bez ní není možné implementaci úspěšně dokončit.
5.
Nyní je možné přihlásit se do účtu PayU a začít s implementací.
7
www.payu.cz
Základní nastavení PayU účtu pro spuštěni implementace:
5.1
2
Nastavení Obchodu (Shopu)
Zvolte „Platby online > Můj Obchod > Přidat obchod“
V prvním kroku je potřeba definovat webovou adresu Obchodu, uvést název Obchodu (případně
také jeho popis) a vybrat požadovanou měnu, ve které budou platby procesovány. Máte-li zájem
zpracovávat ve svém Obchodu platby v eurech, musí být tato skutečnost uvedena ve smlouvě
s PayU.
Pokud máte zájem využívat platební systém PayU na jiné webové adrese, než jaká je uvedena
během registrace, můžete tuto adresu v účtu nastavit. V takovém případě je však nutné, aby byl
vytvořen dodatek ke smlouvě s PayU, kde bude preferována nebo nová webová adresa definována.
8
www.payu.cz
2
5.2
Nastaveni POSu („point of sale“, platební místo)
Pro nastavení hodnot nového POSu je potřeba zadat následující údaje:
a) Název platebního místa
b) Chybová návratová adresa (URL adresa, kam bude plátce přesměrován, pokud se
transakci nepodaří autorizovat)
c) Správná návratová adresa (URL adresa, kam bude plátce přesměrován, pokud se
prvotní autorizace transakce jeví jako úspěšná)
d) Adresa pro oznámení o statusu (URL adresa, kam bude zasílána informace o změně
statusu platby prostřednictvím metody POST)
e) Kódování dat (způsob kódování znaků)
9
www.payu.cz
2
5.3
Konfigurace platebního místa
Jakmile máte přidaný POS, klikněte na něj v seznamu POS. Otevře se vám konfigurace platebního místa. V této konfiguraci jsou některé velmi důležité údaje, které budete potřebovat pro
implementaci platební brány. Jedná se o tyto údaje:
10
www.payu.cz
Po absolvování tohoto kroku můžete začít implementovat, jak je popsáno v kapitole 3 za podmínek
uvedených v kapitole 5, a provádět testovací transakce, jak je popsáno v kapitole 3.7.
6.
2
Zkontrolujte smlouvu od PayU, podepište a odešlete na adresu:
PayU Czech Republic, s. r. o.
Karolinská 650/1
186 00, Praha – Karlín
Dodejte také požadované údaje o identifikaci firmy nebo fyzické osoby podle zákona č. 253/2008 Sb.,
o některých opatřeních proti legalizaci výnosů z trestné činnosti a financování terorismu.
7.
Ve chvíli, kdy obdrží PayU podepsanou smlouvu, přidá zákaznický servis smluvené platební metody
k vašemu obchodnímu místu. V seznamu POS to bude vypadat takto:
11
www.payu.cz
8.
Dokončete implementaci. Proveďte testovací platbu. Nesmí se zobrazovat žádné chybové hlášky.
Seznam chybových hlášek najdete v příloze č. 4. Nahlaste úspěšné zakončení implementace
zákaznickému servisu PayU pomocí kontaktního formuláře ve Vašem PayU účtu:
9.
Pro aktivaci platebních metod uvedených ve smlouvě kontaktujte svého obchodního zástupce v PayU
nebo zašlete požadavek na [email protected].
10.
Na základě Vašeho požadavku na obchodní oddělení a kontroly implementace dle kapitoly 5 Vám budou na Vašem POSu aktivovány jednotlivé platební metody. Můžete začít přijímat platby přes platební
bránu PayU.
2
12
Implementace
PayU
3
www.payu.cz
3.1 Obecné informace
3
Tento praktický průvodce implementací platební brány PayU obsahuje informace pro technickou
integraci s obchodní platformou.
3.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://secure.payu.com/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.
14
www.payu.cz
3
3.3 Integrace s PayU
3.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.3.2
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://secure.payu.com/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.3.3
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:
název v PayU
použité kódování
ISO
ISO-8859-2
UTF
UTF-8
WIN
Windows-1250
15
www.payu.cz
3.3.4
3
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.3.5
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:
7. PayU informuje e-shop
o změně statusu transakce
PayU
E-shop
3. E-shop zasílá do PayU
formulář nové platby
2. Výběr platební brány
v šabloně PayU
1. Výběr zboží/služby
na stránkách e-shopu
Banka
6. Banka
informuje PayU
o provedení
platby
4. Zákazník je přesměrován do banky, kde zaplatí
5. Po provedení platby je zákazník
přesměrován zpět na stránku e-shopu
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.2). Doporučuje
se použití metody POST; není-li to možné, lze použít také metodu GET.
16
www.payu.cz
3
Parametry nové platby jsou následující:
parametr
povinné pole
typ dat
popis
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}
ID platby – musí být pro každou transakci jedinečné
amount
ano
NUM {1,10}
částka v haléřích
pay_type
ano
ENUM
definice zvolené platební metody, jednotlivé hodnoty
jsou uvedeny v Příloze 1 ve sloupci „název“
desc
ano
STR {1,50}
krátký popis – objevuje se Obchodu
ve výpisech transakcí
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Č
country
ne
STR {0,100}
kód krajiny zákazníka (2 písmena) dle ISO-3166
https://www.iso.org/obp/ui/#iso:code:3166:CZ
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
language
ano
ENUM
kód jazyka dle ISO-639
http://www-01.sil.org/iso639-3/
codes.asp?order=639_1&letter=c
(aktuálně je možné uvádět buďto kód „cs“ anebo „en“)
client_ip
ano
STR {7,15}
IP adresa zákazníka v následujícím formátu
D{1,3}.D{1,3}.D{1,3}.D{1,3}
js
ne
ENUM ( 0, 1 )
tato hodnota definuje, jestli má prohlížeč zákazníka
povolený JavaScript
sig
ano
STR {32}
kontrolní součet parametrů odesílaných ve formuláři
ts
ano
STR
časová známka použitá na výpočet hodnoty
parametru sig
Ujistěte se, že nám v rámci parametrů nové platby zasíláte pouze znaky, které existují ve znakové sadě kódování
daného POS (obchodním místě v systému PayU). Např. Pokud je v POS nastaveno kódování UTF-8, ale v některém
z parametrů zasíláte nějkaký znak nebo znaky, které ve znakové sadě UTF-8 neexistují, bude systém v takových
případech generovat chybu 103.
17
www.payu.cz
Ve formuláři nové platby není povinné uvádět parametry obsahující údaje o adrese plátce, pokud je
to však možné, doporučujeme tyto parametry používat. Uvádění těchto informací totiž umožňuje jednodušší identifikaci plátce v případě, že je nutné spárovat platbu manuálně. Identifikace plátce
má v konkrétních případech nespárování platby vliv na konverzi.
3
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
URL 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 jinou platební metodu. V těchto případech je nutné zajistit, aby před tím, než je na PayU
odeslán nový požadavek typu NewPayment, byla 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://secure.payu.com/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
18
www.payu.cz
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
KK
první dva znaky z klíče Key1
template:x
identifikátor šablony, kde x znamená číselnou hodnotu z množiny {3, 5}
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
3
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. 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://secure.payu.com/jsgenerator/js/
jquery-latest.js‘></script>
<script language=‘javascript‘ type=‘text/javascript‘ src=‘https://secure.payu.com/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 6), jelikož parametru definujícímu typ
šablony byla přisouzena hodnota 3. Anglická verze šablony číslo 3 má číslo 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>
19
www.payu.cz
Příklad platebního formuláře s vloženým úryvkem:
3
<form action=“https://secure.payu.com/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=“hidden“ name=“language“ value=“cs“>
<input type=“hidden“ name=“ts“ value=“251013105655“>
<input type=“hidden“ name=“sig“ value=“9075ed67df1c3a4e5686ee7bbb78ad64“>
<input type=“submit“ value=“Paywith PayU.cz“>
</form>
<script language=“JavaScript“ type=“text/javascript“>
<!-document.forms[‚payform‘].js.value=1;
-->
</script>
20
www.payu.cz
3.4 Výměna informací o transakcích
Aplikace Obchodu je povinna ověřovat kontrolní součty přenášených informací.
3.4.1
3
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ů:
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)
sig_ext
interní údaj systému PayU
sig_ext_order
interní údaj systému PayU
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
3.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, může ale dojít také k odeslání několik požadavků stejnému POS najednou.
21
www.payu.cz
Oznámení se posílají okamžitě po změně statusu transakce. 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:
3.4.2
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
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.2) s následujícími parametry:
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)
22
www.payu.cz
V odpovědi obdrží aplikace Obchodu následující informace:
Formát „txt“:
3
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: 2012-12-21 10:39:52
trans_init: 2012-12-21 10:41:03
trans_sent: 2012-12-21 10:41:44
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>2012-12-21 10:39:52</create>
<init>2012-12-21 10:41:03</init>
<sent>2012-12-21 10:41:44</sent>
<recv></recv>
<cancel></cancel>
<auth_fraud>0</auth_fraud>
<ts>1094205828574</ts>
<sig>a95dc2145079b16a3668175279c35736</sig>
</trans>
</response>
23
www.payu.cz
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)
3
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
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í
24
www.payu.cz
3
Další pole – pro vybrané metody plateb:
– testovací platba
3.4.3
pole txt
pole xml
popis
add_test
response/trans/add_test
vždy hodnota „1“
add_testid
response/trans/add_testid
id transakce
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
3.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í“.
3.4.4 Zamítnutí platby
Pro zamítnutí platby je potřeba vyvolat proceduru Payment/cancel a zadat stejné parametry jako
v případě rozeznávání statusu transakce (viz kapitola 3.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í“.
3.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
25
www.payu.cz
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>
3
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>
26
www.payu.cz
3.5 Struktura návratových adres UrlPositive a UrlNegative
3
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 nebo složenkou,
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čená (Zákazník např.
nemusí mít na účtu dostatek prostředků pro provedení platby; v případě platby převodem anebo
složenkou 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 3.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é jsou po přesměrování nahrazeny
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
%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%
27
www.payu.cz
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 . Na základě hodnoty parametru session_id může zase aplikace Obchodu vytvořit Zákazníkovi odkaz na novou
platbu 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.
3
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 3.4.1).
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
28
www.payu.cz
V aplikaci PayU jsou ke každému pos_id přiřazeny dvě hodnoty klíče:
3
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
3.6.1
Kontrolní součet parametrů předávaných do nové platby
Aplikace Obchodu je povinna ve formuláři nové platby (NewPayment) uvádět kontrolní součet všech
přenášených parametrů. Označování nových plateb kontrolními součty představuje mechanismus,
který zvyšuje bezpečnost systému proti napadení zvnějšku a zajišťuje hladký a bezproblémový průběh
transakcí.
Pro vytvoření kontrolního součtu je ve formuláře nové platby nutné uvádět tyto 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ásledujícím vzorcem:
sig = md5(pos_id + pay_type + session_id + pos_auth_key + amount + desc + desc2 + order_id
+ first_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ů.
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.3.5) 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.
29
www.payu.cz
3.7 Testování
3
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.5) 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.
Testovací platební metoda se automaticky deaktivuje v případě, že přes ni nebyla v posledních
třech dnech provedena žádná testovací transakce. Testovací platební metodu lze kdykoliv
libovolně zapínat a vypínat v administraci Vašeho PayU účtu v nastavení POS: Můj obchod –
daný obchod – Seznam POS – daný POS – tabulka dole: Dostupné typy plateb; klikněte u typu
Testovací platba v kolonce Status na Zapnout.
30
Vzhled platební
brány PayU
na e-shopu
4
www.payu.cz
V této části implementačního manuálu se dočtete o tom, jak správně nastavit ukončení nákupu
s PayU, jak správně zobrazovat jednotlivé platební metody.
4
4.1 Vizualizace a popis platebních metod
Společnost PayU dlouhou dobu analyzovala srozumitelnost popisů platebních metod. Výsledkem jsou
následující instrukce, jejichž cílem je dosáhnout rychlé orientace zákazníka při výběru platební metody.
K dispozici jsou 2 možnosti zobrazení platebních metod:
1. Statická JavaScript šablona
2. Dynamická JavaScript šablona (tzv. drop-down varianta)
JavaScript platební šablona PayU umožňuje využít zkušeností PayU v oblasti nákupního procesu
a nabídnout zákazníkům přehledné a vizuálně příjemné zobrazení platebních metod a jejich jasnou
identifikací s logy bank a platebních institucí, které znají.
Obě šablony jsou k dispozici v české a anglické verzi (viz Příloha 6). Příklady implementace šablon na
konkrétních e-shopech jsou zobrazeny v Příloze 7.
4.2 Implementace
Implementace platební šablony PayU obnáší umístění JavaScript kódu do zdroje vašich webových
stránek. Můžete volit mezi statickou a rozbalovací šablonou podle toho, která se bude více hodit do
vašeho nákupního procesu. Platební šablona umožňuje výběr platební metody zákazníkem na stránce
e-shopu, uložení vybraných dat a odeslání zákazníka přímo do banky. E-shop může umístit šablonu
do některé části nákupního procesu, poté je možno nechat zákazníka přejít na další kroky nákupního
procesu jako je např. potvrzení zadané objednávky apod.
Přesný návod, jak implementovat JavaScript šablonu PayU, naleznete v kapitole 3.3.5.
Možnosti úprav
Platební šablonu je možno upravit pomocí CSS stylů. Je možné měnit šířku šablony, barevné pozadí,
barvy a styl textů. Není možno měnit popis platebních metod, obrázky, pořadí platebních metod,
patičku PayU ani počet platebních metod na řádku.
Doporučujeme, pokud to bude možné, ponechat pozadí šablony bílé nebo jen velmi světlé barvy. Čím
tmavší barvu zvolíte, tím větší je možnost, že obrázky a použité prvky šablony budou tzv. okousané
a šablona nebude působit profesionálním dojmem. Může to ovlivnit důvěryhodnost plateb a následně
konverzi vašeho e-shopu.
V případě vlastního zobrazení platebních metod (bez využití šablony) dodržujte tyto pravidla:
1. Platební metody prezentujte v oddělených celcích a to následovně:
a. platební tlačítka a standardní bankovní převod
b. platební karta a mobito
c. platba složenkou
32
www.payu.cz
2. V případě, že kromě platebních metod zprostředkovaných platební bránou PayU máte
naimplementované / zobrazené jiné platební metody, zobrazujte tyto taktéž odděleně.
To znamená platební metody PayU odděleně od ostatních platebních metod.
4
3. Jako dělící znak může posloužit linka nebo prostor mezi jednotlivými skupinami platebních
metod.
4. Platební metody PayU musí být vždy prezentovány s následujícími symboly:
a. PayU – Bezpečné a rychlé platby – bannery ke stažení na stránce
http://www.payu.cz/ke-stazeni
b. V případě využití platebních karet – bezpečnostní loga ke stažení na stránce
http://www.payu.cz/ke-stazeni
5. Platební tlačítka jednotlivých bank nazývejte „rychlé bankovní převody“
6. U každé platební metody je nutné zobrazit příslušné logo a název platební metody tak,
jak jsou zobrazeny v šabloně PayU (viz Příloha 6).
4.3 Nákupní proces a uživatelsky přívětivá implementace
Podle některých studií online nákupního chování až 75 % kupujících opustí e-shop, aniž za zboží
zaplatí. Než totiž zákazník v e-shopu zboží koupí a zaplatí, je nucen proklikat se či projít celou řadou
mnohdy zbytečných úkonů.
Na vině je špatně nastavené ukončení nákupního procesu – takzvaný checkout. E-shop zákazníkovi
často nevědomě komplikuje cestu k dokončení nákupu, potvrzení objednávky a platbě. Proces bývá
zdlouhavý, nepřehledný, e-shop chce po zákazníkovi celou řadu věcí – nutí jej do registrace, vyžaduje
vyplnění osobních údajů. Správně nastavený checkout v kombinaci s okamžitým placením zboží
přitom výrazně přispívá k vyšší konverzi nákupu a tedy ke zvýšení objemu prodeje. Konverzí nákupu
rozumíme potvrzení objednávky a zaplacení zboží.
4.4 Optimalizace nákupního procesu
Celý nákupní proces by měl být ideálně nastaven tak, aby vedl k jedinému cíli: úspěšnému dokončení
transakce, a tedy k zaplacení zboží.
Obecně platí zásada, čím je proces intuitivnější a rychlejší, tím je menší pravděpodobnost, že jej
zákazník předčasně opustí.
33
www.payu.cz
Zjednodušení nákupního procesu vyžaduje optimalizaci tří základních klíčových prvků: navigace,
vizualizace a rychlosti.
4
4.5 Navigace a vizualizace
Zákazník má dnes při nakupování spousty příležitostí, jak vybrat pro něj tu nejlepší nabídku. Využívá
možnosti srovnávat zboží, třeba na Heureka.cz. Často proto během nákupu e-shop opouští, aby
porovnal parametry, ceny, reference a kvalitu různých obchodů. Proto je velmi důležité poskytnout
nakupujícímu co nejvíce informací přímo v e-shopu během nákupu a provést jej nákupním košíkem
(checkoutem) co nejrychleji.
Ideální checkout by měl mít maximálně čtyři kroky. Odbavení zákazníka na jedné stránce má určitě
vyšší konverzi, ale pouze pokud se v celém procesu dokáže zákazník dobře orientovat. Nutností
je navigační lišta, výrazná tlačítka pro pokračování, nebo možnost košík opustit a vrátit se zpět
k předchozímu kroku. Velkou výhodou pro zákazníka je možnost se vrátit přímo na popis produktu
nebo možnost srovnat podobné produkty přímo v nákupním košíku.
Z pohledu nakupujících má e-shop vždy větší věrohodnost, jestliže spolupracuje se známými
a důvěryhodnými institucemi. Jakákoliv loga bank, bezpečnostních systémů, certifikátů
a poskytovatelů platebních metod reprezentujících tuto kredibilitu jsou vždy pro e-shop přínosem,
a proto je ideální je mít přímo jako součást procesu dokončení nákupu. Zvyšuje to pocit bezpečí
a důvěru k obchodu.
Neméně důležitým prvkem vizualizace jsou fotografie. Kvalitní a dostatečně detailní fotografie
kupovaného produktu můžou snížit míru opuštění až o 20 %. Nejčastější důvod opuštění e-shopu
bez dokončení nákupu je však neúměrně vysoké poštovné. Pokud není z jakýchkoliv důvodů možné
cenu poštovného snížit, snažte se prezentovat jeho předpokládanou výši hned na začátku nákupního
procesu.
4.6 Rychlost a konverze
Pro zrychlení celého nákupního procesu je dobré se soustředit na odstranění nadbytečných kroků
a bariér, které jej zákazníkovi znesnadňují. Sem patří například nutnost registrace a zadávání osobních
informací pro nákup. Umožnění nákupu bez registrace je zajímavým způsobem jak zvýšit počet
dokončených a zaplacených objednávek. Čím rychleji zákazníka provedeme nákupním košíkem, tím
vyšší konverze nákupu dosáhneme.
Snad nejvíce podceňovaným a přitom nejlépe dostupným způsobem pro optimalizaci nákupního
procesu jsou jednoduché a rychlé platby. Pro české prostředí jsou relativně novým nástrojem, přitom
však klíčovým pro vyšší konverzi nákupu. Na rozdíl od dobírky nebo standardního bankovního převodu
totiž zákazník před zaplacením neopouští e-shop.
K objednávce i platbě dochází v rámci jednoho procesu: zákazník prochází e-shopem od rozhodnutí
koupit až po zaplacení v krátkém časovém úseku a samotná platba v případě rychlých on-line plateb
netrvá déle než pár sekund. Naopak v případě dobírky nebo standardního bankovního převodu se
může stát, že si zákazník nákup rozmyslí anebo nakoupí u konkurence. Čím jednodušší je odbavení
a platby, tím vyšší konverze a obrat pro e-shop.
34
www.payu.cz
4.7 Funkční šablona
4
Již řadu let se věnujeme optimalizaci platebního procesu. Na základě analýz nákupního chování
jsme vyvinuli funkční šablonu pro placení předem. Šablona slouží e-shopům, které chtějí zvyšovat
konverzi nákupu pomocí rychlých online plateb. Po dohodě s bankami jsme upravili vizualizaci a popis
platebních metod tak, aby byly pro nakupující co nejvíce srozumitelné. Jejich řazení je nastavené tak,
aby byli nakupující nejdříve směřováni na platbu rychlým převodem z jejich banky a až poté na platbu
kartou, která má vyšší náklady na jednu transakci. Šablona je přehledná, dobře čitelná a dá se umístit
přímo na e-shop.
4.8 Edukace zákazníků a marketing
Každý zákazník ocení, pokud je dostatečně informován o průběhu platby a samotném zaplacení za
zboží či služby. U platebních metod „Standardní bankovní převod“ a „Platba složenkou přes Českou
poštu“ PayU nabízí možnost aktivace služby pro zasílání e-mailů s údaji o platbě přímo na e-mail
zákazníkům. Díky tomu je zákazník ujištěn, že zadané údaje jsou správné a zároveň se tím snižuje
případná chybovost. Pokud máte zájem vyzkoušet si šablonu PayU, pak můžete navštívit náš testovací
e-shop na této webové stránce http://payu.fcostry.cz/
35
www.payu.cz
4
Součástí úspěšné implementace je také vložení loga nebo banneru PayU, která jsou k dispozici ke
stažení webu PayU na adrese http://www.payu.cz/ke-stazeni
PayU poskytuje také edukační mailing pro klienty. Informuje tak o tom, jak snížit chybovost při placení
on-line a zvýšit tak konverzi.
Pro podrobnější informace neváhejte kontaktovat náš tým obchodníků a pracovníků zákaznické
podpory.
36
Povinné
parametry
implementace
5
www.payu.cz
Před spuštěním ostrého provozu platebního systému PayU na e-shopu musí být splněny
následující požadavky:
5
1. Nasazení všech platebních metod dle smlouvy.
2. Správný popis a vizualizace platebních metod (viz kapitola 4).
3. Správně naimplementované návratové adresy (viz. kapitola 3.5)
4. Správně naimplementovaný kontrolní součet (viz kapitola 3.6).
5. Pozitivní výsledek testovací platby.
6. Umístění loga PayU (případně také bannerů a další grafiky) na hlavní stránce e-shopu
a na stránce výběru platebních metod.
7. Loga – Orientace pomocí log jednotlivých platebních metod viz bod 12 v příloze 8.
8. Platební metody – Správný krok zobrazení platebních metod PayU viz bod 16 v příloze 8.
38
Administrace
PayU účtu
6
www.payu.cz
6.1 Obecné informace
6
Tato část příručky se věnuje nastavení a práci s PayU účtem. Pomůže vám nastavit vše potřebné od
prvního přihlášení k vašemu účtu a pohybovat se v uživatelském rozhraní PayU.
6.2 Uživatelské rozhraní PayU
Do uživatelského rozhraní PayU je možné se přihlásit po kliknutí na odkaz „Přihlášení do nového PayU
účtu“, který je umístěný na hlavní stránce PayU (http://www.payu.cz).
Po kliknutí na uvedený odkaz je uživatel přesměrován na stránku https://secure.payu.pl/user/
start?lang=cs, kde je potřeba uvést uživatelské jméno a heslo a poté kliknout na tlačítko „Přihlásit se“.
40
www.payu.cz
6
6.3 Vytvoření Obchodu a POSu
Po prvním přihlášení do uživatelského rozhraní je uživatel vyzván k vytvoření Obchodu (ve stručnosti
je založení Obchodu a POSu popsáno také v kapitole 2.2).
Po kliknutí na tlačítko „Přidat obchod“ je v prvním kroku potřeba zvolit webovou adresu Obchodu,
uvést název Obchodu (případně také jeho popis) a vybrat požadovanou měnu. Má-li uživatel zájem
zpracovávat ve svém Obchodu platby v eurech, musí být tato skutečnost uvedena ve smlouvě s PayU.
41
www.payu.cz
6
Pokud má uživatel zájem využívat platební systém PayU na jiné webové adrese, než jakou uvedl během registrace, může tuto adresu uvést. V takovém případě je však nutné, aby byl vytvořen dodatek
ke smlouvě s PayU.
42
www.payu.cz
Ve druhém kroku je třeba zadat jméno POSu a zvolit požadované kódování dat. Rovněž je zde
možné definovat chybnou návratovou adresu (UrlNegative), správnou návratovou adresu
(UrlPositive) a adresu pro oznámení (UrlOnline) pro tento POS. Pole „Kontroloval platnost SIGu“ je
potřeba nechat zakliknuté, aby byla při vytváření nové platby ověřována správná hodnota kontrolního
součtu.
6
Po kliknutí na tlačítko „Přidat obchod“ se zobrazí stránka s konfiguračními údaji vytvořeného POSu,
potřebnými pro naimplementování platebního systému na stránku Obchodu (pos_id, první a druhý
MD5 klíč a autorizační klíč pos_auth_key).
43
www.payu.cz
6
Po kliknutí na tlačítko „Dokončení“ je Obchod přidán do seznamu Obchodů, který se nachází v záložce
„Platby Online“ pod odkazem „Můj obchod“.
Přidání dalšího Obchodu je možné provést kliknutím na tlačítko „Přidat obchod“.
44
www.payu.cz
6
Přidání dalšího POSu do již existujícího Obchodu je možné kliknutím na odkaz „Seznam POS“
u příslušného Obchodu
45
www.payu.cz
a poté na tlačítko „Přidat nový POS“.
6
Podrobnosti o Obchodu je možné zobrazit kliknutím na název Obchodu,
podrobnosti o POSu zase kliknutím na název POSu.
46
www.payu.cz
6
V informacích o POSu jsou zobrazeny také typy plateb dostupné pro daný POS včetně nastavených
provizí (před spuštěním ostrého provozu je k dispozici pouze testovací platba). Uživatel může v nastavení POSu vypínat či zapínat funkci automatického přijímaní plateb a to buď pro každý typ platby
jednotlivě anebo hromadně pro všechny typy plateb.
6.4 Transakce
Seznam transakcí se nachází v záložce „Platby online“ pod odkazem „Transakce“. Transakce je v seznamu možné vyhledávat podle mnoha různých kritérií.
47
www.payu.cz
6
Podrobnosti o každé transakci je možné zobrazit kliknutím na popis transakce.
48
www.payu.cz
Stránka s podrobnostmi o transakci vypadá takto
6
Po kliknutí na tlačítko „Historie oznámení“, je možné manuálně odeslat oznámení o změně statusu transakce na adresu UrlOnline příslušného Obchodu. Funkce má své využití zejména během fáze
implementace a testování platebního systému. Odesílání oznámení jinak probíhá zcela automaticky
a není nutné jej iniciovat tímto ani žádným jiným způsobem.
49
www.payu.cz
6
Prostřednictvím stránky „Seznam transakcí“ je možné přijímat nebo rušit transakce se statusem
„pro přijetí“,
přijímat nebo rušit transakce se statusem „odmítnuta“,
případně rušit transakce se statusem „nová“.
50
www.payu.cz
6
Ze stránky „Seznam transakcí“ je možné provádět také vrácení plateb. Vrátit lze pouze takovou platbu,
která má status „skončena“. Po kliknutí na odkaz „Vrátit“
a kliknutí na tlačítko „Další“ na následující stránce
je možné zadat částku vrácené platby (vrátit lze celou výši transakce nebo její část), uvést zprávu pro
příjemce do pole „Název vrácené platby“ a zvolit jeden ze tří typů „ručních“ (manuálních) způsobů
vrácení platby – bankovní převod, bankovní převod do zahraničí nebo platbu prostřednictvím poštovní
poukázky.
51
www.payu.cz
6
Na základě zvoleného způsobu vrácení platby je poté nutné vyplnit pole v části „Údaje příjemce vrácené platby“ a kliknout na tlačítko „Vrátit platbu“.
52
www.payu.cz
U vybraných typů plateb lze v části „Způsob vrácení platby“ zvolit možnost „automaticky (stejné jako
platební metoda)“. Při výběru této možnosti není potřeba zadávat žádné další údaje – po kliknutí na
tlačítko „Vrátit platbu“ je platba vrácena na účet, ze kterého byla odeslána.
6
Alternativně je možné vrácení platby iniciovat ze stránky „Platby online“ > „Transakce“ > „Vrácené
platby“ kliknutím na tlačítko „Nová vrácená platba“.
53
www.payu.cz
a uvedením čísla transakce, která má být vrácena, na následující straně.
6
6.5 Vyúčtování, Výběry a Vrácené platby
Seznam Historie vyúčtování a transakcí se nachází v záložce „Platby online“ pod odkazem
„Transakce > Vyúčtování“.
Na stránce lze vyhledávat podle různých kritérií, podobně jako na stránce „Seznam transakcí“. Výsledky hledání se však liší v tom, že vedle informací o transakcích uvádějí také údaje týkající se naúčtovaných provizí. Zároveň je zde uváděna i aktuální výše zůstatku Obchodu po každé operaci (tj. po přijetí
transakce, po naúčtování provize atd.)
54
www.payu.cz
6
Stránka „Výběry“ („Platby online“ > „Transakce“ > „Výběry“) umožňuje vyhledávat v historii výběrů
(převodů zůstatků jednotlivých Obchodů na bankovní účty, které jsou k těmto Obchodům přiřazené).
Stránka „Vrácené platby“ („Platby online > Transakce > Vrácené platby“) zase umožňuje vyhledávat
v historii vrácených plateb. Prostřednictvím tlačítka „Nová vrácená platba“ je možné iniciovat vrácení
platby, jak již bylo uvedeno výše.
55
www.payu.cz
6
6.6 Výběry
O převod aktuálního zůstatku Obchodu na bankovní účet, který je k tomuto Obchodu přiřazený, je
možné kdykoliv požádat kliknutím na tlačítko „Vyplatit zůstatek“, které se nachází na stránce „Platby
online“ > „Můj obchod“.
Výběry ale není nutné zadávat vždy pouze tímto manuálním způsobem. V uživatelském rozhraní lze
definovat také pravidla pro provádění výběrů automaticky. Po kliknutí na odkaz „Automatické výběry“
u příslušného Obchodu na stránce „Platby online“ > „Můj obchod“
56
www.payu.cz
6
a zvolení možnosti „Upravit automatické výběry“
se automatické výběry aktivují zakliknutím možnosti „Ano“ u možnosti „Automatické výběry jsou
aktivní“. Poté je nutné zadat „Minimální částku k výběru“ (pokud je zůstatek obchodu menší než tato
částka, výběr se neuskuteční) a zvolit jednu ze tří nabízených „Frekvencí výběrů“ (např. „Periodicky“, tj.
vždy po uplynutí zadaného počtu dnů). Nastavení výběru se poté potvrdí tlačítkem „Uložit změny“.
57
www.payu.cz
Další volitelné „Frekvence výběrů“ jsou „Vybrané pracovní dny“ a „Vybraný den v měsíci“.
První z nich umožňuje provádět výběry konkrétní den v týdnu,
6
druhá pak ve zvolený den v měsíci.
58
www.payu.cz
6.7 Výpisy PDF/CSV/ABO
Z uživatelského rozhraní je možné stahovat výpis transakcí ve 3 různých formátech – PDF, CSV a ABO.
Formát PDF je vhodný pro tisk, s formátem CSV je možné pracovat v programu MS Excel (případně
jiném tabulkovém procesoru), výpis ve formátu ABO (.gpc) je pak kompatibilní s tzv. účetními softwary
(programy na zpracování účetnictví). Výpisy v tomto formátu je možné naimportovat do těchto
programů a zapracovat tak údaje o transakcích ze systému PayU do firemního účetnictví.
Výpisy ve všech třech formátech mohou být vytvářeny periodicky nebo jednorázově. Pro vytvoření
periodického výpisu je na stránce „Platby online“ > „Výpisy PDF/CSV/ABO“ > „Periodické výpisy“
potřeba kliknout na tlačítko „Vytvořit nový periodický výpis“.
6
Na následující stránce je pak v příslušné kolonce nutné vybrat „Obchod“, pro který má být výpis vygenerován, uvést e-mailovou adresu, na kterou má být výpis zaslán a zvolit „Frekvenci“, tj. definovat jak
často má být požadovaný výpis vytvořen. V příkladu uvedeném níže byla zvolena možnost „po každém
výběru“. Kromě této možnosti lze výpisy nastavit tak, aby byly vytvářeny vždy konkrétní den v měsíci, konkrétní den v týdnu anebo opakovaně po uplynutí určitého počtu dnů (tj. jsou zde k dispozici
podobné možnosti jako v případě automatických výběrů).
59
www.payu.cz
Dále je potřeba zvolit požadovaný „Formát souboru“. Podle toho, jaký formát je zvolen, je možné
jeho nastavení dále specifikovat. Nejvíce variabilní je formát CSV. Tento typ výpisu může obsahovat
následující údaje: Typ operace, Datum, ID transakce, Částka, Zůstatek, Změna Zůstatku, ID objednávky,
Popis, Popis2/č- účtu, Typ platby, Město, PSČ, Telefon, E-mail, Ulice, Jméno a příjmení, Provize
a Měna. Přidání požadovaného údaje do výpisu se provede označením údaje kurzorem myši
a kliknutím na tlačítko „>“. Přidání všech údajů do výpisu je možné kliknutím na tlačítko „>>“.
6
CSV výpis, u kterého je zvolen Oddělovač polí ; a Oddělovač textu “ vypadá následovně:
60
www.payu.cz
6
Výpis, u kterého je zvolen Oddělovač polí ; a Oddělovač textu ‘ pak vypadá takto:
Formát ABO umožňuje zvolit, jaký údaj má být uvedený v kolonce „variabilní symbol“ a má nebo nemá-li výpis obsahovat také „záznamy o účtovaných provizích“.
61
www.payu.cz
U formátu PDF je pak možné volit mezi dvěma šablonami výpisu.
6
Šablona „Výpis“ obsahuje údaje: Datum, Typ operace, ID transakce, Částka, Provize, Zůstatek na účtu,
Popis/účet č. a celkové shrnutí daného období.
Šablona „Shrnutí“ pak obsahuje pouze celkové shrnutí daného období.
62
www.payu.cz
Po vyplnění všech povinných polí je aktivování výpisu na závěr nutné potvrdit kliknutím
na tlačítko „Přidat“.
Po kliknutí na toto tlačítko je nově vytvořený požadavek na generování periodických výpisů zobrazený
v tabulce na stránce „Platby online > Výpisy PDF/CSV/ABO > Periodické výpisy“. Přehled již vygenerovaných periodických výpisů je možné zobrazit po kliknutí na odkaz „Seznam periodických výpisů“
tamtéž.
6
Jednorázový výpis je možné vytvořit na stránce „Platby online“ > „Výpisy PDF/CSV/ABO“ > „Jednorázové výpisy“ po kliknutí na tlačítko „Nový výpis“.
63
www.payu.cz
Obdobně jako u periodických výpisů je na následující stránce potřeba zvolit, pro jaký „Obchod“ má
být výpis vytvořen a na jaký „E-mail“ má být zaslán. Namísto frekvence se v tomto případě zadává
období, pro jaké má být výpis vytvořen. Další nastavení, stejně jako je tomu u periodických výpisů,
se pak odvíjí od toho, jaký „Formát souboru“ je zvolen. Po vyplnění všech povinných polí je vytvoření
výpisu aktivováno kliknutím na tlačítko „Generovat“, umístěné ve spodní části stránky.
6
Jakmile je žádost o vytvoření jednorázového výpisu vytvořena, zobrazí se na stránce „Platby online“
> „Výpisy PDF/CSV/ABO“ > „Jednorázové výpisy“. Informace o tom, jaký je aktuální stav požadavku, je
uvedena ve sloupci označeném „Status“. Jakmile je výpis odeslán na požadovanou emailovou adresu,
získává žádost status „Vytvořeno“. Výpisy, které již byly jednou systémem vygenerovány, je možné
opětovně získat kliknutím na tlačítko „Stáhnout“. V tomto případě již není výpis odesílán prostřednictvím emailu, ale je možno jej rovnou otevřít anebo uložit do počítače.
Všechny periodické stejně jako jednorázové výpisy jsou vždy zkomprimovány metodou ZIP.
64
www.payu.cz
6.8 Statistiky
6
Statistiky, které se nacházejí na stránce „Platby online“ > „Statistiky“, slouží k zobrazování statistických
údajů za požadované období. Je možné volit mezi denními, měsíčními a ročními údaji. Mohou být
zobrazena data pouze pro konkrétní Obchod anebo pro vybrané typy plateb. V kolonce „Rozsah“ lze
vybrat mezi možnostmi „počet transakcí“, „objem transakcí“ a „počet transakcí a jejich objem“. Prezentace statistických údajů se aktivuje kliknutím na tlačítko „Zobrazit“.
65
www.payu.cz
Požadované údaje jsou zobrazeny prostřednictvím grafu a tabulky. Pokud graf zobrazuje objem
transakcí (množství peněž, které byly jednotlivými typy plateb uhrazeny), lze tlačítkem „Počet
transakcí“ přepnout na zobrazení počtu plateb a naopak. Po najetí kurzorem myši na některý
ze sloupců grafu se objeví jeho konkrétní číselná hodnota.
6
Stejné údaje jako v grafech jsou pak zobrazeny také v tabulce.
66
www.payu.cz
6.9 Nastavení oznámení
6
V uživatelském rozhraní lze na stránce „Konfigurace účtu“ > „Nastavení oznámení“ aktivovat možnost
zasílání oznámení o transakcích prostřednictvím emailu. Pro odesílání oznámení emailem stačí kliknout na tlačítko „Zapnout“.
6.10 Uživatelské účty
Seznam uživatelských účtů se nachází na stránce „Konfigurace účtu“ > „Uživatelské účty“. Nový uživatelský účet lze vytvořit prostřednictvím tlačítka „Přidat uživatele“.
Na následující stránce je potřeba vyplnit údaje o novém uživateli (tj. kolonky „Uživatelské jméno“,
„Křestní jméno“, „Příjmení“, „E-mail“ a „Telefon“) a dále zvolit, má-li být vytvořený účet typu „Administrátor společnosti“ anebo „Uživatel společnosti“. „Administrátor“ má přístup ke všem údajům a funkcím
v uživatelském rozhraní, zatímco přístupová práva „Uživatele“ lze omezit. Pro účet typu „Uživatel“ je
možné vybrat, má nebo nemá-li mít majitel tohoto uživatelského účtu „Oprávnění prohlížet faktury“.
Po vyplnění všech požadovaných kolonek je možné pokračovat kliknutím na tlačítko „Další“.
67
www.payu.cz
6
Na následující stránce je pro účet typu „Uživatel společnosti“ možné zakliknout, k jakým funkcím
a jakým Obchodům má mít majitel vytvářeného účtu přístup. Vytvoření účtu se dokončí kliknutím
na tlačítko „Přidat uživatele“.
68
www.payu.cz
Nově vytvořený uživatelský účet je poté přidán do seznamu uživatelů na stránce „Konfigurace účtu“ >
„Uživatelské účty“. Heslo k účtu je novému uživateli doručeno na emailovou adresu, uvedenou
v nastavení tohoto účtu.
6
Operace, které je možné s uživatelskými účty provádět, se zobrazí po najetí kurzorem myši na odkaz
„Volby“, který se nachází ve sloupci nadepsaném „Činnost“. Pro uživatelské účty je možné aktivovat
funkci zasílání oznámení o transakcích emailem (odkaz „Oznámení“). Dále je možné „Upravit“ kontaktní údaje uživatele a „Odstranit“ nebo „Blokovat“ uživatelský účet (blokovaný účet je na rozdíl od účtu
odstraněného možné opět odblokovat). Pro uživatelský účet je také možné vygenerovat nové heslo.
69
Přílohy
7
www.payu.cz
7
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
mTransfer – 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
Sberbank
pf
3,00 – 999999,99
10
Fio banka
era
3,00 – 999999,99
10
Era - Poštovní spořitelna
cb
3,00 – 999999,99
10
ČSOB
psc
3,00 – 999999,99
10
PaySec
c
3,00 – 999999,99
10
Platební karty přes GPE
mo
5,00 – 10000,00
10
Mobito
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)
t
0,50 – 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.
Pořadí dostupných platebních kanálů na stránkách Obchodu by mělo být takové jako v tomto
dokumentu.
71
www.payu.cz
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
7
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 2 – „zrušena“ se objeví také v případě, kdy je transakce se statusem 1 – „nová“ nebo 5 – „pro
přijetí“ zrušena aplikací obchodu nebo uživatelem.
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). Obchod by měl platbu přijmout nebo odmítnout 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 zrušena automaticky a finanční prostředky jsou vráceny zpět
plátci.
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
3.4.3 a 3.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í“.
72
www.payu.cz
7
Příloha 3 – Přechody mezi statusy transakce
Je-li automatické přijímání plateb vypnuto:
Nová
(status 1)
Pro přijetí
(status 5)
Zahájena
(status 4)
Je-li možné
transakci zrušit
Zrušena
(status 2)
Odmítnuta
(status 3)
Vrácena
(status 7)
Skončena
(status 99)
73
www.payu.cz
7
Je-li automatické přijímání plateb zapnuto:
Nová
(status 1)
Zahájena
(status 4)
Zrušena
(status 2)
Odmítnuta
(status 3)
Vrácena
(status 7)
Skončena
(status 99)
74
www.payu.cz
7
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
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
211
chybná měna transakce – kontaktujte
prosím náš zákaznický servis
212
požadavek na vytvoření více než 1
transakce za minutu (u neaktivované
společnosti)
107
chybí parametr last_name
108
chybí parametr street
500
neexistující transakce
109
chybí parametr city
501
chybí autorizace pro tuto transakci
110
chybí parametr post_code
502
transakce začala dříve
111
chybí parametr amount
503
autorizace transakce již byla
vykonána
112
nesprávné číslo bankovního účtu
504
transakce byla dříve zrušena
113
chybí parametr email
505
transakce již byla odeslána k přijetí
114
chybí parametr tel. číslo (phone)
506
transakce byla přijata
200
jiná přechodná chyba
201
jiná přechodná chyba databáze
507
chyba při převodu prostředků zpět
zákazníkovi
202
POS tohoto ID je blokován
508
zákazník odstoupil od provedení
platby
203
neplatná hodnota pay_type pro dané
pos_id
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
204
205
zvolený typ platby (pay_type) je
dočasně zablokován pro dané pos_id,
např. z důvodu servisní odstávky
platební brány
částka transakce je nižší než
minimální hodnota
75
www.payu.cz
Příloha 5 – Ukázka php skriptu, který zjišťuje stav transakce
7
Tento skript naleznete také na našich internetových stránkách http://www.payu.cz/ke-stazeni
<?php // adresy pro server PayU a metodu Payment/get
$server = “secure.payu.com”; $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”); 76
www.payu.cz
// 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”); 7
// 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 (!@feof($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); curl_setopt($ch, CURLOPT_POSTFIELDS, $parameters); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $payu_response = curl_exec($ch); curl_close($ch); } 77
www.payu.cz
// 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
7
/* například”
if ($result[“code”] == “99”) { if(money_are_on_the_account) { // platba je úspěšná, takže posíláme zpátky OK
echo “OK”; exit; } } else if ($result[“code”] == “2”) { // transakce zrušena, můžeme rovněž transakci zrušit
} else { // jiné akce
} */ // pokud jsou všechny operace ukončené, posíláme nazpět OK, v opačném případě vygenerujeme
error
// if (everything_ok) // { echo “OK”; exit; 78
www.payu.cz
// } 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 ze secure.payu.com odeslána znovu, můžeme zapsat informaci
do logů (logs)....
} 7
?>
79
www.payu.cz
7
Příloha 6 – PayU šablony (templates)
šablona č. 3 (česká verze)
šablona č. 5 (anglická verze)
80
www.payu.cz
Příloha 7 – Ukázka implementace PayU
Implementace pomocí šablony
7
81
www.payu.cz
Individuální implementace
7
82
www.payu.cz
7
Příloha 8 – Případová studie
Košík e-shopu
Cílem košíku je uskutečněná a zaplacená objednávka.
Hlavním prostředkem k dosažení tohoto cíle je
hladký, rychlý a ničím nerušený průběh objednávky.
Až 40 % Vašich klientů rozhodnutých
k nákupu objednávku obvykle nedokončí.
Nevěříte?
A jak by měl takový správný košík vypadat?
Na následujícím příkladu Vám ukážeme, jak toto
číslo snížit. Nejdůležitější částí nákupního procesu
je nákupní košík. Právě ten rozhoduje, zda si Váš
potenciální zákazník opravdu něco koupí, či zda
zůstane jen potenciálním zákazníkem.
Přeskočíme samotné přesouvání zboží z e-shopu do
košíku. To by mělo být samozřejmě přehledné a košík
by měl být na každé stránce vidět včetně součtu ceny
položek. Nejčastější pozice košíku je pravá horní část
stránky, tam každý nakupující bude košík hledat.
1. KOŠÍK
1
7
2
5
3
4
1
Navigace – nakupující by se měl v košíku
orientovat. Měl by vědět, jaké kroky ho čekají a mít
možnost se do některého vrátit a změnit například
způsob dopravy či platby. Doporučujeme mít košík
vedený na 3 – 5 kroků.
2
Zboží – v košíku musí být vidět nakupované zboží,
množství, název, cena, možnost úpravy počtu kusů
a především aktuální dostupnost.
3
Slevy a dárkové kupóny – možnost zadat slevový
nebo dárkový kupón je dobrý způsob, jak můžete
zjistit,
zda se Vám určité reklamní akce vyplácejí a zda
na ně klienti reagují.
6
4
Vrátit se k nákupu – nakupující by měl mít možnost
jednoduše se vrátit z košíku k nakupování. Toto
tlačítko by mu mělo umožnit návrat na poslední
stránku před vstupem do košíku.
5 Cena – košík by měl obsahovat celkovou cenu
zboží, za kterou si nakupující objednává a to
včetně DPH.
6 Pokračovat – viditelné tlačítko, které jasně
naviguje k dalšímu kroku objednávky.
7
Kontakty – nakupující může mít v průběhu
objednávky dotaz nebo může zapochybovat
o vhodnosti zboží. Pokud mu dáte možnost ujistit
se nebo se zeptat co dál, nepřijdete o něj.
83
www.payu.cz
2. DOPRAVA A PLATBA
a bez přemýšlení nalézt právě tu metodu, kterou
hledá. Každý zná logo své banky nebo jiné
oblíbené platební metody a nemusí číst řádek po
řádku.
8
Doprava a platba - v jednom kroku zjednodušuje
orientaci při nákupu a snižuje počet kroků
nutných k dokončení objednávky.
9
Rozřazením jednotlivých způsobů dopravy
a platby do samostatných odstavců zjednodušíte
nakupujícím orientaci. Například na platbu
při osobním odběru a online platby, případně
splátky.
13 Tlačítko zpět – občas se stane, že si nakupující
uvědomí, že něco nevyplnil správně, případně
že by chtěl o jeden kus zboží navíc. Dejte tedy
klientům možnost pohybovat se v košíku
pohodlně vpřed i vzad.
10
Podrobné informace o dopravě – Jasně uvedená
cena dopravy včetně očekávaného termínu
dodání, případně dalších instrukcí (např.
„Vyčkejte na SMS“).
14
Cena – v košíku by měla být opět určitě vidět
celková cena za objednávané zboží včetně
dopravy a DPH.
15
11
Infoboxy – u platebních metod a dopravy
je dobré dát nakupujícímu podrobné informace
o daném způsobu platby nebo dopravy.
Je to elegantní cesta, jak dostat informace
ke klientům nenuceně. Kdo o ně má zájem,
ten je nalezne, kdo ne, tomu nepřekáží.
Pokračovat – opět viditelné tlačítko, které
naviguje k dalšímu kroku objednávky.
12
7
16 Platební metody – všechny metody patří na
jednu stránku. Nemělo by se tedy stát to, že
si nakupující v kroku platby vybere platební
metodu „PayU“ – což je platební brána nabízející
12 platebních metod – nikoliv platební metoda.
Je to podobné jakoby si měl klient vybrat
„Osobní odběr“ a nevěděl, ve kterých městech je
dostupný.
Loga – jedná se o efektivní formu navigace.
Pokud pracujete s větším počtem platebních
metod, dejte nakupujícím možnost jednoduše
8
9
9
12
11
16
10
84
14
13
15
www.payu.cz
7
17
Upozornění – pokud nakupující například nezvolí
způsob dopravy, jasně vypište, co má udělat.
Košík by neměl pracovat s jedním chybovým
hlášením pro všechny varianty nevyplněných
a nezaškrtnutých polí.
20
Alternativní pole – možnost nákupu na firmu
nebo jiná doručovací adresa se většinou využívá
velmi zřídka. Uvést tyto možnosti formou
skrytých buněk, rozevřených po zaškrtnutí, je
dobrá forma jak je zachovat, ale nekomplikovat
prostupnost košíku.
3. OSOBNÍ ÚDAJE
18
Přihlášení a registrace – pokud to není
bezpodmínečně nutné, tak po klientovi
nevyžadujte registraci. Dejte mu možnost
přihlásit se, nebo vyplnit objednávku jako nový
uživatel. Pokud chcete mít klienty registrované,
raději to udělejte automaticky na základě jejich
objednávky, všechny podstatné údaje máte
19
Vyplňované údaje – nenuťte nakupující
vyplňovat víc údajů, než je bezpodmínečně
nutné a povinná pole viditelně označte.
21 Odeslat objednávku – viditelné pole k odeslání
objednávky, které v tomto případě znamená
i souhlas s obchodními podmínkami.
18
19
20
85
21
www.payu.cz
7
22
Nevyplněná pole – pokud
nakupující nevyplní některé
povinné buňky, e-shop by ho měl
upozornit na specifické nedostatky.
4. POTVRZENÍ OBJEDNÁVKY A PLATBA
23 Potvrzení objednávky – vždy by mělo být
uvedeno číslo objednávky pro budoucí
komunikaci. Dejte nakupujícímu vědět, že se
jeho objednávka zpracovává, odešlete mu e-mail
s jejím shrnutím. V tomto kroku můžete také dát
klientovi možnost opravit dříve vyplněné údaje
(například výběr jiné platební metody).
24 Platba – pokud si klient vybral platbu předem,
musí mít ještě možnost zaplatit. Toto tlačítko
ho přesměruje na zvolenou platební metodu.
23
24
Samozřejmostí každého košíku využívajícího
online platby je také takzvaná pozitivní a negativní
návratová adresa. Ta první informuje klienta o
úspěšné platbě za objednávku, ta druhá o neúspěšné.
V případě neúspěšné platby doporučujeme
nevyprazdňovat košík a dát klientovi možnost zvolit
jinou platební metodu a dokončit během dvou kliků
objednávku napodruhé.
86
www.payu.cz
Příloha 9 – Změny v manuálu podle verzí
7
VERZE 1.1
Kapitola 2, str. 7 – text „www.payu.cz“ nahrazen textem „secure.payu.com“
Kapitola 3, str. 14 – text „www.payu.cz“ nahrazen textem „secure.payu.com“
Kapitola 3, str. 15 – text „www.payu.cz“ nahrazen textem „secure.payu.com“
Kapitola 3, str. 17 – text „objeví se zákazníkovi na výpisech z banky“
nahrazen textem „objevuje se Obchodu ve výpisech transakcí“
Kapitola 3, str. 18 – text „www.payu.cz“ nahrazen textem „secure.payu.com“
Kapitola 3, str. 19 – text „www.payu.cz“ nahrazen textem „secure.payu.com“ (3×)
Kapitola 3, str. 20 – text „www.payu.cz“ nahrazen textem „secure.payu.com“ (2×)
Kapitola 6, str. 40 – text „www.payu.cz“ nahrazen textem „secure.payu.com“
Kapitola 7, str. 73 – přidání šipky mezi „Odmítnuta (status 3)“ a „Skončena (status 99)“
Kapitola 7, str. 75 – přidání chyby č. 508
Kapitola 2, str. 7 – text „https://secure.payu.com/manager/register?execution=e1s1“ nahrazen textem
„http://registrace.payu.cz/?p=6“
Kapitola 6, str. 40 – text „Přihlášení pro e-shopy“ nahrazen textem „Přihlášení do nového PayU účtu“
Kapitola 6, str. 40 – text „https://secure.payu.com/manager/login?lang=cs“ nahrazen textem
„https://secure.payu.pl/user/start?lang=cs“
VERZE 2.0
Kapitola 7, str. 76 – text „www.payu.cz“ nahrazen textem „secure.payu.com”
Kapitola 7, str. 79 – text „z www.payu.cz“ nahrazen textem „ze secure.payu.com”
kapitola 3, str. 20 - text „za 24 hodin“ nahrazen textem „za hodinu“
kapitola 3, str. 27 - změna věty „Jedná-li se… platby.“ a věty „I v případě… atd.).“
kapitola 4, str. 32 - odstraněn text „platba superCASH“
kapitola 6, str. 65 - úprava obrázku
kapitola 6, str. 66 - úprava obrázku
kapitola 7, str. 71 - odebrání „superCASH“ řádku tabulky
kapitola 7, str. 80 - úprava obrázku
kapitola 7, str. 81 - úprava obrázku
kapitola 7, str. 82 - úprava obrázku
Kapitola 7, str. 75 – update seznamu chyb
Kapitola 7, str. 80 – odebrání šablon 4 a 6
Kapitola 3, str. 30 – přidání modrého rámečku
Kapitola 7, str. 83 – 86 – přidání přílohy
Kapitola 3, str 17 – přidání textu „Ujistěte se…“
87
www.payu.cz
Kapitola 5, str. 38 – změna textu „v kapitole“ na „v příloze“
Kapitola 7, str. 75 – přidání chyby 212
7
Kapitola 7, str. 80 – přidání textu „(česká verze)“ a „(anglická verze)“; výměna obrázků
VERZE 2.1
Kapitola 3, str. 19 – odstranění čísel 4, 6 v tabulce
Kapitola 3, str. 19 – přesunutí textu ze str. 20, odstranění odstavce, odstranění scriptu
Kapitola 3, str. 20 – přesunutí textu na str. 19, odstranění věty „anglická verze“
Kapitola 3, str. 20 – přidání textu <input type=“hidden“ name=“ts“ value=“251013105655“> a <input
type=“hidden“ name=“sig“ value=“9075ed67df1c3a4e5686ee7bbb78ad64“>
Kapitola 7, str. 71 – přidání nových položek „era, cb, psc“
Kapitola 7, str. 71 – změna hodnoty sloupce u metody „t“ z „1,00 – 1000,00“ na „0,50 – 1000,00“
Kapitola 7, str. 72 – (status 3) přidání textu „Obchod by měl…“
Kapitola 7, str. 71 – změna textu „mPenize“ na „mTransfer“
Celý dokument – zrušení ligatury „fi“ na „fi“
Kapitola 3, str. 17 – změna parametru „ne“ na „ano“ (řádek language)
VERZE 2.2
Obsah, str. 3 – oprava textu „příloha 5“
Kapitola 3, str. 17 – změna „http:www.chemie.fu-berlin.de/…“ na „https://www.iso.org/obp/…“
Kapitola 3, str. 17 – změna „http:www.ics.uci.edu/…“ na „http://www-01.sil.org/…“
Kapitola 3, str. 20 – vložení řádku „<input type=“hidden“ name=“language“ value=“cs“>“
Kapitola 3, str. 21 – vložení řádků „sig_ext“ a „sig_ext_order“
Obálka, str. 89 – změna tel. č. na „226 221 951“
88
Adresa: PayU Czech Republic, s. r. o. / Karolinská 650/ 1 / Praha 8, 18600
Telefon: 226 221 951 / e-mail: [email protected] / web: www.payu.cz / © PayU