Příručka pro použití platební brány

Transcription

Příručka pro použití platební brány
Příručka pro použití
Platební brány PaySec
Verze dokumentu 1.20
Upozornění:
ČSOB si vyhrazuje právo dokument upravovat, měnit
adresy (umístění) a rozhraní služeb systému PaySec.
V případě dotazů prosím kontaktujte Helpdesk PaySec.
Příručka pro použití Platební brány PaySec verze 1.20
Obsah
1.
Platební brána PaySec - obecné podmínky používání
4
1.1.
Základní pojmy
1.1.1.
Platební řešení PaySec e-commerce
1.1.2.
Elektronická peněženka PaySec
1.1.3.
PaySec
1.1.4.
Platební brána platebního řešení PaySec
1.1.5.
Mobilní platební brána platebního řešení PaySec
1.1.6.
Brána pro chytré telefony platebního řešení PaySec
1.1.7.
Webová služba MAPI (Merchant API)
1.1.8.
Typy platebních metod
4
4
4
4
4
5
6
6
7
2.
8
Platba prostřednictvím Platební brány PaySec
2.1.
Ve prospěch internetového obchodu z Konta PaySec
8
2.2.
Ve prospěch internetového obchodu běžným bankovním převodem z běžného účtu jiné banky
(QR platbou) nebo složenkou (Offline platba)
9
2.3.
Ve prospěch internetového obchodu on-line z běžného účtu u ČSOB nebo Poštovní spořitelny /
Era
10
2.4.
2.4 Ve prospěch internetového obchodu platebními kartami
11
2.5.
Ve prospěch internetového obchodu MasterCard Mobile
12
2.6.
Možné kolize a jejich řešení
13
2.6.1.
Zákazník se nevrátil zpět do e-shopu z platební brány PaySec
13
2.6.2.
Transakci se nepodařilo zrealizovat
13
2.6.3.
Stav transakce se nepodařilo ověřit
13
2.6.4.
Přerušení transakce před přijetím do systému
14
2.6.5.
Automatická periodická kontrola stavu nedokončených objednávek
14
3.
Integrace PaySec se stránkami obchodníka
3.1.
3.2.
3.3.
3.4.
3.4.1.
3.4.2.
3.4.3.
3.4.4.
4.
Vstupní parametry pro platební bránu
Vstupní parametry pro Mobilní platební bránu
Jakou platební metodu zvolit
Platba z Internetového obchodu
Příklad formuláře e-shopu – klasická verze (test)
Příklad formuláře e-shopu – klasická verze (produkce)
Příklad formuláře e-shopu – mobilní verze (test)
Příklad formuláře e-shopu – mobilní verze (produkce)
16
16
19
20
21
21
21
22
22
Rozhraní Merchant API (MAPI)
23
4.1.
Testovací a produkční prostředí
4.2.
Zabezpečení komunikace
4.3.
Metody
4.3.1.
VerifyTransactionIsPaid
4.3.2.
GetStatement a GetStatementWithBalance
4.3.3.
PaymentReturn
4.3.4.
RepeatPayment
4.3.5.
depositBlockedTransaction
4.3.6.
cancelBlockedTransaction
23
24
24
25
27
32
34
35
36
5.
5.1.
5.2.
Testovací platební brána – uživatelské rozhraní
Přihlášení do uživatelského rozhraní
Platební brána – menu po přihlášení
© 2007-2014 Československá obchodní banka, a.s.
37
37
38
Příručka pro použití Platební brány PaySec verze 1.20
5.3.
5.4.
5.5.
5.6.
Platební
Platební
Platební
Platební
brána
brána
brána
brána
–
–
–
–
MAPI
detail volání MAPI
Transakce
detail transakce
38
39
40
41
6.
FAQ – nejčastější dotazy
42
7.
Označení internetového obchodu logem PaySec
43
8.
Přílohy
44
8.1.
Bezpečná komunikace
8.1.1.
Nastavení serverového certifikátu jako důvěryhodného
8.2.
Příklady volání webové služby MAPI z různých technologií
8.2.1.
Definice SOAP zpráv
8.2.2.
C# 2.0 pomocí SOAP zpráv
8.2.3.
PHP 5.2.5
8.2.4.
ASP.NET 2.0
8.2.5.
ASP 3.0 – Visual Basic
8.2.6.
Python
© 2007-2014 Československá obchodní banka, a.s.
44
44
45
45
46
47
47
49
50
Příručka pro použití Platební brány PaySec verze 1.20
1. Platební brána PaySec - obecné podmínky používání
Použití platební brány k přijímání plateb v systému PaySec je vázáno na vlastnictví Konta pro
obchodníky a vztahují se na ně Obchodní podmínky PaySec.
Konto pro obchodníky si může založit Fyzická osoba-podnikatel nebo Právnická osoba.
Identifikační formulář majitele Konta pro obchodníky je k dispozici na adrese www.paysec.cz.
1.1. Základní pojmy
1.1.1.
Platební řešení PaySec e-commerce
Platební řešení PaySec e-commerce je univerzální on-line platební řešení umožňující
obchodníkovi (e-shopu nebo neziskové organizaci) příjem plateb na Internetu z několika
platebních metod v jednom řešení.
1.1.2.
Elektronická peněženka PaySec
Elektronická peněženka PaySec je univerzální on-line platební nástroj pro platby na Internetu na
bázi předplaceného konta. Pomocí Konta PaySec je možné platit u obchodníků, kteří platbu
PaySec podporují, nebo provádět platby mezi Konty PaySec.
1.1.3.
PaySec
Systém serverů, který nabízí obchodníkům (e-shopům a neziskovým organizacím) platební řešení
PaySec e-commerce a klientům elektronickou peněženku PaySec.
1.1.4.
Platební brána platebního řešení PaySec
Platební brána (uživatelské rozhraní) je samostatná část portálu PaySec, která slouží k realizaci
jedné transakce mezi klientem (platí) a obchodníkem (přijímá platbu). Pomocí platební brány
může nakupující pohodlně a rychle autorizovat transakci a zaplatit tak obchodníkovi. Platební
brána funguje na serveru PaySec a sama o sobě nevyžaduje žádnou instalaci. Obchodník si
realizuje pouze jednu implementaci platební brány a díky ní může zákazníkům nabídnout několik
platebních metod. Na tuto stránku se můžete dostat výhradně přesměrováním ze stránek
obchodníka v případě, že klient zvolil platbu pomocí PaySec.
Platební brána umožňuje klientovi výběr mezi více platebními metodami

PaySec (platba z Konta PaySec klienta na Konto PaySec obchodníka)

ČSOB (platba z běžného účtu klienta u ČSOB na Konto PaySec obchodníka)

Poštovní spořitelna / Era (platba z běžného účtu klienta u Poštovní spořitelny / Era na
Konto PaySec obchodníka)

Platební karty (platby platebními kartami asociací MasterCard, VISA a Diners Club na
Konto PaySec obchodníka)

MasterCard Mobile (platba platebními kartami asociací MasterCard a VISA
prostřednictvím smart aplikace MasterCard Mobile)

Běžný bankovní převod / složenka / QR platba (offline platba) (platba převodem z
běžného účtu v libovolné bance pomocí internetového bankovnictví nebo Smartbankignu
nebo složenkou na Konto PaySec obchodníka)
Klient tedy nemusí vlastnit Konto PaySec a přesto může obchodníkovi zaplatit z běžného účtu u
ČSOB nebo Poštovní spořitelny / Era, pomocí platební karty libovolné banky nebo platebním
příkazem z běžného účtu libovolného banky v ČR, případně složenkou na České poště.
Platební brána existuje v testovací a produkční verzi.
 Testovací verze:
https://testgateway.paysec.cz/GateWay.aspx
 Produkční verze:
https://gateway.paysec.cz/GateWay.aspx
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Platební brána z pohledu klienta
1.1.5.
Mobilní platební brána platebního řešení PaySec
Mobilní platební brána je zjednodušenou verzí klasické platební brány a je vhodná pro e-shopy,
které mají mobilní webovou verzi webu / e-shopu.
Od klasické platební brány se mobilní verze odlišuje následujícími vlastnostmi:




Produkční verze je provozována na adrese:
https://gateway.paysec.cz/MobileGateWay.aspx
Testovací verze je provozována na adrese
https://testgateway.paysec.cz/MobileGateWay.aspx
Její GUI je zjednodušené
Nabízí pouze tyto platební metody:
o Platební karty (platby platebními kartami asociací MasterCard, VISA a Diners
Club na Konto PaySec obchodníka)
o PaySec (platba z Konta PaySec klienta na Konto PaySec obchodníka)

Uživatel PaySec nemůže provádět platby vyžadující autorizaci SMS
o ČSOB Smartbanking (platba z běžného účtu klienta u ČSOB na Konto PaySec
obchodníka prostřednictvím ČSOB Smartbankingu)
o Era Smartbanking (platba z běžného účtu klienta u Poštovní spořitelny / Era na
Konto PaySec obchodníka prostřednictvím Era Smartbankingu)
o MasterCard Mobile (platba platebními kartami asociací MasterCard a VISA
prostřednictvím smart aplikace MasterCard Mobile)
Platební metody ČSOB Smartbanking, Era Smartbanking a MasterCard Mobile se
zobrazí uživateli pouze v tom případě, že je mobilní brána zobrazena ze zařízení
s operačním systémem Android nebo Apple iOS.
Upozornění: vstupní parametry pro klasickou a mobilní verzi platební brány se liší především
v parametru Sessionless. Rozdíl v implementaci mezi klasickou a mobilní platební brány je v adrese
a dodatečném parametru Sessionless pro mobilní bránu. E-shop používající mobilní bránu nesmí být
závislý na session, ale rozpoznat zákazníka vracejícího se z brány pomocí parametru zaslaného eshopem do parametru BackURL. Blíže viz kapitola 3.2.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Mobilní platební brána z pohledu klienta
1.1.6.
Brána pro chytré telefony
platebního řešení PaySec
Platební řešení PaySec nabízí pro e-shopy poskytující své zboží
nebo služby prostřednictvím nativních smart aplikací pro telefony
nebo tablety s operačním systémem Google Android nebo
Apple iOS speciální PaySec bránu pro chytré telefony.
Technická specifikace PaySec brány pro chytré telefony je popsána v samostatné dokumentaci.
1.1.7.
Webová služba MAPI (Merchant API)
MAPI je webová služba (aplikační rozhraní - API) platebního řešení PaySec, které umožňuje
majitelům Konta pro obchodníky ověřit provedení transakce zadané prostřednictvím
Platební brány, Mobilní platební brány i Brány pro chytré telefony. Toto rozhraní je určeno
obchodníkům, kteří expedují zboží nebo službu. Pro využití rozhraní MAPI je nutné napojit
internetový obchod na webovou službu PaySec. To umožní e-shopu automaticky ověřovat
provedení transakcí klientů všemi platebními metodami. Případně automatizovaně provádět
vratky. Použití MAPI vyžaduje základní programátorské zkušenosti. MAPI existuje v testovací a
produkční verzi a vždy ve dvou variantách. Viz kapitola Rozhraní Merchant API (MAPI).
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
1.1.8.
Typy platebních metod
Online platební metody

Platby těmito metodami jsou prováděny v reálném čase. Tzn. po provedení platby a
návratu z platební brány zpět do e-shopu je již známo, zda byla platba provedena či
nikoli. Pouze ve výjimečných případech (výpadky externích systémů, výpadky síťového
spojení, atp.) může být platba dokončena až později.

Metody: PaySec, ČSOB, Poštovní spořitelna / Era, Platební karty, MasterCard Mobile
Offline platební metody

