1 2.2 Implementační manuál PayU pro developery2 Obsah 1. Úvod 2. Od registrace po spuštění provozu platební brány 2.1 Začínáme, testujeme 2.2 Aktivace...
2. Od registrace po spuštění provozu platební brány 2.1 Začínáme, testujeme 2.2 Aktivace e-shopů 2.3 Jak vypadá akvizice e-shopů developera? 2.4 Jak probíhá proces platby prostřednictvím platební brány Payu? 2.5 Co je potřeba zajistit na straně developera 2.6 Šablona pro platby procesované prostřednictvím platební brány Payu 2.7 Zásady pro umístění PayU v nákupním košíku 2.8 Povinné podmínky spolupráce 2.9 Propagace platební brány PayU developerem
4 5 6 7 8 8 9 10 11 12
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í
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 Edukace zákazníků a marketing
33 34 34 35 35 35 36 37
5. Povinné parametry implementace
38
6. 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 – Kontakty Příloha 9 – Případová studie Příloha 10 – Změny v manuálu podle verzí
40 41 42 43 45 46 50 51 52 53 57
2
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 developerů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 a jaké jsou možnosti vizualizace nabízených platebních metod. 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 z šesti 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.
3
www.payu.cz
Od registrace po spuštění provozu platební brány
2
4
www.payu.cz
Praktický průvodce implementací platební brány PayU. Manuál obsahuje popis klíčových situací developera při práci s PayU, které následují po uzavření smlouvy.
2
2.1 Začínáme, testujeme
Co se děje na straně developera • Registrace na www.payu.cz kvůli zřízení testovacího účtu.
Co zajišťuje PayU • Zřízení PayU účtu.
• Založení testovacího SHOPu a POSu v PayU účtu. • Implementace podle technické dokumentace v tomto manuálu. • Aktivace testovací platby. • Provedení testovací platby. • Kontrola úspěšné testovací platby, nákupního procesu a umístění PayU v něm.
5
www.payu.cz
2
2.2 Aktivace e-shopů Co se děje na straně developera • Vytvořit stránku na webu developera s informacemi o PayU, na tuto URL budou klienti developera směřováni.
Co zajišťuje PayU • Kontrola na straně PayU Obchodní zástupce
• Vložit do této stránky odkazy na automaticky registrační proces, pomocí kterého budou s klienty zpracovávány smlouvy. • Dodání vzoru návratových adres obchodnímu zástupci PayU. (Ve vzoru se bude měnit pouze doména e-shopu). • Vytvoření webové aplikace se zabezpečeným přístupem pro PayU. Jedná se o jednoduchý formulář obsahující pole pro IČO, číslo POSu (pos_id) a konfigurační klíče POSu (key1, key2 a pos_auth_key), potřebné pro pozdější propojení plateb u jednotlivých e-shopů na PayU.
• Vložení klíčů Zákaznický servis PayU
• Automatická implementace a zprovoznění plateb přes PayU na e-shopu.
• Finální kontrola Obchodník PayU
Smlouva uzavřena
Platební brána PayU naimplementována
Testovací platba provedena
Nákupní proces schválen obchodníkem PayU
6
www.payu.cz
2.3 Jak vypadá akvizice e-shopů developera? a.
Developer informuje prostřednictvím svých komunikačních kanálů e-shopy o možnostech a výhodách online plateb nabídka na aktivaci platební brány PayU.
b.
Zájemci jsou směřováni na stránku s odkazy do automatického registračního procesu na stránkách developera.
c.
Po vyplnění základních údajů se klientovi zobrazí provizní nabídka a posléze může uzavřít smlouvu. V případě větších klientů se zobrazí zpráva, že je budeme do jednoho pracovního dne kontaktovat.
d.
Následuje AML ověření a v případě větších klientů vyjednání podmínek a podpis smlouvy.
e.
V případě větších klientů následuje doručení podepsané smlouvy do sídla PayU. U menších klientů došlo v rámci kroku b. k uzavření elektronické smlouvy.
f.
Zákaznický servis PayU založí e-shopu PayU účet a informuje e-shop o přístupových údajích.
g.
Následně založí zákaznický servis na PayU účtu e-shopu SHOP a POS.
h.
Aktivace platebních metod dle smlouvy.
i.
Zákaznický servis PayU se přihlásí do zabezpečeného prostředí developera, kde vyplní IČ, číslo POSu a přístupové klíče.
j.
Developer zajistí automatické přijetí a uložení klíčů pro daný e-shop a aktivaci plateb.
2
7
www.payu.cz
2.4 Jak probíhá proces platby prostřednictvím platební brány PayU
2
Proces nákupu na internetu se standardně skládá z následujících po sobě jdoucích kroků: 1.
Nákupní košík.
2.
Výběr adresy pro doručení zboží, způsobu dopravy a platby. V tomto kroku by měly být zobrazeny jednotlivé platební metody, které PayU nabízí.
3.
Rekapitulace objednávky.
4.
Přesměrování na banku / platební bránu.
5.
V případě nezdaru zaslání e-mailu s návratovou URL adresou s výběrem platebních metod, nebo vložit možnost výběru přímo na negativní návratovou adresu.
6.
Provedení platby.
7.
Přesměrování na správnou či chybnou návratovou adresu, která by měla obsahovat: a) OK – Potvrzení objednávky s informací o jejím přijetí a úspěšném zahájení platby v případě správné návratové adresy. b) NOK – Potvrzení objednávky s informací o tom, že objednávka byla přijata, ale NEBYLA zaplacena, včetně seznamu dostupných platebních metod pro opětovnou platbu v případě chybné návratové adresy.
2.5 Co je potřeba zajistit na straně developera Správnou prezentaci PayU v šabloně. PayU není platební metoda, a tudíž nemůže být jako platební metoda prezentována. Zákazník nikdy nevybírá PayU, ale vždy platební metodu, kterou PayU zprostředkovává. (např. svou banku, přes kterou bude platit) Uskutečňování plateb prostřednictvím šablony PayU. Odesílání požadavku na platbu do PayU a přesměrování zákazníka na platební bránu okamžitě po potvrzení objednávky zákazníkem.
8
www.payu.cz
2.6 Šablona pro platby procesované prostřednictvím platební brány PayU
2
Platební šablona PayU je poskytována všem developerům a e-shopům ve formě JavaScript kódu. Tento kód je nutné vložit do zdrojového kódu webových stránek tak, jak je popsáno v technické dokumentaci PayU. JavaScriptem je zajištěna jednotná prezentace PayU v platebních šablonách všech e-shopů, které online platby prostřednictvím PayU nabízejí. Pokud dojde k jakékoliv změně v šabloně PayU, bude okamžitě promítnuta ve všech nákupních košících e-shopů stejně. Šablonu lze zároveň přizpůsobit potřebám e-shopů a nastavit si v nákupním košíku na míru její velikost, texty, fonty. Co není možné měnit jsou loga a pořadí platebních metod v šabloně.
9
www.payu.cz
2.7 Zásady pro umístění PayU v nákupním košíku
2
Umístění online platebních metod na prvním místě, další v pořadí následují platební metody jiných poskytovatelů. Pořadí platebních metod: rychlé online převody bank, platba platebními kartami a přes Mobito, ostatní platební metody. Proces výběru platební metody musí být z pohledu kupujícího co nejjednodušší. Po výběru platební metody kupující v ideálním případě už jen potvrdí celou objednávku jediným klikem. Kupující je po potvrzení objednávky přesměrován přes PayU přímo na banku případně jinou platební bránu nezbytnou pro dokončení platby.
Developer je povinen poskytnout PayU vzor návratových adres tak, aby bylo možné je použít pro každý e-shop, který používá systém developera a uzavře smlouvu s PayU o poskytování online plateb. V tomto vzoru bude následně upravena doména jednotlivých e-shopů. V administraci developera ani e-shopu není možno zapínat nebo vypínat platební metody PayU. Veškeré informace v administraci developera týkající se PayU podléhají schválení PayU.
10
www.payu.cz
2.8 Povinné podmínky spolupráce
2
Klíčové kroky, které musí být splněny proto, aby mohl developer nabízet řešení s platbami PayU pro své e-shopy: 1.
Smlouva s PayU (Developer × PayU).
2.
Správná implementace platební brány a alespoň 1 uskutečněná (ostrá) transakce na testovacím rozhraní developera.
3.
Vytvořená informační stránky o PayU na webu developera, informující o platební bráně nabízených platbách přes PayU, společně s odkazem na automatický registrační proces.
4.
Vytvoření odkazu na bod 3 v administračním rozhraní developera (správa e-shopu v sekci plateb).
5.
Zajištění formuláře na straně developera dostupného pro zákaznický servis PayU po zalogování (https stránka, login a heslo jen pro PayU), kde bude moci zákaznický servis PayU vkládat informace potřebné ke spuštění plateb.
6.
Nastavení automatického zpracování údajů developerem a nastavení do administračního rozhraní e-shopu.
7.
Dodání vzorové návratové URL adresy PayU adresy pro oznámení a typu kódování (např. UTF8, WIN-1250 atd.).
8.
Dohoda s obchodníkem či zástupcem marketingu PayU na komunikační strategii vůči e-shopům (mailingy, newslettery), případně předání akvizičního seznamu obchodníků (e-shopů) pro kontaktování ze strany PayU.
9.
Implementace modulu PayU dle manuálu, autorizace implementace pověřeným pracovníkem PayU.
11
www.payu.cz
2.9 Propagace platební brány PayU developerem
2
Za účelem jednotné prezentace značky podléhají veškeré výstupy corporate design manuálu skupiny PayU a musejí být odsouhlaseny zástupcem společnosti PayU.
V administraci e-shopu je na straně developera povinnost uvádět PayU v sekci plateb jako: Platební brána PayU – jednoduché a bezpečné online platby.
Pro propagaci a aktivní nabízení online plateb prostřednictvím platební brány PayU může developer využít následující komunikační nástroje a materiály:
Logo PayU Webové bannery PayU E-mailing Newsletter Microsite o online platbách
Tyto formy propagace může developer využít jak na svém webu, tak při komunikaci směrem ke svým klientům a provozovatelům e-shopů. Další formy propagace a společných marketingových aktivit jsou ze strany PayU vždy vítány a podporovány
V případě zájmu o zaslání výše uvedených podkladů kontaktujte svého obchodního zástupce nebo přímo [email protected].
12
www.payu.cz
Ukázky e-mailingu:
2
13
www.payu.cz
Ukázky bannerů:
2
14
www.payu.cz
Implementace PayU
3
15
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.
16
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
17
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
1. Výběr zboží/služby na stránkách e-shopu
3. E-shop zasílá do PayU formulář nové platby
2. Výběr platební brány
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.
18
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.
19
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).
K vytvoření platebního formuláře je zapotřebí standardní HTML formulář s příslušnými atributy (viz parametry nové platby uvedené výše). Proměnné hodnoty, které jsou požadovány k vytvoření platebního formuláře, mohou být staženy prostřednictvím požadavku na vzdálený server PayU.
20
www.payu.cz
XML soubor je možné ze systému PayU načíst z tohoto místa:
3
UrlPayU/Encoding/xml/pos_id/KK/paytype.xml Jednotlivé parametry mají následující význam:
Tento soubor obsahuje atributy, které se mohou v průběhu času měnit, proto ho není možné používat stále, ale je potřeba jej pravidelně obnovovat (s doporučenou frekvencí jednou za hodinu).
3
Po stažení XML souboru jej aplikace Obchodu může zpracovat za účelem vytvoření platebního formuláře. Příklad: <scriptlanguage=“JavaScript“ type=“text/javascript“> Platební formulář by měl být vytvořen v souladu s aktuálními Obchodními podmínkami a dalšími platnými smlouvami.
22
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.
23
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)
24
www.payu.cz
V odpovědi obdrží aplikace Obchodu následující informace: Formát „txt“:
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í
26
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
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”: <status>ERROR <error> 503 <message>
28
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 anebo 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
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
30
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ů. 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.
31
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.
32
www.payu.cz
Vzhled platební brány PayU na e-shopu
4
33
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. S cílem umožnit zákazníkovi rychlou orientaci při výběru platební metody byly vytvořeny platební šablony PayU. Podoba těchto šablon je zobrazena v Příloze 6. Příklady implementace šablon na konkrétních e-shopech jsou zobrazeny v příloze 7.
4.2 Implementace V případě, že e-shop nemá zájem PayU šablonu využít, vytváří na svých stránkách způsob zobrazení platebních metod zákazníkovi sám. V takovém případě prosím dodržujte následující 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 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. 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).
34
www.payu.cz
4.3 Nákupní proces a uživatelsky přívětivá implementace
4
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í. Zjednodušení nákupního procesu vyžaduje optimalizaci tří základních klíčových prvků: navigace, vizualizace a rychlosti.
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.
35
www.payu.cz
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.
4
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.
36
www.payu.cz
4.7 Edukace zákazníků a marketing
4
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 platbu přes PayU, pak můžete navštívit náš testovací e-shop na této webové stránce http://payu.fcostry.cz 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.
37
www.payu.cz
Povinné parametry implementace
5
38
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.
39
www.payu.cz
Přílohy
6
40
www.payu.cz
6
6
Přílohy 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.
41
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
6
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í“.
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
45
www.payu.cz
Příloha 5 – Ukázka php skriptu, který zjišťuje stav transakce
6
Tento skript naleznete také na našich internetových stránkách http://www.payu.cz/ke-stazeni
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”);
46
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”);
// 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(“/.*<pos_id>([0-9]*)<\/pos_id>.*<session_id>(.*)<\/session_id>.*(.*)”. “<\/order_id>.*([0-9]*)<\/amount>.*<status>([0-9]*)<\/status>.*<desc>(.*)<\/ desc>.*”. “([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
6
/* 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;
48
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).... }
6
?>
49
www.payu.cz
7
Příloha 6 – PayU šablony (templates)
šablona č. 3 (česká verze)
šablona č. 5 (anglická verze)
50
www.payu.cz
Příloha 7 – Ukázka implementace PayU Implementace pomocí šablony
Příloha 9 – 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.
53
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
54 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
55 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é.
56
www.payu.cz
Příloha 10 – Změny v manuálu podle verzí
6
VERZE 1.1 Kapitola 3, str. 16 – text „www.payu.cz“ nahrazen textem „secure.payu.com” Kapitola 3, str. 17 – text „www.payu.cz“ nahrazen textem „secure.payu.com” Kapitola 3, str. 20 – text „www.payu.cz“ nahrazen textem „secure.payu.com” Kapitola 3, str. 21 – text „www.payu.cz“ nahrazen textem „secure.payu.com” (2×) Kapitola 6, str. 43 – přidání šipky mezi „Odmítnuta (status 3)“ a „Skončena (status 99)“ Kapitola 6, str. 45 – přidání chyby č. 508 VERZE 2.0 Kapitola 6, str. 46 – text „www.payu.cz“ nahrazen textem „secure.payu.com” Kapitola 6, str. 49 – text „z www.payu.cz“ nahrazen textem „ze secure.payu.com” kapitola 3, str. 22 – text „za 24 hodin“ nahrazen textem „za hodinu“ kapitola 3, str. 29 – změna věty „Jedná-li se… platby.“ a věty „I v případě… atd.).“ kapitola 4, str. 34 – odstraněn text „platba superCASH“ kapitola 6, str. 41 – odebrání „superCASH“ řádku tabulky kapitola 6, str. 50 – úprava obrázku kapitola 6, str. 51 – úprava obrázku Kapitola 6, str. 45 – update seznamu chyb Kapitola 6, str. 50 – odebrání šablon 4 a 6 Kapitola 3, str. 32 – přidání modrého rámečku Kapitola 7, str. 53 – 56 – přidání přílohy Kapitola 3, str 19 – přidání textu „Ujistěte se…“ Kapitola 5, str. 39 – změna textu „v kapitole“ na „v příloze“ Kapitola 7, str. 45 – přidání chyby 212 Kapitola 7, str. 50 – přidání textu „(česká verze)“ a „(anglická verze)“; výměna obrázků VERZE 2.1 Kapitola 3, str. 19 – přidání parametru platby „pay_type“ Kapitola 3, str. 22 – přidání textu a Kapitola 6, str. 41 – přidání nových položek „era, cb, psc“ Kapitola 6, str. 41 – změna hodnoty sloupce u metody „t“ z „1,00 – 1000,00“ na „0,50 – 1000,00“ Kapitola 6, str. 42 – (status 3) přidání textu „Obchod by měl…“ Kapitola 6, str. 41 – změna textu „mPenize“ na „mTransfer“ Celý dokument – zrušení ligatury „fi“ na „fi“ Kapitola 3, str. 19 – změna parametru „no“ na „yes“ (řádek language)
57
www.payu.cz
VERZE 2.2 Obsah, str. 2 – oprava textu „příloha 5“
6
Kapitola 3, str. 19 – změna „http:www.chemie.fu-berlin.de/…“ na „https://www.iso.org/obp/…“ Kapitola 3, str. 19 – změna „http:www.ics.uci.edu/…“ na „http://www-01.sil.org/…“ Kapitola 3, str. 22 – vložení řádku „“ Kapitola 3, str. 23 – vložení řádků „sig_ext“ a „sig_ext_order“ Obálka, str. 59 – změna tel. č. na „226 221 951“