Ověření provedení platby není možné provést ihned po přesměrování z platební brány
zpět do e-shopu. Toto je případ platební metody Běžný bankovní převod / složenka / QR
platba, kdy musí nejdříve proběhnout převod mezi bankou zákazníka a ČSOB (platba je
připisována na sběrný účet PaySec). To trvá typicky od několika hodin až po několik dnů
v závisti na tom, jak rychle odešle platbu banka zákazníka. Připsání plateb je ihned po
jejich obdržení z jiné banky.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
2. Platba prostřednictvím Platební brány PaySec
Platba pomocí platebního řešení PaySec s využitím platební brány probíhá následovně:
2.1.
Ve prospěch internetového obchodu z Konta PaySec
5
internetový obchod
PaySec
61
4
2
3
Uživatel
Přehled komunikace při platbě v internetovém obchodě
1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány
PaySec.
2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu
(rozcestník platebních metod) a předá jí informace o požadované platbě. Přesměrování musí
provedeno tak, aby se rozcestník platebních metod PaySec zobrazil přes celé okno
prohlížeče a v URL bylo uvedeno URL platební brány PaySec.
3. Zákazník si na platební bráně vybere platební metodu PaySec. Zákazník bude přesměrován
na přihlášení do svého PaySec Konta. Po zadání přihlašovacího jména a hesla do systému
PaySec potvrdí transakci. V případě transakce vyšší než limit, který si zákazník nastavil ještě
autorizuje transakci pomocí SMS. Peníze jsou převedeny na Konto obchodníka.
4. Internetový prohlížeč uživatele je přesměrován zpět na adresu, která byla předána platební
bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené
platby (nebo informaci o zamítnutí platby zákazníkem).
5. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím
webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla
transakce skutečně provedena. Tento krok je nezbytný k bezpečnému ověření
skutečného stavu provedení transakce. Ověření transakce musí být provedeno
ihned po zavolání návratového URL e-shopu a to tak rychle, aby e-shop mohl na
stránce, kterou klientovi zobrazí po jeho návratu z platební brány PaySec mohl
rovnou zobrazit odpověď, kterou získal pomocí tohoto ověření transakce. Typicky
během maximálně jednotek sekund.
6. Zákazníkovi je zobrazena informace o úspěšném nebo neúspěšném provedení transakce a
zaplacené zboží (služba, obsah) je předáno k odeslání (stažení a podobně).
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
2.2. Ve prospěch internetového obchodu běžným bankovním
převodem z běžného účtu jiné banky (QR platbou) nebo složenkou
(Offline platba)
1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány
PaySec.
2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník
platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak,
aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo
uvedeno URL platební brány PaySec.
3. Zákazník si na platební bráně vybere platební metodu Bankovní převod/QR platba.
4. Uživateli jsou zobrazeny údaje pro provedení platebního příkazu. (Číslo sběrného účtu systému
PaySec. specifický a variabilní symbol, atd.). Tyto údaje jsou zobrazeny jednak textově a jednak
pomocí mezibankovního QR kódu.
5. Zákazník provede platbu ze svého internetového bankovnictví, podáním platebního příkazu ve své
bance nebo podáním složenky na České poště nebo načtením QR kódu Smartbankingem své
banky. Platba je připsána na Konto PaySec obchodníka až po připsání částky na sběrný účet
systému PaySec, což může trvat od několika hodin až po 3 dny. Na Konto pro obchodníky je
platba připsána ihned po obdržení platby z jiné banky přes clearing ČNB.
6. Internetový prohlížeč uživatele je po kliknutí na tlačítka Potvrdit platbu/Odmítnout platbu
přesměrován zpět na adresu, která byla e-shopem předána platební bráně jako jeden
z parametrů. Platební brána PaySec zašle zpět v URL identifikaci provedené platby (nebo informaci
o zamítnutí platby zákazníkem), a dále parametr OfflinePayment=1.
7. Pokud bylo vráceno číslo provedené platby a parametr OfflinePayment=1, zobrazí e-shop
zákazníkovi informaci o čekání na příchozí platbu pomocí běžného bankovního převodu.
8. Zákazníkovi e-shop může ještě jednou zobrazit parametry platby a pokud má k dispozici
zákazníkův e-mailu, tak mu je ještě odešle e-mailem. Parametry platby jsou v ostrém prostředí:
Číslo účtu: 72887288/0300
Částka: určuje e-shop
Specifický symbol: číslo obchodnického PaySec Konta e-shopu
Variabilní symbol: je předán e-shopu v návratovém URL jako TransactionID
Platnost: do kdy musí být platba připsána na PaySec Konto obchodníka (délku platnosti si určuje
obchodník v úvodním nastavení tohoto typu platby)
9. Pokud bylo vráceno číslo provedené platby a parametr OfflinePayment=1, internetový
obchod začne periodicky volat webovou službu VerifyTransactionIsPaid (viz kapitola
4.3.1.), a to až do prvního úspěšného ověření, že byla transakce skutečně provedena
(max. do doby platnosti transakce). Do doby úspěšného ověření je odpověď kód 11,
který značí, že se jedná o čekající transakci běžným bankovním převodem. Tento krok je
nezbytný k bezpečnému ověření
skutečného stavu provedení
transakce.
Po připsání každé platby běžným
bankovním převodem (offline platby) je
zároveň obchodníkovi odeslán informační
email, jehož přílohou je XML soubor s popisem transakce. Email ale není podepsaný
elektronickým podpisem, a proto jej nelze považovat za důvěryhodné potvrzení platby. Nelze
tedy přijetím a zpracováním tohoto emailu nahradit volání MAPI metody VerifyTransactionIsPaid.
Pro přijetí tohoto e-mailu má možnost e-shop nastavit samostatnou e-mailovou adresu, na
kterou jsou zasílány pouze informace o připsání tohoto typu transakcí.
Ukázka XML souboru z informačního emailu o přijaté offline platbě:
<?xml version="1.0" encoding="utf-16"?>
<offlinePayment>
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
<transactionId>101563547</transactionId>
<ucetZakaznika>8857527/0300</ucetZakaznika>
<merchandOrderId>1365773</merchandOrderId>
<castka>100.00 Kč</castka>
</offlinePayment>
2.3. Ve prospěch internetového obchodu on-line z běžného účtu u
ČSOB nebo Poštovní spořitelny / Era
1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány
PaySec.
2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník
platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak,
aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo
uvedeno URL platební brány PaySec.
3. Zákazník si na platební bráně vybere platební metodu ČSOB nebo Poštovní spořitelna / Era.
4. Platební brána přesměruje zákazníka do internetového bankovnictví. V rámci přesměrování jsou
předány všechny informace k provedení platebního příkazu.
5. Zákazník se přihlásí do internetového bankovnictví a provede platební příkaz na sběrný účet
systému PaySec. Do systému PaySec je odesláno avízo o provedení transakce, které umožní
okamžité připsání částky na Konto PaySec obchodníka.
6. Internetové bankovnictví přesměruje zákazníka zpět do systému PaySec, kde proběhne ověření
transakce vůči internetovému bankovnictví a v případě úspěchu připsání částky na Konto PaySec
obchodníka.
7. Internetový prohlížeč uživatele je přesměrován zpět na adresu, která byla e-shopem předána
platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené
platby (nebo informaci o zamítnutí platby zákazníkem).
8. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím
webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce
skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu
provedení transakce. Ověření transakce musí být provedeno ihned po zavolání
návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi
zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou
získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund.
9. Zákazníkovi je zobrazena informace o úspěšném nebo neúspěšném provedení transakce a
zaplacené zboží (služba, obsah je předáno k odeslání (stažení a podobně).
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
2.4. 2.4 Ve prospěch internetového obchodu platebními kartami
1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány
PaySec.
2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník
platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak,
aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo
uvedeno URL platební brány PaySec.
3. Zákazník si na platební bráně vybere platební metodu Platební karta.
4. Platební brána přesměruje zákazníka na 3D Secure platební bránu GP webpay. V rámci
přesměrování jsou předány všechny informace k provedení platby.
5. Zákazník vyplní údaje o platební kartě (číslo karty, platnost karty, CVV/CVC kód) a případně 3D
secure heslo ke kartě, pokud mu ho jeho banka poskytka. Do systému PaySec je odesláno avízo o
provedení transakce, které umožní okamžité připsání částky na Konto PaySec obchodníka.
6. Platební brána GP webpay přesměruje zákazníka zpět do systému PaySec, kde proběhne ověření
transakce a v případě úspěchu připsání částky na Konto PaySec obchodníka.
7. Internetový prohlížeč uživatele je přesměrován zpět na adresu, která byla e-shopem předána
platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci provedené
platby (nebo informaci o zamítnutí platby zákazníkem).
8. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím
webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce
skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu
provedení transakce. Ověření transakce musí být provedeno ihned po zavolání
návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi
zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou
získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund.
9. Zákazníkovi je zobrazena informace o úspěšném nebo neúspěšném provedení transakce a
zaplacené zboží (služba, obsah) je předáno k odeslání (stažení a podobně).
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
2.5. Ve prospěch internetového obchodu MasterCard Mobile
1. Zákazník v internetovém obchodě vybere zboží a zvolí platbu prostřednictvím platební brány
PaySec.
2. Internetový obchod přesměruje internetový prohlížeč zákazníka na platební bránu (rozcestník
platebních metod) a předá jí informace o požadované platbě. Přesměrování musí provedeno tak,
aby se rozcestník platebních metod PaySec zobrazil přes celé okno prohlížeče a v URL bylo
uvedeno URL platební brány PaySec.
3. Zákazník si na platební bráně vybere platební metodu MasterCard Mobile.
4. Platební brána přesměruje zákazníka na stránku, kde je zobrazen QR kód pro načtení přes
fotoaparát mobilního telefonu, který má nainstalovanou aplikaci MasterCard mobile. Aplikace je
dostupná pro mobilní telefony s Android nebo Apple iOS.
5. Zákazník načte kód do aplikace MasterCard Mobile, případně ho přepíše do aplikace ručně.
6. V aplikaci se zákazníkovi zobrazí parametry platby, zákazník vybere kartu a potvrdí platbu.
7. Platební brána obdrží informaci o provedené platbě a systém PaySec okamžitě připíše částku na
Konto PaySec obchodníka.
8. Platební brána přesměruje Internetový prohlížeč uživatele zpět na adresu, která byla e-shopem
předána platební bráně jako jeden z parametrů. Platební brána PaySec zašle zpět identifikaci
provedené platby (nebo informaci o zamítnutí platby zákazníkem).
9. Pokud bylo vráceno číslo provedené platby, internetový obchod si prostřednictvím
webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) ověří, že byla transakce
skutečně provedena. Tento krok je nezbytný k bezpečnému ověření skutečného stavu
provedení transakce. Ověření transakce musí být provedeno ihned po zavolání
návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi
zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou
získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
2.6. Možné kolize a jejich řešení
2.6.1.
Zákazník se nevrátil zpět do e-shopu z platební brány PaySec
Kdy může nastat kolize





Mezi
Mezi
Mezi
Mezi
Mezi
krokem
krokem
krokem
krokem
krokem
3
2
3
3
3
a
a
a
a
a
4
6
7
7
8
u
u
u
u
u
platby
platby
platby
platby
platby
z peněženky PaySec
běžným bankovním převodem
on-line z běžného účtu ČSOB nebo Poštovní spořitelny / ERA
platební kartou
MasterCard Mobile
Co zobrazit zákazníkovi
Zákazník se již nevrátí na e-shop.
Jak dále postupovat
Internetový obchod implementuje automatickou periodickou kontrolu stavu nedokončených
objednávek (2.6.5) pomocí volání webové služby. Na základě výsledku kontroly jsou objednávky
automaticky zpracovány (transakce je ve stavu provedena) nebo zamítnuty (transakce
neexistuje nebo je ve stavu zamítnutá).
2.6.2.
Transakci se nepodařilo zrealizovat
Kdy může nastat kolize



Zákazník zamítl platbu
Zákazník nesplnil podmínky pro vytvoření transakce, například má zablokovaný účet,
nemá dostatek prostředků nebo pouze nedokončil autorizaci platby a přesměroval svůj
prohlížeč na jinou adresu
Účet obchodníka je blokovaný pro příjem plateb
Co zobrazit zákazníkovi
V případě zamítnutí zobrazí Internetový obchod zákazníkovi text:
„Váš pokyn k zamítnutí platby byl proveden úspěšně.“ 1
V ostatních případech nedochází ke zpětnému přesměrování na Internetový obchod.
Jak dále postupovat
V případě nepřesměrování zákazníka zpět na Internetový obchod implementuje automatickou
periodickou kontrolu stavu nedokončených objednávek pomocí volání webové služby z kapitoly
2.6.5.
2.6.3.
Stav transakce se nepodařilo ověřit
Kdy může nastat kolize





1
Přesměrování na Platební bránu PaySec selže.
Nepodaří se dokončit platbu.
Při přesměrování zpět na Internetový obchod.
V kroku pro ověření platby: Webová služba pro ověření platby je nedostupná.
U platby pomocí běžného bankovního převodu: platba zatím nebyla připsána na sběrný
účet systému PaySec
Obchodník je povinen zobrazit text v přesném znění
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Co zobrazit zákazníkovi
V případě, že byl uživatel úspěšně přesměrován zpět na Internetový obchod s výjimkou běžného
bankovního převodu, zobrazí se zákazníkovi následující text:
„Stav transakce se nepodařilo ověřit. Pracujeme na nápravě.“2
Jak postupovat
Internetový obchod implementuje automatickou periodickou kontrolu stavu nedokončených
objednávek (2.6.5) pomocí volání webové služby3. Na základě výsledku kontroly jsou objednávky
automaticky zpracovány (transakce je ve stavu provedena) nebo zamítnuty (transakce
neexistuje nebo je ve stavu zamítnutá).
2.6.4.
Přerušení transakce před přijetím do systému
Pokud transakce nebyla dokončena nebo vůbec neexistuje, pak nemá obchodník vůči zákazníkovi
žádný závazek a není nutná žádná akce. Transakce nemusí být dokončena zejména z těchto
důvodů:

Selhalo přesměrování klienta na platební bránu

Data předané na platební bránu od obchodníka nebyla validní (formální chyba)

Klientovi se nepodařilo přihlásit do systému (např. při zapomenutém heslu)

Klient se rozhodl, že transakci nebude realizovat a neukončil transakci standardně
stiskem tlačítka „Zamítnout platbu“ (například pouze zavřel okno internetového
prohlížeče).

Platební brána nepřijímá požadavky.
V případě, že by takové situace nastávaly často, může to svědčit o chybě v platební bráně nebo
jen o vysoké fluktuaci (zákazník si to při placení rozmyslí). Ujistěte se, že je platební brána
z pohledu zákazníka funkční. Například používá URL adresu z produkčního prostředí spolu
s číslem Konta z produkčního prostředí. Pozor, číslo Konta a URL adresy pro testovací a
produkční prostředí jsou různé.
2.6.5.
Automatická periodická kontrola stavu nedokončených objednávek
V případech, kdy se nepodaří nebo není možné ověřit transakci voláním webové služby
VerifyTransactionIsPaid (MAPI) ihned po návratu do e-shopu, popř. když k návratu
nedojde, je potřeba aby internetový obchod implementoval a použil automatickou
periodickou kontrolu stavu nedokončených objednávek („čekajících transakcí“) pomocí
volání VerifyTransactionIsPaid. Na základě výsledku kontroly jsou objednávky
automaticky zpracovány (transakce je ve stavu provedena) nebo zamítnuty (transakce
je ve stavu zamítnutá) nebo se ve zvoleném intervalu volání zopakuje (transakce nebo
číslo objednávky neexistuje).

Ověření transakce je možné zkoušet ihned po té, co je zákazník přesměrován
z e-shopu na platební bránu PaySec, kromě platební metody Běžný bankovní
převod, kdy téměř určitě platba ještě nebude zaúčtovaná.

Je možné ověřovat všechny objednávky libovolně staré a libovolně dlouho.

Do doby provedení transakce odpovídá PaySec kódem 4 – transakce neexistuje.
To znamená, že buď vůbec nebyla založeno nebo se čeká na dokončení platby.

Po provedení transakce odpovídá PaySec kódem 0 - Transakce byla úspěšně
zaúčtována.

V případě použití platební metody platba běžným bankovním převodem
odpovídá PaySec do doby zaplacení návratovým kódem 11 – Nezaplacená offline
platba. V tomto případě provádí e-shop ověřování do konce doby platnosti
2
Obchodník je povinen zobrazit text v přesném znění
Jakmile je webová služba dostupná, lze z chybových kódů určit, zda transakce vůbec
proběhla, a pokud ano, tak s jakým výsledkem.
3
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20

tohoto typu transakce (dny) a ne pouze po dobu max. 60 minut jako u on-line
transakcí.
Další méně časté kódy a doporučenou reakci naleznete v odst. 4.3.1.
Doporučujeme následující postup:
1.
provést kontrolu každé objednávky cca 5 - 30 minut po té, co zákazník opustil
e-shop a přešel na platební bránu PaySec (a pak každou minutu po maximálně
60 minut), v případě offline platby nejdříve za 60 minut (a pak každou hodinu
do doby platnosti transakce).
1) v případě odpovědi, která transakci potvrzuje (kód 0) e-shop ihned
označí objednávku za zaplacenou a připíše tuto transakci zákazníkovi
v případě, že se zákazník následně vrátí na e-shop, tak mu ten zobrazí
standardní zprávu o úspěšném přijetí platby – stejně, jako by to učinil
bez periodického ověření
2) v případě odpovědi, která transakci NEpotvrzuje (kód 4) e-shop tuto
objednávku zařadí do dalšího periodického ověření. Zamítavý kód
neznamená, že zákazník během následujících několika minut transakci
nedokončí.
2.
V případě, že při první kontrole transakce byla získána odpověď, která
transakci NEpotvrzuje, bude e-shop opakovat ověřování až do 60 minut po té,
co zákazník opustil e-shop a přešel na platební bránu PaySec
1) v případě odpovědi, která transakci potvrzuje (kód 0) e-shop ihned
označí objednávku za zaplacenou a připíše tuto transakci zákazníkovi
v případě, že se zákazník následně vrátí na e-shop, tak mu ten zobrazí
standardní zprávu o úspěšném přijetí platby – stejně, jako by to učinil
bez periodického ověření
2) v případě odpovědi, která transakci NEpotvrzuje (kód 4) je již velice
nepravděpodobné, že zákazník transakci na platební bráně dokončí. Eshop proto tuto objednávku může vyřadit z dalšího periodického
ověření.
Alternativní postupy periodického ověřování „čekajících transakcí“:

Je možné ověřovat transakci například každou 1 minutu po opuštění e-shopu.
Tím zajistíte maximální on-linovost transakce i případě výpadku internetového
připojení zákazníka před návratem na e-shop.

Ověřování provádějte maximálně 60 minut po opuštění e-shopu.
Upozornění: Kontrolu, zda existuje transakce s Vaším číslem objednávky, má smysl provádět
pouze po určitou dobu (maximálně 20 minut od potvrzení platby zákazníkem pro online platby
(tedy maximálně do 60 minut i po započítání času, který by mohl zákazník strávit mezi
přesměrování z e-shopu a potvrzením platby a pro offline platby počet dnů, který máte
nastavený pro platnost platebních údajů - transakce) od vytvoření objednávky. Po uplynutí této
doby je 100%, že transakce již nebude zrealizována.
POZOR: pokud není on-line platba ve prospěch e-shopu úspěšně ověřena
(s návratovým kódem 0) do 20 minut od jejího provedení, je platba automaticky
stornována a plná částka je vrácena zpět zákazníkovi. V případě pokusu o ověření
transakce následně je e-shopu vrácen návratový kód 1.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
3. Integrace PaySec se stránkami obchodníka
Při realizaci platby na Internetu pomocí platebního řešení PaySec je klient přesměrován
z obchodu / portálu na Platební bránu PaySec, kde autorizuje transakci, a následně je
přesměrován zpět na obchod/portál obchodníka. Ten pak dle využívané služby (internetový
obchod / darovací platební tlačítko) informuje klienta o dalším postupu.
3.1. Vstupní parametry pro platební bránu
Platební brána přijímá požadavky prostřednictvím metody HTTP POST (viz specifikace W3C)
s následujícími povinnými parametry:
Parametr
Popis
MicroaccountNumber
Číslo Konta internetového obchodu (sedmimístné číslo; musí
jít o aktivní Konto pro obchodníky v systému PaySec).
Amount
Částka v CZK, která má být uhrazena (bez oddělení tisíců;
dvě desetinná místa oddělená tečkou).
MerchantOrderId
(Tento parametr se
používá v případě, že
provozujete Internetový
obchod)
Číslo objednávky (obsahuje číslice, písmena abecedy a
speciální znaky (! , . : ; ] ) % ( [ ‘ * / #_ - + \), musí být
pro každou platbu v rámci Konta obchodníka unikátní).
U platby v systému PaySec bude následně toto číslo uvedeno
jako Identifikace platby (variabilní symbol).
V GetStatement bude uvedeno v parametru ClientIdentifier
Upozornění: Parametr MerchantOrderId může obsahovat
maximálně 30 znaků.
OrderId
(Tento parametr se
používá pouze
pro darovací platební
tlačítko, kde se
neexpeduje žádné zboží
nebo služba)
Variabilní symbol platby (obsahuje číslice, písmena abecedy a
speciální znaky obsahuje číslice, písmena abecedy a speciální
znaky (! , . : ; ] ) % ( [ ‘ * / #_ - + \), nemusí být unikátní).
U platby v systému PaySec bude následně toto číslo uvedeno
jako Identifikace platby (variabilní symbol).
V GetStatement bude uvedeno v parametru ClientIdentifier
Upozornění: Budete-li posílat číslo objednávky v parametru
OrderId, nebude možné ověřit skutečný stav transakce
pomocí volání MAPI! Návratový kód bude vždy 4 (transakce
nenalezena). Použijte parametr MerchantOrderId, chcete-li
stav transakce ověřovat.
V případě použití MerchantOrderId už nepoužívejte
parametr OrderId.
MessageForTarget
Zpráva pro příjemce platby (obchodníka; zpravidla popis
objednávky), které bude zobrazená klientovi a měla by
charakterizovat nakupované zboží/obsah/služby. Plátce může
zprávu upravit v průběhu platby.
U platby bude uvedena jako Zpráva pro příjemce.
BackURL
Adresa, na kterou bude internetový prohlížeč přesměrován
po provedení platby (například
http://www.shop.cz/platba.php?tid={0}).
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Řetězec {0} bude nahrazen identifikátorem transakce, a to
následovně:
Pokud byla platba zákazníkem zamítnuta a nebyla uvedena
URL adresa na kterou se má přesměrovat v případě
odmítnutí, pak má identifikátor hodnotu 0 (např.
http://www.shop.cz/platba.php?tid=0).
Pokud byl proces zaplacení dokončen, pak má identifikátor
hodnotu odpovídající číslu transakce v systému PaySec (větší
než 0, např.
http://www.shop.cz/platba.php?tid=1688).
Jako volitelný parametr je možné do URL zadat navyše
řetezec {1}, který bude nahrazen hodnotou
MerchantOrderId (pokud byla tato hodnota platební bráně
předána), např.
http://www.shop.cz/platba.php?tid={0}&merchantOr
derId={1}.
Upozornění: Řetězec {0} je povinný jenom v případě, když
je uveden i řetězec {1}.
Upozornění: Nezapomeňte, že skutečný stav transakce
zjistíte teprve po volání webové služby MAPI.
Upozornění: Pro validaci zda je URL správné se používá
následující regulární výraz:
^(?<Protocol>https?):\/\/(?<Domain>[\w@][\w.:@
\-]+)\/?((?<FT>[\w\.?=%&=\@/$,]*\{0\})|(?<FtM>(?<FT>[\w\.?=%&=\@/$,]*\{0\})(?<MerchantOrderId>[\w\.?=%&=\@/$,]*\{1\}))|(?<MFt>(?<MerchantOrderId>[\w\.?
=%&=\-@/$,]*\{1\})(?<FT>[\w\.?=%&=\@/$,]*\{0\})))?(?<ParametersRest>[\w\.?=%&=\@/$,]*)$
CancelURL
Adresa, na kterou bude internetový prohlížeč přesměrován
po odmítnutí platby (například
http://www.shop.cz/platba.php).
Jako volitelné parametry je do URL možné zadat řetězce {0}
a {1} (buď jenom řetezec {0} nebo oba, a teda {0} a {1}).
Řetezec {0} bude nahrazen číslem transakce 0 (značí, že
transakce byla odmítnuta) a řetězec {1} hodnotou
MerchantOrderId, pokud byla tato hodnota platební bráně
předána.
Upozornění: Řetězec {0} je povinný jenom v případě, když
je uveden i řetězec {1}.
Upozornění: Pro validaci zda je URL správné se používá
následující regulární výraz:
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
^(?<Protocol>https?):\/\/(?<Domain>[\w@][\w.:@
\-]+)\/?((?<FT>[\w\.?=%&=\@/$,]*\{0\})|(?<FtM>(?<FT>[\w\.?=%&=\@/$,]*\{0\})(?<MerchantOrderId>[\w\.?=%&=\@/$,]*\{1\}))|(?<MFt>(?<MerchantOrderId>[\w\.?
=%&=\-@/$,]*\{1\})(?<FT>[\w\.?=%&=\@/$,]*\{0\})))?(?<ParametersRest>[\w\.?=%&=\@/$,]*)$
Note
(nepovinné)
Popis objednávky, který by měl charakterizovat nakupované
zboží/obsah/služby. Tento popis nebude zobrazen na detailu
platby, ani z pohledu klienta, ani z pohledu obchodníka.
Najdete ho pouze ve výpisu transakcí po přihlášení do
systému nebo jako jeden z výstupních parametrů webové
služby PaySec (metoda GetStatement).
Upozornění: Popis objednávky není povinný a může
obsahovat maximálně 100 znaků.
RepeatTemplate
(nepovinné)
Nepovinný parametr, určen pro funkcionalitu opakované
platby. Pokud je RepeatTemplate=1, proběhne daná platba
standardním způsobem, navíc je označena jako šablona pro
platbu opakovanou. Následnou platbu s využitím takto
vytvořené šablony provádí obchodník přes MAPI rozhraní.
Poznámka: V současné době lze funkcionalitu opakované
platby použít pouze pro platbu platební kartou, navíc je
použití této funkce podmíněno nastavením obchodního konta.
BlockTransaction
(nepovinné)
Nepovinný parametr, určen pro funkcionalitu
předautorizované (blokované) platby. Pokud je transakce
označena jako předautorizovaná, tj. BlockTransaction=1,
neproběhne zaúčtování částky na konto obchodníka, ale
částka je pouze předautorizována ve prospěch konta
obchodníka. Samotné zaúčtování, resp. zrušení autorizace
provádí obchodník přes MAPI rozhraní.
Poznámka: V současné době lze funkcionalitu
předautorizované platby použít pouze pro platbu platební
kartou.
SkipToPaymentMeth
od
Nepovinný parametr, určen pro přeskočení rozcestníku na
zvolenou platební metodu. Jako hodnota se udává číslo
platební metody, která se má použít:
1 – PaySec
2 – Platba z účtu ČSOB/ČSOB Smartbanking
3 - Platba z účtu Poštovní spořitelny/ERA Smartbanking
4 – Platební karta
5 – Běžný bankovní převod/složenka
7 – MasterCard Mobile
Příklad: SkipToPaymentMethod=2 (přeskočení přímo na
platbu z účtu ČSOB)
Tento parametr je podporován na platební i na mobilní
platební bráně.
Poznámka: Platební metoda musí být povolena, jinak bude
zobrazena chybová hláška.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Sessionless
(povinné pro mobilní
bránu)
Tento parametr je povinný na mobilní bráně a má vždy
hodnotu 1.
Tímto parametrem dává obchodník najevo, že funkčnost jeho
implementace není ovlivněna zavřením prohlížeče v mobilním
zařízení.
Na desktopové webové bráně se tento parametr nevyžaduje.
Podrobnosti jsou uvedeny v kapitole 3.2.
Nebude-li požadavek úplný, nebo nebude validní, platební brána upozorní klienta (kupujícího) a
transakci v tomto případě neuskuteční.
Pokud je transakce uskutečněna, je klient přesměrován na URL adresu definovanou v parametru
backURL.
Důležité upozornění: Zpětné volání URL obchodníka (backURL) má pouze informativní
charakter. Vzhledem k „bezestavovosti“ HTTP protokolu může volání přes prohlížeč klienta
z různých důvodů selhat, resp. skutečný stav transakce je nutné dodatečně ověřit pomocí
webové služby VerifyTransactionIsPaid (viz kapitola 4.3.1.) – u e-shopu , nebo pomocí
uživatelského rozhraní PaySec, v sekci přehledy - u darovací platby.
Obchodník (e-shop) nesmí expedovat zboží nebo službu pouze na základě
přesměrování uživatele zpět na BackURL.
Obchodník (e-shop) si musí „převzít“ platbu do svého systému voláním
VerifyTransactionIsPaid nebo výjimečně voláním GetStatement.
3.2. Vstupní parametry pro Mobilní platební bránu
Vstupní parametry pro mobilní verzi jsou stejné jako u klasické platební brány, obsahují však
jeden parametr navíc.
Parametr
Popis
Sessionless
(povinné pro mobilní
bránu)
Tento parametr je povinný na mobilní bráně a má vždy
hodnotu 1.
Tímto parametrem dává obchodník najevo, že funkčnost jeho
implementace není ovlivněna zavřením prohlížeče v mobilním
zařízení (viz následující text).
Na desktopové webové bráně se tento parametr nevyžaduje.
U nových platebních metod, kdy placení probíhá pomocí aplikace v mobilním telefonu, může dojít
během platby k uzavření webového prohlížeče. V závislosti na tom, jak používáte session
management ve Vaší implementaci e-shopu, může proto dojít ke zrušení session.
Pokud používáte session s uložením údajů (např. čísla objednávky) do cookie s neuvedenou
dobou platnosti, při přesměrování na BackUrl nebo CancelUrl po provedení platby bude tato
cookie pravděpodobně vymazána.
Je možné tento problém řešit změnou nastavení session managementu ve Vámi použité
technologii (uložit např. session id do parametru), nebo si posílat číslo objednávky v parametrech
BackUrl a CancelUrl, aby při přesměrování zpět na Váš e-shop bylo zřejmé, ke které objednávce
request patří. Je to možné těmito způsoby:

Poslat si v BackUrl a CancelUrl přímo číslo objednávky:
Příklad:
BackUrl http://eshop.cz/objednavka.php?ft_id={0}&id_objednavky=123
CancelUrl http://eshop.cz/zruseno.php?id_objednavky=123

V BackUrl a CancelUrl poslat parametr {1}. PaySec doplní při přesměrování zpět do
eshopu hodnotu merchantOrderId.
Příklad:
BackUrl http://eshop.cz/objednavka.php?ft_id={0}&id_objednavky={1}
CancelUrl http://eshop.cz/zruseno.php?ft_id={0}&id_objednavky={1}
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Nadále bude fungovat nahrazení hodnoty {0} za číslo finanční transakce.
3.3. Jakou platební metodu zvolit
Majitel Konta pro obchodníky může využít dvou metod pro komunikaci. Oba způsoby vedou
k vytvoření platby, kterou může následně klient autorizovat. S výběrem vhodné metody pro
napojení vašich stránek/obchodu/portálu vám pomůže následující tabulka:
Metoda
Pro koho
Co je potřeba
Internetový
obchod
Obchodník expedující zboží nebo službu, kde
je nutné provádět automatické ověřování
transakcí bez zásahu obsluhy.
Tento obchodník má typicky vlastní obchod/portál,
který může upravovat, event. využívá hotového
řešení třetí strany, které platby pomocí PaySec
podporuje.
HTML, programování
ve skriptovacím nebo
programovacím jazyce
jako např. PHP,
ASP.NET, Java, apod.
Parametr MerchantOrderId musí být vyplněn a musí
být unikátní.
V případě
implementace od třetí
strany nebude
programování nutné.
V tomto případě už nepoužívejte parametr
OrderId.
Po uskutečnění transakce musí být platba
ověřena pomocí webové služby
VerifyTransactionIsPaid (viz kapitola 4.3.1.)
Obchodník musí mít zřízené Konto pro obchodníky a
zákazníci mohou využít všechny platební metody.
POZOR: pokud není on-line platba ve prospěch
e-shopu úspěšně ověřena (s návratovým
kódem 0) do 20 minut od jejího provedení, je
platba automaticky stornována a plná částka
je vrácena zpět zákazníkovi.
Darovací
platební
tlačítko
Příjem darů. Není určeno pro e-shopy expedující
zboží nebo služby. Jedná se např. o stránky
pro dobrovolné dary, sponzoring,charitativní
organizace, sbírky nebo v případně osobního Konta
PaySec o osobní stránky apod.
Místo parametru MerchantOrderId je použit
parametr OrderId, který nemusí být unikátní.
V tomto případě už nepoužívejte parametr
MechantOrderId.
V případě Konta pro obchodníky přijímá obchodník
všechny metody platby.
U osobního Konta PaySec je možné přijímat platby
pouze z jiných Kont PaySec.
© 2007-2014 Československá obchodní banka, a.s.
Základy HTML.
Příručka pro použití Platební brány PaySec verze 1.20
3.4. Platba z Internetového obchodu
Internetový obchod posílá na v HTML formuláři následující údaje na Platební bránu PaySec.
Důležité je použít pro číslo objednávky parametr MerchantOrderId. Tato hodnota musí být
unikátní. Pomocí této hodnoty následně e-shop ověřuje stav platby. Teprve po potvrzení
zaplacení pomocí ověřovací metody obchodník expeduje zboží nebo službu. Viz kapitola MAPI.
Na desktopové webové verzi platební brány se zákazníkovi zobrazí rozcestník
následujících platebních metod, avšak v závislosti na tom, jestli má obchodník dané
metody povolené, zda výše částky odpovídá limitům platebních metod a není nižší než
poplatek za platbu: ČSOB, Poštovní spořitelny / ERA, elektronická peněženka PaySec,
platební karta, MasterCard Mobile a běžný bankovní převod.
Na mobilní webové verzi platební brány volané z počítače nebo mobilního zařízení
s výjimkou mobilního zařízení s Android nebo Apple iOS se zákazníkovi pouze platba z
elektronické peněženky PaySec a platební kartou, opět v závislosti na tom, jestli má
obchodník obě metody povolené, zda výše částky odpovídá limitům platebních metod a
není nižší než poplatek za platbu. Při volání brány z mobilního zařízení s Android nebo
Apple iOS se zobrazí i další „smart“ platební metody ČSOB, Era a MasterCard Mobile.
3.4.1.
Příklad formuláře e-shopu – klasická verze (test)
<html>
<head>
<title>Zaplacení pomocí PaySec</title>
</head>
<body>
<form action="https://testgateway.paysec.cz/GateWay.aspx" method="post">
<input type="submit" value="Zaplatit pomocí PaySec" />
<input type="hidden" name="MicroaccountNumber" value="1100000" />
<input type="hidden" name="Amount" value="250.50" />
<input type="hidden" name="MerchantOrderId" value="123456" />
<input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" />
<input type="hidden" name="BackURL"
value="http://www.shop.cz/platba.php?TId={0}" />
<input type="hidden" name="CancelURL"
value="http://www.shop.cz/platbaodmitnuta.php" />
</form>
</body>
</html>
3.4.2.
Příklad formuláře e-shopu – klasická verze (produkce)
<html>
<head>
<title>Zaplacení pomocí PaySec</title>
</head>
<body>
<form action="https://gateway.paysec.cz/GateWay.aspx" method="post">
<input type="submit" value="Zaplatit pomocí PaySec" />
<input type="hidden" name="MicroaccountNumber" value="1100000" />
<input type="hidden" name="Amount" value="250.50" />
<input type="hidden" name="MerchantOrderId" value="123456" />
<input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" />
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
<input type="hidden" name="BackURL"
value="http://www.shop.cz/platba.php?TId={0}" />
<input type="hidden" name="CancelURL"
value="http://www.shop.cz/platbaodmitnuta.php" />
</form>
</body>
</html>
3.4.3.
Příklad formuláře e-shopu – mobilní verze (test)
<html>
<head>
<title>Zaplacení pomocí PaySec</title>
</head>
<body>
<form action="https://testgateway.paysec.cz/MobileGateWay.aspx" method="post">
<input type="submit" value="Zaplatit pomocí PaySec" />
<input type="hidden" name="MicroaccountNumber" value="1100000" />
<input type="hidden" name="Amount" value="250.50" />
<input type="hidden" name="MerchantOrderId" value="123456" />
<input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" />
<input type="hidden" name="BackURL"
value="http://www.shop.cz/platba.php?TId={0}" />
<input type="hidden" name="CancelURL"
value="http://www.shop.cz/platbaodmitnuta.php" />
<input type="hidden" name="Sessionless" value="1" />
</form>
</body>
</html>
3.4.4.
Příklad formuláře e-shopu – mobilní verze (produkce)
<html>
<head>
<title>Zaplacení pomocí PaySec</title>
</head>
<body>
<form action="https://gateway.paysec.cz/MobileGateWay.aspx" method="post">
<input type="submit" value="Zaplatit pomocí PaySec" />
<input type="hidden" name="MicroaccountNumber" value="1100000" />
<input type="hidden" name="Amount" value="250.50" />
<input type="hidden" name="MerchantOrderId" value="123456" />
<input type="hidden" name="MessageForTarget" value="Jaromír Nohavica - MP3" />
<input type="hidden" name="BackURL"
value="http://www.shop.cz/platba.php?TId={0}" />
<input type="hidden" name="CancelURL"
value="http://www.shop.cz/platbaodmitnuta.php" />
<input type="hidden" name="Sessionless" value="1" />
</form>
</body>
</html>
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
4. Rozhraní Merchant API (MAPI)
V rámci služeb rozhraní pro obchodníky existuje webová služba MAPI, která umožňuje
obchodníkům ověřit, zda transakce zadaná na Platební bránu PaySec z elektronického obchodu
byla či nebyla zaplacena. Služba odpovídá standardu WebServices 1.1 (WS-I Basic Profile 1.1) a
je možné jí bez problémů „volat“ z různých platforem.
Popis rozhraní služby ve standardu WSDL je dostupný na těchto adresách:
Produkční verze

https://mapi.paysec.cz/mapi.svc?wsdl (WCF Web Service)

https://mapi.paysec.cz/mapi.asmx?wsdl (ASP.NET Web Service)
Testovací verze

https://testmapi.paysec.cz/mapi.svc?wsdl (WCF Web Service)

https://testmapi.paysec.cz/mapi.asmx?wsdl (ASP.NET Web Service)
Volání MAPI je na těchto adresách
Produkční verze

https://mapi.paysec.cz/mapi.svc (WCF Web Service)

https://mapi.paysec.cz/mapi.asmx (ASP.NET Web Service)
Testovací verze

https://testmapi.paysec.cz/mapi.svc (WCF Web Service)

https://testmapi.paysec.cz/mapi.asmx (ASP.NET Web Service)
Pro většinu e-shopů je vhodnější implementovat verzi ASMX.
V případě, že je e-shop v PHP, je z důvodu kompatibility PHP vhodnější použít verzi
SVC.
4.1. Testovací a produkční prostředí
Obě prostředí mají z pohledu MAPI identická rozhraní.
V testovacím prostředí má obchodník k dispozici testovací obchodnické PaySec Konto a
testovací osobní PaySec Konto. Osobní Konto je přednabité na 50 000 Kč.
Při platbě platební metodou PaySec se přihlásí do osobního Konta a z něj pošle na obchodnické
Konto částku transakce. Osobní Konto se automaticky pravidelně dobíjí při poklesu zůstatku pod
určitou částku. Z obchodnického Konta je možné také realizovat Vratky, kdy se prostředky vrací
na zdrojové osobní Konto.
Při platbě platební metodou z běžného účtu u ČSOB a Poštovní spořitelny / ERA, platební kartou
a MasterCard Mobile je simulováno rozhraní internetového bankovnictví, kartová platební brána a
platba přes smart aplikaci MasterCard Mobile. Z těchto simulátorů je platba ihned převedena na
PaySec Konto obchodníka. Zde je neomezený limit na platbu. I zde může obchodník provádět
vratku na zdrojový běžný účet nebo platební kartu. Pro simulátory není nutné používat žádné
přihlašovací údaje ani testovací platební kartu.
Obchodník – implementátor má možnost se přihlásit do testovacího Konta PaySec, kde
si může ověřit stavy jednotlivých transakcí a to, jak jsou transakce obchodníkem
ověřovány.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
V produkčním prostředí je limit na transakci z osobního PaySec Konta daný vždy aktuálním
sazebníkem PaySec (http://www.paysec.cz/CmsPage.aspx?Id=feeList). V době vydání
této verze příručky je maximální částka transakce přes platební bránu z osobního Konta PaySec
55 000 Kč.
Při platbě z běžného účtu je limit na transakci nižší z následujících dvou limitů. Na straně
obchodníka je to 1 mil. Kč. Na straně uživatele internetového bankovnictví je to jeho individuální
limit, který může být stejný nebo i nižší například ve stovkách tisíc Kč.
Při platbě platební kartou je držitel karty omezen limitem na platební kartě pro určité období.
Limit pro platby kartou na Internetu může být oddělen od limitu pro platbu kartou v kamenných
obchodech.
Cílem testovací verze je umožnit obchodníkovi odladit komunikaci mezi
obchodem/portálem a službami PaySec. Speciálně ověřit to, jak jsou jednotlivé
transakce ověřovány pomocí MAPI metody VerifyTransactionIsPaid. Zde je nutné, aby
byly transakce z PaySec Konta na platební bráně označeny tmavě zelenou barvou.
Přehled transakcí na testovací platební bráně najdete po přihlášení na
https://testgateway.paysec.cz/Login.aspx v sekci Platební brána – Transakce.
Pro přístup do produkčního prostředí použijte uživatelské jméno a heslo pro MAPI, které si
můžete nastavit po přihlášení ke svému Kontu v záložce Osobní nastavení. Nemáte-li nastavené
heslo pro MAPI, požádejte majitele PaySec Konta o jeho nastavení.
Pro přístup do testovací verze prosím kontaktujte pracovníky týmu PaySec na e-mailové adrese
[email protected]
4.2. Zabezpečení komunikace
Komunikace s webovou službou MAPI je zabezpečena pomocí protokolu HTTPS.
Testovací i produkční používá certifikáty vydané certifikační autoritou GlobalSign.
Ujistěte se, že prohlížeč, který používáte, má uvedenou tuto certifikační autoritu jako
důvěryhodnou certifikační autoritu. Blíže kapitola 8.1.
4.3. Metody
Webová služba MAPI obsahuje implementaci těchto metod:

VerifyTransactionIsPaid – NEZBYTNĚ NUTNÉ pro ověření zaplacení nákupu
v internetovém obchodě (e-shopu) – bez ověření transakce je platba po 20
minutách stornována a vrácena zpět zákazníkovi

GetStatement – získání transakční historie (zaúčtovaných položek) k danému kontu –
Vhodné pro větší e-shopy pro provádění například denní rekonciliace

GetStatementWithBalance – jako GetStatement, navíc obsahuje informace
o zůstatcích pro dané období

PaymentReturn – vrácení peněz (vratka) z transakce uskutečněné pomocí platební
brány. Vhodné pro možnost automatizovaného vracení transakcí systémem e-shopu.

RepeatPayment – umožní realizovat opakovanou platbu ze šablony (nyní pouze platby
platební kartou; šablonou se rozumí předchozí platba stejnou kartou, která je explicitně
označena jako šablona)

depositBlockedTransaction – umožní zaúčtování předautorizované transakce, tj.
převod částky na konto obchodníka

cancelBlockedTransaction – umožní zrušit již předautorizovanou transakci
Vstupní, resp. výstupní parametry volání metod viz popis dále.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
4.3.1.
VerifyTransactionIsPaid
Metoda VerifyTransactionIsPaid se používá pro ověření zaplacení transakce při platbě
v internetovém obchodě. Implementace této služby je nezbytně nutná pro všechny
obchodníky - e-shopy expedující zboží nebo službu pro automatické ověření transakce
systémem e-shopu. Po úspěšném ověření platby je požadováno na e-shopu automatické
označení objednávky za zaplacenou.
Ověření transakce by mělo být pro online platební metody provedeno ihned po zavolání
návratového URL e-shopu a to tak rychle, aby e-shop mohl na stránce, kterou klientovi
zobrazí po jeho návratu z platební brány PaySec mohl rovnou zobrazit odpověď, kterou
získal pomocí tohoto ověření transakce. Typicky během maximálně jednotek sekund.
U transakcí, kde se zákazník dlouho nevrací zpět na e-shop a pro offline platební
metody je nutné implementovat „periodické ověřování čekajících transakcí“. Detailní
postup je popsán v kapitole 2.6.5.
POZOR: pokud není on-line platba ve prospěch e-shopu úspěšně ověřena
(s návratovým kódem 0) do 20 minut od jejího provedení, je platba automaticky
stornována a plná částka je vrácena zpět zákazníkovi.
Služba vyžaduje čtyři vstupní parametry:
Parametr
Typ
Popis
userName
string
Uživatelské jméno obchodníka, kterým se hlásí
na portál PaySec.
Password
string
Heslo pro MAPI. Není-li nastaveno heslo pro MAPI,
použijte heslo spojené s uživatelským jménem
obchodníka.
merchantOrderId
string
Unikátní identifikátor transakce obchodníka. Tento
identifikátor musí být v unikátní v rámci transakcí
daného obchodníka. Pomocí čísla objednávky je
následně možné zjistit stav transakce.
Může obsahovat všechny znaky ASCII s výjimkou
znaků > <.
Amount
decimal
Částka v CZK včetně desetinné části.
Metoda ověří, zda existuje transakce se zadaným číslem objednávky, zda cílový účet patří
zadanému obchodníkovi, zda zní na správnou částku a zda se váže k uvedené objednávce.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Návratová hodnota:
Metoda vrací číselný identifikátor (int) v závislosti na stavu transakce:
Popis
Text pro zákazníka4
Akce
0
Transakce byla úspěšně
zaúčtována.
Platba prostřednictvím
systému PaySec proběhla
úspěšně
Vydat
zboží/službu
zákazníkovi.
1
Transakce byla zamítnuta.
Platbu se nepodařilo
zrealizovat.
Viz kapitola
2.6.2
2
Přihlašovací jméno či heslo
není platné nebo přihlašovací
jméno neexistuje.
Stav platby se nepodařilo
ověřit.
Pracujeme na nápravě.
Viz kapitola
2.6.3
3
Konto je blokováno nebo
zrušeno.
Stav platby se nepodařilo
ověřit. Pracujeme
na nápravě.
Viz kapitola
2.6.3
4
Transakce s daným číslem
objednávky
(MerchantOrderId)
neexistuje.
Pro online metody:
Platba zatím nebyla
přijata. Stav bude ověřen
později.
Pro offline metody:
Čeká se na přijetí platby.
Pro online
metody:
Viz kapitola
2.6.4
5
Zadaná částka neodpovídá
transakci.
Platbu se nepodařilo
zrealizovat.
Viz kapitola
2.6.3
6
Systémová chyba
(kontaktujte podporu).
Stav platby se nepodařilo
ověřit. Pracujeme
na nápravě.
Viz kapitola
2.6.3
7
Nevyplněný parametr
MerchantOrderId
8
Nedostatečná oprávnění
(zadané přihlašovací údaje
nepatří mikroúčtu typu
obchodník, ale osobnímu
Kontu)
Stav platby se nepodařilo
ověřit. Pracujeme
na nápravě.
9
Transakce typu
Předautorizovaná platba byla
zrušena.
Předautorizace částky byla
zrušena.
10
Transakce typu
Předautorizovaná platba byla
úspěšně předautorizována.
Předautorizace částky byla
provedena.
11
Nezaplacená offline platba
(čeká se na přijetí platby)
Čeká se na přijetí platby.
Webová služba je nedostupná
Stav platby se nepodařilo
ověřit. Pracujeme
na nápravě.
Hodnota
-
4
Obchodník je povinen zobrazit text v přesném znění
© 2007-2014 Československá obchodní banka, a.s.
Viz kapitola
2.6.3
Příručka pro použití Platební brány PaySec verze 1.20
4.3.2.
GetStatement a GetStatementWithBalance
Metoda slouží k získání výpisu pohybů na kontě.
Implementace této metody je vhodná pro větší e-shopy k automatické rekonciliaci
všech pohybů na PaySec Kontě pro obchodníky a to i takových, které nebyly provedeny
přes platební bránu PaySec.
Vyžaduje čtyři vstupní parametry:
Parametr
Typ
Popis
userName
string
Uživatelské jméno obchodníka, kterým se hlásí na portál
PaySec.
password
string
Heslo pro MAPI. Není-li nastaveno heslo pro MAPI, použijte
heslo spojené s uživatelským jménem obchodníka.
dateFrom
date
Datum od, od kterého se má výpis generovat. Pokud je
datum zadán včetně času, je čas ignorován.
Datum je ve formátu YYYY-MM-DD, kde:
YYYY je rok (2008 až 2099)
MM je měsíc (01 až 12)
DD je den (01 až max. 31 – podle měsíce)
Příklad: 2008-06-16
dateTo
date
Datum, do kterého se má výpis generovat (včetně).
Návratové hodnoty:
Metoda vrací dva výstupy:
1) Číselný identifikátor (int) v závislosti na stavu operace:
Hodnota
Popis
0
OK
2
Chybné uživatelské jméno nebo heslo.
3
Konto neexistuje nebo není aktivní .
6
Systémová chyba (kontaktujte podporu).
7
Chyba vstupních parametrů.
(nezadaný parametr userName nebo
password)
-
Webová služba je nedostupná.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
2) Seznam řádků výpisu (v případě, že operace proběhla v pořádku (OK)).
POZOR, formát návratových informací je jiný ve verzi ASMX a SVC.
Každý řádek obsahuje tyto údaje:
Parametr
Typ
Popis
Id
long
Identifikátor transakce
Date
datetime
Datum a čas zaúčtování transakce
TransactionType
string
Název typu transakce.
AccountNumber
string
Číslo konta. Pro nabíjení a vybíjení je
prázdné.
AccountName
string
Jméno nebo číslo protistrany - konta.
Pro nabíjení kartou je prázdné.
Value
decimal
Částka transakce bez poplatků.
TotalValue
decimal
Částka transakce včetně poplatků.
Jedná se o částku, o kterou se změnil
zůstatek Konta.
FeeValue
decimal
Částka poplatků.
ClientIdentifier
string
Klientský identifikátor transakce (např.
číslo objednávky nebo variabilní
symbol)
Description
string
Popis vztahující se k transakci.
DescriptionForTarget
string
V případě zaslání peněz obsahuje popis
určený pro cílové Konto.
IsStorno
bool
Indikuje, zda se jedná o storno
transakci.
OriginalFinancialTransactionId
long
V případě storna obsahuje id
stornované transakce, které původní
transakci přidělil systém PaySec
Note
string
Popis objednávky.
NoteDetail
string
U plateb provedených přes platební
bránu obsahuje příznak GW značící, že
platba proběhla přes platební bránu.
3) Metoda GetStatementWithBalance obsahuje navíc informace o zůstatcích na
kontě a o výši obratů
Parametr
Typ
Popis
BalanceStart
decimal
Zůstatek na mikroúčtu na začátku
výpisu
BalanceEnd
decimal
Zůstatek na mikroúčtu ke konci výpisu
Expenses
decimal
Suma všech výdajů za dané období
Fees
decimal
Suma všech poplatků za dané období
Income
decimal
Suma všech příjmů za dané období
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Verze ASMX:
Příklad položky příchozí platby při volání GetStatement verze ASMX u platby z běžného účtu u ČSOB a
Poštovní spořitelny / ERA
<GetStatementItemResponse>
<Id>101378975</Id>
<Date>2011-05-05T11:48:15.72</Date>
<TransactionType>ChargeFromBankAccount</TransactionType>
<AccountNumber>1144</AccountNumber>
<AccountName>123/0300</AccountName>
<Value>250.0000</Value>
<TotalValue>247.0000</TotalValue>
<FeeValue>-3.0000</FeeValue>
<ClientIdentifier>3250659</ClientIdentifier>
<Description>Test platba</Description>
<DescriptionForTarget/>
<IsStorno>false</IsStorno>
<OriginalFinancialTransactionId xsi:nil="true"/>
<TransactionTypeName>Převod z běžného účtu</TransactionTypeName>
<Note/>
<NoteDetail>GW</NoteDetail>
</GetStatementItemResponse>
Příklad položky příchozí platby volání GetStatement verze ASMX u platby jiného PaySec Konta
<GetStatementItemResponse>
<Id>101419870</Id>
<Date>2010-11-27T04:25:43.713</Date>
<TransactionType>Transfer</TransactionType>
<AccountNumber>10101010</AccountNumber>
<AccountName>TestKonto</AccountName>
<Value>5.0000</Value>
<TotalValue>5.0000</TotalValue>
<FeeValue>0</FeeValue>
<ClientIdentifier>7066939</ClientIdentifier>
<Description>Test produkce - prijemce</Description>
<DescriptionForTarget/>
<IsStorno>false</IsStorno>
<OriginalFinancialTransactionId xsi:nil="true"/>
<TransactionTypeName>Platba z Konta na Konto</TransactionTypeName>
<Note/>
<NoteDetail>GW</NoteDetail>
</GetStatementItemResponse>
Příklad položky příchozí platby volání GetStatement verze ASMX u platby platební kartou
<GetStatementItemResponse>
<Id>100582379</Id>
<Date>2012-01-30T18:51:36.53</Date>
<TransactionType>CardPayment</TransactionType>
<AccountNumber>1122</AccountNumber>
<AccountName>1122</AccountName>
<Value>301.0000</Value>
<TotalValue>293.9800</TotalValue>
<FeeValue>-7.0200</FeeValue>
<ClientIdentifier>301A</ClientIdentifier>
<DescriptionForTarget/>
<IsStorno>false</IsStorno>
<OriginalFinancialTransactionId xsi:nil="true"/>
<TransactionTypeName>Platba platební kartou</TransactionTypeName>
<Note/>
</GetStatementItemResponse>
Příklad položky příchozí platby volání GetStatement verze ASMX u platby MasterCard Mobile
<GetStatementItemResponse>
<Id>100588106</Id>
<Date>2013-02-01T11:28:38.61</Date>
<TransactionType>PaymentFromMCM</TransactionType>
<AccountNumber>1122</AccountNumber>
<AccountName>RMAtest01 (2203883)</AccountName>
<Value>10.0000</Value>
<TotalValue>10.0000</TotalValue>
<FeeValue>0</FeeValue>
<ClientIdentifier>827833</ClientIdentifier>
<Description>12345</Description>
<DescriptionForTarget/>
<IsStorno>false</IsStorno>
<OriginalFinancialTransactionId xsi:nil="true"/>
<TransactionTypeName>Platba z MasterCard Mobile</TransactionTypeName>
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
<Note>paid by android application</Note>
<NoteDetail/>
</GetStatementItemResponse>
Verze SVC:
Příklad položky příchozí platby volání GetStatement verze SVC u platby běžným bankovním převodem
<StatementItem>
<accountName>1100</accountName>
<accountNumber>1100</accountNumber>
<clientIdentifier>1748417</clientIdentifier>
<date>2012-07-20T12:07:23.817</date>
<description>Test produkce - prijemce</description>
<descriptionForTarget/>
<feeValue>-1.1000</feeValue>
<id>102697063</id>
<isStorno>false</isStorno>
<note/>
<noteDetail>GW</noteDetail>
<originalFinancialTransactionId i:nil="true"/>
<totalValue>8.9000</totalValue>
<transactionType>Offline</transactionType>
<transactionTypeName>Platba offline převodem z BÚ</transactionTypeName>
<value>10.0000</value>
</StatementItem>
Verze SVC – kompletní výpis XML volání GetStament
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetStatementResult xmlns="http://schemas.mapi.paysec.cz/2008/02">0</GetStatementResult>
<ArrayOfStatementItem xmlns="http://schemas.mapi.paysec.cz/2008/02/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<StatementItem>
<accountName>RMAtest01 (2203883)</accountName>
<accountNumber>1122</accountNumber>
<clientIdentifier>5099258</clientIdentifier>
<date>2013-02-01T10:28:38.64</date>
<description>Zprava pro prijemce</description>
<descriptionForTarget/>
<feeValue>0</feeValue>
<id>100588102</id>
<isStorno>false</isStorno>
<note/>
<noteDetail/>
<originalFinancialTransactionId i:nil="true"/>
<totalValue>54.4500</totalValue>
<transactionType>PaymentFromMCM</transactionType>
<transactionTypeName>Platba z MasterCard Mobile</transactionTypeName>
<value>54.4500</value>
</StatementItem>
<StatementItem>
<accountName>RMAtest01 (2203883)</accountName>
<accountNumber>1122</accountNumber>
<clientIdentifier>2241672</clientIdentifier>
<date>2013-02-01T10:10:01.687</date>
<description>Zprava pro prijemce</description>
<descriptionForTarget/>
<feeValue>-2.0700</feeValue>
<id>100588101</id>
<isStorno>false</isStorno>
<note/>
<noteDetail/>
<originalFinancialTransactionId i:nil="true"/>
<totalValue>51.2300</totalValue>
<transactionType>CardPayment</transactionType>
<transactionTypeName>Platba platební kartou</transactionTypeName>
<value>53.3000</value>
</StatementItem>
<StatementItem>
<accountName>RMAtest01 (2203883)</accountName>
<accountNumber>1144</accountNumber>
<clientIdentifier>3516849</clientIdentifier>
<date>2013-02-01T10:08:57.233</date>
<description>Zprava pro prijemce</description>
<descriptionForTarget/>
<feeValue>0</feeValue>
<id>100588100</id>
<isStorno>false</isStorno>
<note/>
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
<noteDetail/>
<originalFinancialTransactionId i:nil="true"/>
<totalValue>52.2000</totalValue>
<transactionType>ChargeFromBankAccount</transactionType>
<transactionTypeName>Převod z běžného účtu</transactionTypeName>
<value>52.2000</value>
</StatementItem>
<StatementItem>
<accountName>RMAtest01 (2203883)</accountName>
<accountNumber>2203564</accountNumber>
<clientIdentifier>2441296</clientIdentifier>
<date>2013-02-01T10:05:43.877</date>
<description>Zprava pro prijemce</description>
<descriptionForTarget/>
<feeValue>-2.0000</feeValue>
<id>100588098</id>
<isStorno>false</isStorno>
<note/>
<noteDetail/>
<originalFinancialTransactionId i:nil="true"/>
<totalValue>48.0000</totalValue>
<transactionType>Transfer</transactionType>
<transactionTypeName>Platba z Konta na Konto</transactionTypeName>
<value>50.0000</value>
</StatementItem>
</ArrayOfStatementItem>
</s:Body>
</s:Envelope>
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
4.3.3.
PaymentReturn
Metoda slouží k vrácení peněz (vratka) z transakce uskutečněné pomocí platební brány. Vracení
probíhá na základě unikátního identifikátoru původní platby (MerchantOrderID) a je možné vrátit
libovolnou částku maximálně do výše původní platby.
Lze vracet ze všech druhů plateb. Jak platby přijaté transakcí typu „Platba z Konta na
Konto“ , tak peníze přijaté transakcí typu „Platba z běžného účtu“ tak platby přijaté
transakcí „Platba platební kartou“.
Metoda vyžaduje šest vstupních parametrů:
Parametr
Typ
Popis
userName
string
Uživatelské jméno obchodníka, kterým se hlásí
na portál PaySec.
password
string
Heslo pro MAPI. Není-li nastaveno heslo pro MAPI,
použijte heslo spojené s uživatelským jménem
obchodníka.
merchantOrderId
string
Unikátní identifikátor původní transakce
obchodníka.
Může obsahovat všechny znaky ASCII s výjimkou
znaků > <.
amount
decimal
Částka včetně desetinné části. Nesmí přesáhnout
výši původní transakci.
descriptionForSource
(nepovinné)
string
Zpráva pro odesílatele platby (obchodníka), která
by měla obsahovat popis původní objednávky a
charakterizovat důvod vracení peněz.
U platby bude uvedena jako Zpráva pro příjemce.
V GetStatement je pak uveden v tagu
<Description>
descriptionForTarget
(nepovinné)
string
Zpráva pro příjemce platby (klienta), která by
měla obsahovat popis původní objednávky a
charakterizovat důvod vracení peněz.
U platby bude uvedena jako Zpráva pro příjemce.
V GetStatement je pak uveden v tagu
<DescriptionForTarget>
Návratové hodnoty:
Metoda vrací strukturu PaymentReturnResult, ve které je textový kód resultCode. Ten nabývá
v závislosti na stavu transakce hodnot v následující tabulce.
POZOR, návratové hodnoty se liší pro verzi ASMX (text před závorkou) a SVC (číslo v závorce).
Hodnota
Popis
OK (0)
OK – vracení proběhlo úspěšně.
BadCredentials (2)
Chybné uživatelské jméno nebo heslo.
BadCredentials (2)
Konto neexistuje nebo není aktivní.
BadOrderIdOrNonexistingFinTran
(4)
SystemError (6)
BadParameters (7)
-
Transakce s daným číslem objednávky
(MerchantOrderId) neexistuje.
Chyba vstupních parametrů.
Není zadáno číslo objednávky
(MerchantOrderId) nebo není zadáno
userName, password.
Webová služba je nedostupná.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Poznámka: výše uvedené platí pouze v případě volání metody PaymentReturn přes
https://mapi.paysec.cz/mapi.asmx, v případě volání přes
https://mapi.paysec.cz/mapi.svc jsou jako návratové hodnoty vraceny čísla uvedeny
v závorce.
Ukázka volání metody PaymentReturn z PHP
Předání parametrů této metodě se liší od ostatních metod, je nutné ji proto volat jinak,
než je uvedeno v kapitole 8.2.3.
$userName = 'obchodnik01';
$password = 'heslo01';
$merchantOrderid = '1345653056';
$amount = 28;
$descriptionForSource = 'Popis pro obchodnika';
$descriptionForTarget = 'Popis pro klienta';
$paysecMapi = new SoapClient("https://testmapi.paysec.cz/mapi.svc?wsdl");
$param_array = array(
'requestData' => array(
'Header' => array(
'LoginInfo' => array(
'password' => $password,
'userName' => $userName
)
),
'amount' => $amount,
'merchantOrderid' => $merchantOrderid,
'descriptionForSource' => $descriptionForSource,
'descriptionForTarget' => $descriptionForTarget
)
);
$resultObject = $paysecMapi->PaymentReturn($param_array);
echo $resultObject->PaymentReturnResult->resultCode;
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
4.3.4.
RepeatPayment
Metoda slouží k realizaci opakované platby. Principem opakované platby je to, že pouze první
platba je autorizována konečným zákazníkem, tato autorizace je poté platná i pro následné
opakované platby, platba je poté inkasována obchodníkem. Pro použití této funkcionality je
potřeba splnit podmínky provozovatele PaySec a podepsat dodatek ke smlouvě mezi PaySec a
obchodníkem. Funkcionalita opakované platby je v aktuální verzi určena pouze pro platby
platební kartou. Opakovaná platba funguje následovně:
1. Během provádění standardní platby přes platební bránu je tato platba obchodníkem
označena jako opakovaná, viz parametr RepeatTemplate, kapitola 3.1
2. Po zaúčtování transakce je tato v systému označena jako šablona pro opakovanou platbu
3. Opakovaná platba se provádí MAPI voláním, jedním z parametrů je identifikace prvotní
platby, která byla označena jako šablona.
4. Po provedení metody RepeatPayment je nutné volat metodu VerifyTransactionIsPaid
s novým merchantOrderId pro ověření zaúčtování této opakované platby. Toto volání se
řídí popisem uvedeným v kapitole 2.6.5.
Metoda vyžaduje tyto vstupní parametry:
Parametr
Typ
Popis
userName
string
Uživatelské jméno obchodníka, kterým se hlásí
na portál PaySec.
password
string
Heslo pro MAPI. Heslo spojené s uživatelským
jménem obchodníka nelze použít.
oldMerchantOrderId
string
Unikátní identifikátor původní transakce
obchodníka, která byla označena jako šablona
opakované platby.
Může obsahovat všechny znaky ASCII s výjimkou
znaků > <.
merchantOrderId
string
Nový jedinečný identifikátor transakce v rámci
transakcí na mikroúčtu obchodníka.
merOrderNumber
(nepovinné)
string
Číslo objednávky obchodníka, nemusí být
jedinečné
amount
decimal
Částka platby včetně desetinné části.
Návratové hodnoty:
Metoda vrací číselný kód v závislosti na stavu transakce:
Hodnota
Popis
0
OK – opakovaná platba byla úspěšně autorizována.
1
Opakovanou platbu se nepodařilo zrealizovat.
2
Chybné uživatelské jméno nebo heslo, nebo konto neexistuje.
3
Konto není aktivní.
4
5
Transakce s daným číslem objednávky (MerchantOrderId) neexistuje.
Zadaná částka je menší nez poplatek za transakci.
6
Systémová chyba (kontaktujte podporu).
7
Chyba



8
Obchodnické konto nemá povolenu opakovanou platbu.
12
-
vstupních parametrů.
nezadaný parametr userName, password nebo merchantOrderId
parametr merOrderNumber je zadán, ale není celé číslo
merchantOrderId je delší než 30 znaků
Číslo objednávky (MerchantOrderId) bylo již použito pro platbu pro toto
obchodnické konto.
Webová služba je nedostupná.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
4.3.5.
depositBlockedTransaction
Metoda slouží k realizaci zaúčtování předautorizované (blokované) platby na účet obchodníka.
Pro každou předautorizovanou platbu lze tuto metodu volat pouze jednou, lze deponovat
libovolnou částku až do výše původní předautorizace. Pokud je deponovaná částka nižší než
předautorizace, je rozdíl uvolněn zpět na účet zákazníka.
Metoda vyžaduje tyto vstupní parametry:
Parametr
Typ
Popis
userName
string
Uživatelské jméno obchodníka, kterým se hlásí
na portál PaySec.
password
string
Heslo pro MAPI. Heslo spojené s uživatelským
jménem obchodníka nelze použít.
merchantOrderId
string
Unikátní identifikátor předautorizované transakce.
amount
decimal
Částka včetně desetinné části, která má být
deponována. Musí být rovna nebo menší než
původní předautorizovaná částka.
Návratové hodnoty:
Metoda vrací kód v závislosti na stavu transakce:
Hodnota
Popis
0
Operace proběhla v pořádku.
1
Finanční transakci pro dané merchantOrderId se nepodařilo
zaúčtovat, protože platnost předautorizace vypršela.
2
Chybné uživatelské jméno nebo heslo.
3
Konto není aktivní.
4
Finanční transakce pro dané merchantOrderId neexistuje
nebo není typu Platba platební kartou.
5
Chybná částka – chybný číselný formát, je záporná nebo
nulová, nebo je větší než částka původní transakce.
6
Systémová chyba.
7
Chyba vstupních parametrů.
(nezadaný parametr userName, password nebo
merchantOrderId)
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
4.3.6.
cancelBlockedTransaction
Metoda slouží ke zrušení předautorizované (blokované) platby. Předautorizace bude zrušena a
blokovaná částka bude uvolněna zpět ve prospěch účtu zákazníka.
Metoda vyžaduje tyto vstupní parametry:
Parametr
Typ
Popis
userName
string
Uživatelské jméno obchodníka, kterým se hlásí
na portál PaySec.
password
string
Heslo pro MAPI. Heslo spojené s uživatelským
jménem obchodníka nelze použít.
merchantOrderId
string
Unikátní identifikátor předautorizované transakce.
Návratové hodnoty:
Metoda vrací kód v závislosti na stavu transakce:
Hodnota
Popis
0
Operace proběhla v pořádku.
2
Chybné uživatelské jméno nebo heslo.
3
Konto není aktivní.
4
Finanční transakce pro dané merchantOrderId neexistuje.
6
Systémová chyba.
7
Chyba vstupních parametrů.
(nezadaný parametr userName, password nebo
merchantOrderId)
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
5. Testovací platební brána – uživatelské rozhraní
Pro otestování implementace na straně Internetového obchodu nabízí platební řešení PaySec
Testovací platební bránu.
Testovací platební brána umožňuje provádět všechny transakce stejně jako na ostrém prostředí.
Umožňuje veškeré volání webových služeb MAPI.
Pro manuální kontrolu transakcí a volání MAPI je k dispozici jednoduchý webový přístup do
testovacího PaySec Konta pro obchodníky, kde je možné zkontrolovat provedené transakce
včetně jejich správného ověření.
Zde jsou k dispozici následující přehledy:

Přehled volání rozhranní MAPI

Přehled transakcí přijatých přes platební bránu se spárování příslušného volání
VerifyTransactionIsPaid
V testovacím prostředí má obchodník k dispozici testovací obchodnické PaySec Konto a
testovací osobní PaySec Konto. Osobní Konto je přednabité na 50 000 Kč.
Při platbě platební metodou PaySec se přihlásí do osobního Konta a z něj pošle na obchodnické
Konto částku transakce. Osobní Konto se automaticky pravidelně dobíjí při poklesu zůstatku pod
určitou částku. Z obchodnického Konta je možné také realizovat Vratky, kdy se prostředky vrací
na zdrojové osobní Konto.
Při platbě platební metodou z běžného účtu u ČSOB a Poštovní spořitelny je simulováno rozhraní
internetového bankovnictví, ze kterého je platba ihned převedena na PaySec Konto obchodníka.
Zde je neomezený limit na platbu. I zde může obchodník provádět vratku na zdrojový běžný
účet.
Při platbě platební kartou je simulováno rozhraní kartové brány, ze které je platba ihned
převedena na PaySec Konto obchodníka. Zde je neomezený limit na platbu. I zde může
obchodník provádět vratku na zdrojovou platební kartu.
Pro platbu běžným bankovním převodem zatím není k dispozici simulátor. To znamená, že na
testovací bráně není možné zaplatit a dokončit transakci offline platby. Proto bude volání
VerifyTransactionIsPaid se správnými parametry vracet pro offline platby vždy návratový kód 4
(špatné číslo objednávky nebo neexistující transakce).
Cílem testovací platební brány PaySec je umožnit obchodníkovi odladit komunikaci
mezi obchodem/portálem a službami PaySec. Speciálně ověřit to, jak jsou jednotlivé
transakce ověřovány pomocí MAPI metody VerifyTransactionIsPaid. Zde je nutné, aby
byly transakce z PaySec Konta na platební bráně označeny tmavě zelenou barvou.
Přehled transakcí na testovací platební bráně najdete po přihlášení na
https://testgateway.paysec.cz/Login.aspx v sekci Platební brána – Transakce.
5.1. Přihlášení do uživatelského rozhraní
Do uživatelského rozhranní testovací platební brány se lze přihlásit na adrese
https://testgateway.paysec.cz/Login.aspx
Pro přihlášení použijte přihlašovací jméno a heslo obdržené při od pracovníků prodejního teamu
PaySec.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
5.2. Platební brána – menu po přihlášení
Po přihlášení se zobrazí uživatelské rozhraní a v horní části obrazovky se zobrazí menu. Na tuto
stránku je možné se opět dostat kliknutím na Platební brána – Základní informace
Obrázek - menu uživatelského rozhraní Plat. brány
5.3. Platební brána – MAPI
Záložka plat. brána-MAPI umožňuje procházet a filtrovat volání rozhraní platební brány MAPI
(Merchant API). Jednotlivý řádek přehledu představuje jedno volání metody MAPI. V sloupci
Název metody se zobrazuje název volané metody a v sloupci Návratová hodnota je zobrazena
hodnota vrácená rozhraním. Filtr v horní části obrazovky umožňuje filtrovat volání MAPI podle
období (výsuvné pole Období, pole Datum od a Datum do), volané metody (výsuvné pole Název
metody) a návratové hodnoty (pole Návratová hodnota). Jednotlivé položky filtru lze mezi sebou
kombinovat. Pro aktivaci filtru stiskněte tlačítko Vyhledat. Kliknutím na číslo v sloupci MapiId
zobrazí detail volání Merchant API.
Obrázek - přehled volání MAPI
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
5.4. Platební brána – detail volání MAPI
Detail volání MAPI se zobrazí po kliknutí na MapiId a obsahuje následující informace:

MapiId – unikátní identifikátor volání

Název – název metody, která je na Merchant API volána

Číslo konta PaySec – číslo konta v systému PaySec

Číslo finanční transakce – číslo finanční transakce, ke které se volání MAPI vztahuje.
Kliknutím na číslo se zobrazí Detail platby.

Datum volání metody – čas kdy byla metoda volána

Uživatelské jméno – jméno uživatele, který MAPI volal

MerchantOrderId – identifikátor platby z internetového obchodu. Slouží pro identifikaci
platby obchodníkovi v internetovém obchodě.

Částka – částka volání

Název nebo číslo konta

Číslo mobilu

Datum od

Datum do

Zpráva pro odesílatele

Zpráva pro příjemce

Návratová hodnota – návratová hodnota metody Merchant API.
Obrázek - detail volání MAPI
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
5.5. Platební brána – Transakce
Záložka obsahuje seznam transakcí přijatých přes platební bránu. Pomocí barevného zvýraznění
je v přehledu zobrazeno, jak dlouho po vzniku transakce (od zadání a potvrzení platby
uživatelem na platební bráně) byl stav transakce ověřen metodou VerifyTransactionIsPaid přes
rozhraní MAPI. Barvy mají následující význam:
· Šedá barva – transakce byla přes platební bránu byla označena parametrem OrderId,
který se používá pro darovací platební tlačítko. U těchto transakcí není možné ověřovat
stav finanční transakce pomocí metody VerifyTransactionIsPaid.
· Tmavě zelená – transakce přijatá přes platební bránu byla ověřena do 1 minuty od
vzniku transakce. U transakcí z Konta PaySec značí pouze tento stav správnou
implementaci ověřování transakci.
· Světle zelená –transakce přijatá přes platební bránu byla ověřena za více než 1 a méně
než 5 minut od vzniku transakce.
· Žlutá – transakce přijatá přes platební byla ověřena za více než 5 a méně než 15 minut
od vzniku transakce.
· Oranžová – transakce přijatá přes platební bránu byla ověřena za více než 15 minut od
vzniku transakce.
· Červená – transakce přijatá přes platební bránu nebyla vůbec ověřena voláním metody
VerifyTransactionIsPaid. Každou transakci je nutné automatizovaně e-shopem
ověřit. Implementujte metodu VerifyTransactionIsPaid
· Fialová – poslední ověření stavu finanční transakce se nezdařilo, byl vrácen chybový kód
Obrázek - barevný filtr transakcí Platební brány
Kliknutím na Číslo platby v přehledu zobrazí Detail platby.
Filtr přehledu transakcí přijatých přes platební bránu
Přehled transakcí je možné filtrovat podle následujících kritérií:

Období – zobrazí pouze transakce za poslední týden/2 týdny/měsíc

Konta – zobrazí pouze transakce pro zadané konto

Datum od/do – zobrazí pouze transakce provedené v zadaném časovém intervalu

Částka od/do – zobrazí pouze transakce s částkou v zadaném intervalu

Čísla transakce – zobrazí pouze transakci odpovídající zadanému identifikátoru

Identifikace platby v internetovém obchodě (MerchantOrderId) – zobrazí pouze transakce
založené za účelem zaplacení požadavku přijatého pod identifikátorem MerchantOrderId.
Vyhledávání se potvrzuje stiskem tlačítka Zobrazit.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Obrázek - Přehled transakcí Platební brány
5.6. Platební brána – detail transakce
Z přehledu plateb na Platební bráně je možné kliknutím na číslo ve sloupci Číslo platby přejít na
detail platby. Detail platby obsahuje následující položky:

Číslo platby – identifikátor platby

Plátce – číslo konta plátce

Variabilní symbol platby

Typ – typ platby (např. převod z běžného účtu, převod z konta na konto, atd.)

Poznámka pro příjemce – zpráva pro příjemce od odesílatele platby

Stav – stav platby (např. nová, autorizovaná, odmítnutá, atd.)
Obrázek - detail platby
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
6. FAQ – nejčastější dotazy
Dotaz
Nedaří připojit na testovací bránu PaySec.
Odpověď
Nejčastější problémem s připojením ke zkušební platební bráně je zabezpečení komunikace
šifrováním. Téma je popsáno v kapitole 8.1 Bezpečná komunikace.
Dotaz
Máme internetový obchod. Opravdu musí být parametr MerchantOrderId unikátní? Jak máme
vyřešit situaci, kdy si klient objedná, přistoupí k platbě s číslem objednávky a platba se
nepodaří? Pak totiž klient nemá možnost pokusit se o platbu znovu, protože MerchantOrderId již
„vyčerpal“ prvním pokusem. Kvůli tomu nemůžeme MerchantOrderId použít pro naše číslo
objednávky a ztěžuje nám to párování transakcí a objednávek. Jaké navrhujete řešení?
Odpověď
Ano, parametr MerchantOrderId musí být jedinečný. Je to z důvodu možnosti později pomocí
MAPI ověřit, zda se transakce zaúčtovala úspěšně. V případě platebního tlačítka k ověřování
nedochází a parametr OrderId plní obecnou funkci variabilního symbolu (unikátnost není
vyžadována).
Případ opakovaného pokusu o zaplacení je však možný. Při placení na produkční platební bráně
totiž dochází k validaci před tím, než je transakce předána k zaúčtování.
Důsledkem toho je fakt, že transakce, která by selhala při účtování, vůbec nevznikne
(a „nevyčerpá“ tak MerchantOrderId).
Díky tomu pak opakovaný pokus neselže, neboť unikátnost MerchantOrderId nebude
porušena. Pokud si však již uživatel na rozcestníku zvolí platební metodu, pak je transakce
předána k zaúčtování a MerchantOrderId je tím použito.
Dotaz
Při platbě v internetovém obchodě je zákazník přesměrován na bránu PaySec. Tam zaplatí a pak
je přesměrován zpět. V URL se zpět posílá i parametr "tid", tedy nějaké ID transakce.
Dotaz zní: Pokud se transakce povedla, tak je "tid" vždy nenulové? Jinak řečeno, pokud přijde
tid>0, dá se to s jistotou považovat za úspěšně provedenou transakci?
Odpověď
Číslo transakce tid má pouze informativní charakter.
Slouží primárně jako informace pro dohledání v případě nějakých kolizí.
Podmínka tid>0 pouze říká, zda má cenu ověřovat stav transakce, nebo je již jasné, že
neproběhla:
Tid = 0 ... Platba byla zamítnuta
Tid > 0 ... Není jisté, je potřeba ověřit
Skutečný stav transakce zjistíte až po volání webové služby MAPI.
Kontrola tid je nedostatečná z důvodu možné modifikace parametru útočníkem - osobou snažící
se zfalšovat platbu.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
7. Označení internetového obchodu logem PaySec
Internetový obchod se uzavřením smlouvy zavazuje k označení webových stránek logy a bannery
platebního řešení PaySec.
Kroky k označení stránek e-shopu jsou následující:
1. Implementace PaySec na testovacím rozhraní
2. Úspěšné otestování platby a jejího ověření pracovníkem e-shopu (většinou implementátorem)
vůči testovací platební bráně PaySec
3. Zprovoznění platební metody PaySec v ostrém e-shopu
4. Oznámení zprovoznění platební metody PaySec v ostrém e-shopu pracovníkům teamu PaySec
5. Provedení zkušebního nákupu a platby přes ostrou platební bránu PaySec pracovníkem teamu
PaySec
6. Provedení vratky ze strany e-shopu
7. V případě úspěchu odsouhlasení implementace ze strany teamu PaySec
8. Obchodník označí e-shop požadovanými logy PaySec (do doby uvedené ve smlouvě)
9. Obchodník oznámí označení e-shopu pracovníkům teamu PaySec
10. Kontrola označení e-shopu logy Paysec pracovníky teamu PaySec
11. Odsouhlasení e-shopu ze strany pracovníků teamu PaySec
12. Zaslání loga e-shopu a krátkého textu o e-shopu pracovníkům teamu PaySec
13. Uvedení loga e-shopu spolu s textem v adresáři PaySec: http://adresar.paysec.cz/
Loga a bannery PaySec jsou ke stažení v sekci Pro obchodníky a v sekci Pro neziskovky na webu
PaySec.
U označení je nutné použít následující logo PaySec buď ve svislé nebo vodorovné verzi. Logo je
dostupné v různých velikostech.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
8. Přílohy
8.1. Bezpečná komunikace
Komunikace mezi elektronickým obchodem a systémem PaySec probíhá pomocí zabezpečeného
kanálu. Veškerá komunikace je zašifrována tak, aby byla zajištěna integrita (nikdo zprávu
nezmění) a důvěrnost (nikdo si zprávu nepřečte) dat. K zašifrování se používají certifikáty. Aby si
byl elektronický obchod jistý, že posílá data správnému serveru, musí certifikát ověřit. Ověření
většinou provádí hostující prostředí (iis/windows, apache/linux, …) samo. Za tímto účelem
existuje v prostředí seznam s důvěryhodnými certifikáty.
V okamžiku, kdy internetový obchod zahajuje komunikaci, prokazuje se server svým
certifikátem. Prostředí pak samo tento certifikát porovná se svým seznamem, a pokud jej najde,
komunikace pokračuje. V opačném případě komunikace selže. Typickým symptomem této
situace je chyba: Could not establish an encrypted connection because certificate presented by
testgateway.paysec.cz has an invalid signature.
Pro úplnost je třeba dodat, že ke korektnímu ověření může dojít i jinak. Stačí, když se za určitý
server (resp. jeho certifikát) zaváže (digitálně jej podepíše) tzv. certifikační autorita. Certifikační
autorita se rovněž identifikuje svým certifikátem, který už pak v seznamu důvěryhodných být
musí.
8.1.1.
Nastavení serverového certifikátu jako důvěryhodného
Operační systémy Windows
Pro operační systémy Microsoft Windows je produkční certifikát podepsán GlobalSign CA, která je
tzv. Microsoft Trusted. To znamená, že certifikáty podepsané touto CA jsou automaticky
považovány za důvěryhodné.
V případě, že by tomu tak na Vašem systému nebylo nebo potřebujete komunikovat se zkušební
platební bránou, postupujte následovně:
1)
Připravte si soubor s certifikátem. Oba certifikáty, testovací i produkční, lze vytvořit
z informací uvedených v kapitole 4.2 Zabezpečení komunikace.
2)
Klikněte na tlačítko Start – Spustit – pak napište a odešlete: mmc.exe
3)
Objeví se okno. Z roletového menu vyberte: File – Add/Remove snap-in (Soubor –
přidat nebo odebrat modul snap-in).
4)
Klikněte na tlačítko Add (Přidat).
5)
Nalistujte položku Certificates (Certifikáty) a potvrďte.
6)
Zvolte Computer account (Účet počítače).
7)
Potvrďte všechny otevřené dialogy
8)
Rozbalte adresářovou strukturu certifikátů v levé části okna
9)
Vyvolejte kontextové menu nad Trusted Root Certification Authorities (Důvěrné
kořenové certifikační úřady)
10) Vyberte All Tasks – Import (Všechny úkoly - importovat)
11) Nalistujte soubor s příslušným certifikátem a naimportujte jej.
Tip: Používáte-li ASP.NET 2.0, lze pouze pro testovací účely toto ověření obejít. Viz kapitola
8.2.4.
Jiné operační systémy
Doporučujeme prostudovat stránky společnosti GlobalSign, kde je popis instalace certifikátů
pro různá prostředí:
http://www.globalsign.com/support/root-certificate/domainserversign.html
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
8.2. Příklady volání webové služby MAPI z různých technologií
V této kapitole nejprve uvedeme definici SOAP zpráv, které si mezi sebou klient a služba
vyměňují. Tato znalost stačí k tomu, aby bylo možno službu volat z široké palety technologií,
které v zásadě musí podporovat pouze zaslání textového řetězce přes https protokol. Ukážeme
Vám vzorovou implementaci v jazyku C# 2.0, která tento způsob využívá.
Jakkoli je volání přímo na úrovni zpráv možné, existují efektivnější způsoby. Uvidíte způsob
implementace v technologiích PHP a ASP.NET 2.0.
8.2.1.
Definice SOAP zpráv
Vstupní SOAP zpráva
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<userName
xmlns="http://schemas.mapi.paysec.cz/2008/02">OBCHODNIK123</userName>
<password
xmlns="http://schemas.mapi.paysec.cz/2008/02">P@SSWORD</password>
<merchantOrderId
xmlns="http://schemas.mapi.paysec.cz/2008/02">111</merchantOrderId>
<amount xmlns="http://schemas.mapi.paysec.cz/2008/02">222</amount>
</soap:Body>
</soap:Envelope>
Nahraďte zvýrazněné hodnoty vlastními.
Výstupní SOAP zpráva
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<VerifyTransactionIsPaidResult
xmlns="http://schemas.mapi.paysec.cz/2008/02">4</VerifyTransactionIsPaidResult>
</s:Body>
</s:Envelope>
Získejte zvýrazněnou hodnotu.
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
8.2.2.
C# 2.0 pomocí SOAP zpráv
V tomto případě je využita třída System.Net.HttpWebRequest, pomocí které je zaslána
webové službě SOAP zpráva. Tato zpráva musí být poslána metodou POST a odpovědí na ní je
opět SOAP zpráva, ze které je následné vyčten návratový kód Merchant API.
using
using
using
using
using
System;
System.Net;
System.Text;
System.IO;
System.Xml;
namespace GateWayTest
{
class Program
{
static string request = @"
<soap:Envelope xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/""
xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""
xmlns:xsd=""http://www.w3.org/2001/XMLSchema"">
<soap:Body>
<userName
xmlns=""http://schemas.mapi.paysec.cz/2008/02"">obchodnik123</userName>
<password
xmlns=""http://schemas.mapi.paysec.cz/2008/02"">P@ssword</password>
<merchantOrderId
xmlns=""http://schemas.mapi.paysec.cz/2008/02"">111</merchantOrderId>
<amount xmlns=""http://schemas.mapi.paysec.cz/2008/02"">222</amount>
</soap:Body>
</soap:Envelope>
";
static void Main(string[] args)
{
HttpWebRequest webRequest =
(HttpWebRequest)WebRequest.Create("https://testmapi.paysec.cz/mapi.svc?wsdl");
webRequest.Headers.Add("SOAPAction",
"http://schemas.mapi.paysec.cz/2008/02/ShoppingService/VerifyTransactionIsPaid");
webRequest.ContentType = "text/xml;charset=utf-8";
webRequest.Method = "POST";
byte[] postDataBytes = Encoding.UTF8.GetBytes(request);
using (Stream stream = webRequest.GetRequestStream())
{
stream.Write(postDataBytes, 0, postDataBytes.Length);
}
HttpWebResponse res = (HttpWebResponse)webRequest.GetResponse();
StreamReader str = new StreamReader(res.GetResponseStream(), true);
XmlDocument xmlResponse = new XmlDocument();
xmlResponse.LoadXml(str.ReadToEnd());
res.Close();
str.Close();
XmlNamespaceManager nsmgr = new XmlNamespaceManager(xmlResponse.NameTable);
nsmgr.AddNamespace("ab", "http://schemas.mapi.paysec.cz/2008/02");
XmlNode resultNode = xmlResponse.SelectSingleNode("//ab:VerifyTransactionIsPaidResult",
nsmgr);
string retVal = resultNode.InnerText;
Console.WriteLine("Result code: " + retVal);
}
}
}
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
8.2.3.
PHP 5.2.5
V případě PHP lze využít rozšíření php_soap (komunikace s webovými službami) a
php_openssl (protokol HTTPS). Tyto rozšíření lze zapnout editací konfiguračního souboru
php.ini. Tento soubor musí obsahovat následující dvě řádky.
extension=php_soap.dll
extension=php_openssl.dll
Poté lze s webovou službou komunikovat jako v následujícím příkladu.
<?php
$paysecMapi = new SoapClient("https://testmapi.paysec.cz/mapi.svc?wsdl");
$resultCode = $paysecMapi->VerifyTransactionIsPaid("obchodnik123", " P@ssword", " 111", "
222");
echo "Result code: $resultCode";
?>
8.2.4.
ASP.NET 2.0
Příklad předpokládá, že jste pro volání webové služby vygenerovali proxy třídu s názvem
MerchantAPI.ShoppingService.
// Input parameters
string username = "obchodnik123";
string password = "P@ssw0rd";
string merchantOrderId = PregeneratedMerchantOrderId;
decimal amount = decimal.Parse(Request.QueryString["Amount"]);
// Result
int verificationResult;
// Call Web service
MerchantAPI.ShoppingService shoppingService = new MerchantAPI.ShoppingService();
verificationResult = shoppingService.VerifyTransactionIsPaid(username, password, merchantOrderId,
amount);
// Process result
if (verificationResult==0)
{
// Paid
}
else
{
// Not paid yet
}
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
Pouze pro testování – nedůvěryhodná CA
Potřebujete-li ověřit implementaci v ASP.NET 2.0 na serveru, kde nemáte možnost nainstalovat
testovací certifikát, můžete využít níže uvedené implementace.
Příklad je vhodný pouze pro testovací účely. Máte-li možnost, volte raději cestu instalace
testovacího certifikátu.
/// <summary>
/// Ověří platbu pomocí MAPI.
/// </summary>
public void ValidatePayment()
{
// Vstupni parametry
string username = "obchodik123";
string password = "P@ssw0rd";
string merchantOrderId = PregeneratedMerchantOrderId;
decimal amount = decimal.Parse(Request.QueryString["Amount"]);
// Vysledek
int verificationResult;
// Nastavení pravidel pro validaci serverových certifikátů. Nastavení je provedeno
// obecně pro všechny ServicePoint instance, vzniklé po provedení následující řádky
ServicePointManager.ServerCertificateValidationCallback = new
RemoteCertificateValidationCallback(myCertificateValidation);
// Volani Web service
MerchantAPI.ShoppingService shoppingService = new MerchantAPI.ShoppingService();
verificationResult = shoppingService.VerifyTransactionIsPaid(username, password, merchantOrderId,
amount);
// Zpracovat vysledek
if (verificationResult==0)
{
// Paid
}
else
{
// Not paid yet
}
}
/// <summary>
/// Tato implementace VŽDY POVOLÍ komunikaci.
/// NEPOUŽÍVAT PRO PRODUKČNÍ PROSTŘEDÍ.
/// </summary>
/// <returns><c>True</c>, pokud se má komunikace povolit. Jinak <c>False</c>.</returns>
public bool myCertificateValidation(Object sender, X509Certificate certificate,
X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
// Vždy povolí komunikaci!!!
return true;
}
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
8.2.5.
ASP 3.0 – Visual Basic
V tomto případě je využit COM objekt MSXML2.XMLHTTP.6.0, pomocí kterého je zaslána
webové službě SOAP zpráva. Tato zpráva musí být poslána metodou POST a odpovědí na ní je
opět SOAP zpráva, ze které je následné vyčten návratový kód Merchant API. To je realizováno
pomocí COM objektu MSXMLl2.DOMDOCUMENT.3.0, který je určen pro práci s XML.
<%@ Language="VBScript" %>
<%Option Explicit%>
<%
Dim soapRequest
soapRequest = "<soap:Envelope
xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/""
xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""
xmlns:xsd=""http://www.w3.org/2001/XMLSchema"">" & _
"
<soap:Body>" & _
"
<userName
xmlns=""http://schemas.mapi.paysec.cz/2008/02"">Login</userName>" & _
"
<password
xmlns=""http://schemas.mapi.paysec.cz/2008/02"">Heslo</password>" & _
"
<merchantOrderId
xmlns=""http://schemas.mapi.paysec.cz/2008/02"">111</merchantOrderId>" & _
"
<amount xmlns=""http://schemas.mapi.paysec.cz/2008/02"">222</amount>" &
_
"
</soap:Body>" & _
"</soap:Envelope>"
Dim xmlhttp
Set xmlhttp = server.Createobject("MSXML2.XMLHTTP.6.0")
xmlhttp.open "POST", "https://testmapi.paysec.cz/mapi.svc", false
xmlhttp.setRequestHeader "Content-Type","text/xml;charset=utf-8"
xmlhttp.setRequestHeader "SOAPAction",
"http://schemas.mapi.paysec.cz/2008/02/ShoppingService/VerifyTransactionIsPaid"
xmlhttp.send soapRequest
Dim xml_document
Set xml_document = server.Createobject("Msxml2.DOMDocument.3.0")
xml_document.loadXML xmlhttp.responseText
Response.Write "Result code: " & xml_document.text
%>
© 2007-2014 Československá obchodní banka, a.s.
Příručka pro použití Platební brány PaySec verze 1.20
8.2.6.
Python
from ZSI.client import Binding
from ZSI import TC
PAYSEC_USER = "login"
PAYSEC_PASS = "password"
PAYSEC_MAPI = "https://testmapi.paysec.cz/mapi.svc"
""" VerifyTransactionIsPaid """
class VerifyTransactionIsPaidParameters:
def __init__(self, merchantOrderId, amount):
self.userName = PAYSEC_USER
self.password = PAYSEC_PASS
self.merchantOrderId = merchantOrderId
self.amount = amount
class TC_VerifyTransactionIsPaidParameters(TC.SimpleType):
def get_formatted_content(self, pyobj):
return str(pyobj)
def serialize(self, elt, sw, pyobj, name=None, orig=None, **kw):
ns = "http://schemas.mapi.paysec.cz/2008/02"
el = elt.createAppendElement(ns,
self.serialize_text_node(el, sw,
el = elt.createAppendElement(ns,
self.serialize_text_node(el, sw,
el = elt.createAppendElement(ns,
self.serialize_text_node(el, sw,
el = elt.createAppendElement(ns,
self.serialize_text_node(el, sw,
"userName")
pyobj.userName)
"password")
pyobj.password)
"merchantOrderId")
pyobj.merchantOrderId)
"amount")
pyobj.amount)
return None
typecode = TC_VerifyTransactionIsPaidParameters()
class VerifyTransactionIsPaidResult:
typecode = TC.Integer("VerifyTransactionIsPaidResult")
def VerifyTransactionIsPaid(merchantOrderId, amount):
SOAPAction =
"http://schemas.mapi.paysec.cz/2008/02/ShoppingService/VerifyTransactionIsPaid"
params = VerifyTransactionIsPaidParameters(merchantOrderId, amount)
b = Binding(url=PAYSEC_MAPI)
b.Send(PAYSEC_MAPI, None, params, soapaction=SOAPAction)
return b.Receive(VerifyTransactionIsPaidResult)
if __name__ == "__main__":
print VerifyTransactionIsPaid("ABCDEF", 256.00)
© 2007-2014 Československá obchodní banka, a.s.