M INTEGRACE DO SYSTÉMU OBCHODNÍHO PARTNERA

ProxyPay

3/M

INTEGRACE DO SYSTÉMU OBCHODNÍHO PARTNERA

VERZE

AUTOR

ZMĚNY

DATUM

2.9

Richard Švec, Petr Štefko, Tomáš Novotný, Zbyšek Strnad

30.3.2006

3.0

David Maleček, Jakub Špiroch

22.4.2009

3.1

Jakub Špiroch

17.8.2009

3.2

Ing. Radovan Bryx, Tomáš Žák

9.11.2011 » Registrované platby (kap. 5) » Rejection POST (kap. 4.5)

3.3

Ing. Radovan Bryx, Tomáš Žák

» Zjišťování stavu transakce (kap. 7.2)

13.6.2012

» Proměnná „brand“ nepovinná (kap 4.2) » Změna max. délky certifikátu (Příloha B) 3.3.3

Ing. Radovan Bryx

4.0

Ing. Radovan Bryx

» Nové jazyky platební brány (kap. 4.2)

9.10.2013

» Texty pro internetové stránky(příloha C) » Oprava chyb

9.4.2014

» Grafické úpravy (celý dokument) » Doplnění odpovědí v XML (kap. 4.4) 4.1.

Ing. Radovan Bryx

» Změna podporovaných portů (kap.8)

3.10.2014

» Nová pole OrderID1 a OrderID2 (kap.2) 4.2. Ing. Radovan Bryx, Tomáš Žák

» Nová funkce OneClickPayments (kap.5)

e-commerce – Integrace do systému obchodního partnera

20.10.2014

2

OBSAH 1.

JAK PROBÍHÁ IMPLEMENTACE .................................................... 6

2.

INTEGRACE DO VAŠEHO SYSTÉMU ........................................... 7

2.1.

JAK PROBÍHÁ TRANSAKCE ................................................................................................... 7

2.2.

JAK INICIOVAT PLATBU? (NEW PAYMENT POST) ............................................................ 10

2.3.

VALIDATION POST (POVINNÉ) ............................................................................................ 14

2.4 CONFIRMATION POST (POVINNÉ) ........................................................................................... 17 2.5 REJECTION POST (POVINNÉ) .................................................................................................. 20

3.

REGISTROVANÉ PLATBY (VOLITELNÉ) ..................................... 23

4.

XML INTERFACE (VOLITELNÉ) ................................................... 25

4.1 PRINCIP XML ROZHRANÍ .......................................................................................................... 25 4.2 SPECIFIKACE XML ZPRÁVY ..................................................................................................... 26 4.3 XML DOTAZ (XML REQUEST) ................................................................................................... 26 4.3.1. Příklad: SaleRequest (pouze pro MO/TO transakce) .......................................................... 29 4.3.2.

Příklad: AuthorisationRequest (pouze pro MO/TO transakce) ........................................ 30

4.3.3.

Příklad: CaptureRequest ................................................................................................. 30

4.3.4.

Příklad: CancelRequest ................................................................................................... 31

4.3.5.

Příklad: RefundRequest ................................................................................................... 31

4.3.6.

Příklad: TransactionStatusRequest ................................................................................. 32

4.3.7.

Příklad: LastTransactionsRequest ................................................................................... 32

4.3.8.

Příklad: Pozastavení recurring transakce ........................................................................ 33

4.3.9.

Příklad: Obnovení recurring transakce ............................................................................ 33

4.3.10.

Příklad: Zrušení recurring transakce ............................................................................ 33

4.4 XML ODPOVĚĎ (XML RESPONSE) ........................................................................................... 34 4.4.1.

Příklad SaleResponse – neúspěšná transakce ............................................................... 37

4.4.2.

Příklad AuthorisationResponse – úspěšná předautorizace ............................................. 37

4.4.3.

Příklad TransactionStatusResponse ............................................................................... 37

4.4.4.

Příklad LastTransactionsResponse ................................................................................. 38

4.4.5.

Příklad RecurringOperationResponse – úspěšná akce................................................... 39

4.4.6.

Příklad ErrorMessage – nesprávné přihlašovací údaje ................................................... 39

4.5 SEZNAM MOŽNÝCH STAVŮ TRANSAKCE............................................................................... 39 4.6 ČÍSLOVÁNÍ SUBREFERENCE ................................................................................................... 40

5.

ONE CLICK PAYMENTS (OCP) - VOLITELNÉ ............................. 42

5.1.

PRVNÍ TRANSAKCE .............................................................................................................. 42

5.2.

DALŠÍ TRANSAKCE ............................................................................................................... 43

5.3.

NASTAVENÍ ZABEZPEČENÍ PRO OCP ................................................................................ 44

5.4.

CHYBOVÉ HLÁŠKY OCP....................................................................................................... 45

e-commerce – Integrace do systému obchodního partnera

3

5.5.

6.

DALŠÍ XML DOTAZY PRO OCP ............................................................................................ 45

EMAILOVÉ ŠABLONY (VOLITELNÉ)............................................ 47

6.1 EMAIL PRO OBCHODNÍHO PARTNERA ................................................................................... 47 6.2 EMAIL PRO DRŽITELE KARTY .................................................................................................. 48

7.

MERCHANT BACKOFFICE .......................................................... 51

8.

ZABEZPEČENÍ.............................................................................. 52

8.1

PREVENCE PROTI CROSS-SITE SCRIPTING .................................................................... 52

8.2 PREVENCE PROTI SQL INJECTION ......................................................................................... 52

9.

NEJČASTĚJŠÍ DOTAZY ............................................................... 54

Příloha A – povolené znaky pro proměnnou cardholderID ............................................................... 56 Příloha B - podporované certifikáty ................................................................................................... 58 Příloha C – Text určený pro web obchodního partnera .................................................................... 59 Příloha D – Informace pro registraci ................................................................................................. 61

e-commerce – Integrace do systému obchodního partnera

4

ÚVODEM Vítáme Vás v implementační příručce, která má za cíl poskytnout Vám všechny potřebné informace integraci Vašeho e-shopu do systému e-commerce České spořitelny a.s. Popisuje potřebné úkony pro úspěšné zavedení a otestování on-line platby kartou na e-shopu a vysvětluje, jakým způsobem funguje komunikace mezi e-shopem a platebním systémem ČS. Řešení je určeno pro přijímání a zpracování on-line transakcí z internetového nebo mobilního obchodního systému. Je kladen důraz na jednoduchou integraci, platformovou nezávislost, možnost implementace pomocí libovolného skriptovacího jazyka a využití libovolného webového serveru a databáze. K výměně dat slouží zabezpečený HTTPS protokol. Pro správu provedených transakcí slouží obchodnímu partnerovi rozhraní Merchant Back Office umožňující přístup uživatelů ve třech úrovních oprávnění (viz kapitola 7).

TIP: ZAPAMATUJTE SI DŮLEŽITÉ NÁZVY ProxyPay

Název pro systém platební brány České spořitelny

Merchant BackOffice

Webové prostředí pro přehled a správu transakcí

e-commerce – Integrace do systému obchodního partnera

5

1. JAK PROBÍHÁ IMPLEMENTACE Proces implementace (od zaslání potřebných formulářů a smluvních podkladů obchodnímu zástupci ČS do spuštění ostrého provozu) lze v ideálním případě stihnout za jeden týden, pokud je na straně obchodního partnera všechno připraveno podle pokynů v této příručce. Integrace e-shopu obchodního partnera do systému e-commerce ČS běžně probíhá v následujících krocích:

Od obchodního zástupce při podpisu smlouvy o přijímání karet obdržíte registrační formulář, který vyplníte a předáte zpět

Informace z formuláře jsou zadány do systémů ČS a pro daný e-shop je vytvořena virtuální provozovna s unikátním obchodnickým číslem označovaným jako „MerchantID“

Podpora e-commerce v ČS Vám zašle na e-mailové adresy uvedené v registračním formuláři potřebné podklady pro otestování propojení e-shopu s platební bránou (virtuální testovací karty, MerchantID, přihlašovací údaje do rozhraní Merchant Back Office) Po obdržení testovacích podkladů začnete se samotnými testy, tj. s vytvářením testovacích nákupů a transakcí. Během testování je Vám k dispozici podpora e-commerce, která zodpoví případné dotazy a pomůže Vám vyřešit případné problémy s funkčností plateb

Po dokončení testování a kontrole funkčnosti ze strany ČS přejdou obě strany do ostrého provozu, platební bránu poté můžete zpřístupnit svým klientům

e-commerce – Integrace do systému obchodního partnera

6

2. INTEGRACE DO VAŠEHO SYSTÉMU Integrace propojení mezi Vaším systémem a platební bránu není třeba považovat za velmi složitou akci, která by si vyžádala velké náklady a úsilí. Samozřejmě je třeba připomenout, že náročnost závisí na „hloubce implementace“ do Vašich systémů. Implementace je jistě odlišná mezi základním e-shopem a velkou korporací, která využívá rozsáhlé vnitrofiremní systémy. Aby bylo zřejmé, jako komunikace mezi Vámi a platební bránou probíhá, v první podkapitole si vysvětlíme, jak taková transakce vzniká.

TIP: CO BUDETE POTŘEBOVAT

HTTPS

INFO

CERTIFIKÁT

První krok integrace s platební bránou je zajištění SSL certifikátu pro Vaše stránky. V příloze tohoto dokumentu naleznete podporované formáty. Certifikát nemusí být podepsaný certifikační autoritou, takže může být „self-signed“. Myslete ovšem na to, že pokud nemáte ověřený certifikát, některé prohlížeče mohou klientovi po zaplacení zobrazit upozornění o přechodu na nedůvěryhodné stránky.

POTŘEBNÉ ÚDAJE

V příloze D najdete informace, které od Vás budeme potřebovat před zahájením implementace.

2.1. JAK PROBÍHÁ TRANSAKCE Tato kapitola vysvětluje, jakým způsobem probíhá on-line transakce a specifikuje komunikaci mezi systémem ProxyPay a Vaším e-shopem. Obsahuje i přehled a stručný popis proměnných, které se během komunikace předávají. Následující postup stručně ukazuje, jakým způsobem probíhá komunikace mezi prohlížečem držitele karty, Vaším systémem a platební bránou ČS. KROK

Klient si na Vašich stránkách vybere zboží/službu a jako způsob platby zvolí platbu kartou on-line.

KROK

e-commerce – Integrace do systému obchodního partnera

Váš systém odešle metodou POST formulář s informacemi o platbě a objednávce na adresu systému ProxyPay

7

KROK

ProxyPay provede kontrolu údajů a uloží je, načež je odešle zpět na Vaši Validation URL. Validation skript zkontroluje, zda přijaté údaje souhlasí s těmi, které původně odeslal. Pokud ano, odpoví HTML řetězcem: [OK]

X

KROK

Pokud se podařilo načíst [OK] odpověď od validation skriptu, ProxyPay odešle do prohlížeče držitele karty stránku s popisem objednávky a s požadavkem na vložení údajů o kartě (číslo, expirace, CVV). Držitel karty vyplní tyto údaje a potvrdí odeslání. ProxyPay využije údaje o kartě k autorizaci platby. Pokud načítání odpovědi validation skriptu z nějakého důvodu selhalo nebo skript vygeneroval jinou odpověď než [OK], ProxyPay přeskočí na krok 7

KROK

Po úspěšném dokončení autorizace transakce odešle ProxyPay metodou POST souhrnné údaje o objednávce na Vaši Confirmation URL. Confirmation skript opět zkontroluje, zda přijaté údaje souhlasí s těmi, které původně odeslal. Pokud ano, odpoví HTML řetězcem: [OK]

X Pokud se podařilo načíst [OK] odpověď od confirmation skriptu, ProxyPay odešle do prohlížeče držitele karty stránku, která jej přesměruje na Vaši stránku OK URL. Pokud je povoleno zasílání oznamovacích e-mailů, Vám a držiteli karty je zaslán e-mail potvrzující úspěšné dokončení platby. KROK

Pokud načítání odpovědi confirmation skriptu z nějakého důvodu selhalo nebo skript vygeneroval jinou odpověď než [OK], ProxyPay přeskočí na krok 7. Timeout odpovědi je 15 sekund. Pokud v této lhůtě není obdržena odpověď, ProxyPay opakuje znovu bod 6 se stejným timeoutem. Pokud ani tentokráte není obdržena odpověď, ProxyPay tuto transakci automaticky reverzuje (zruší) a přeskočí na krok 7.

e-commerce – Integrace do systému obchodního partnera

8

Pokud v kterémkoliv bodě při zpracování transakce dojde k chybě, ProxyPay odešle Rejection POST na Vaši Rejection URL.

KROK

Zároveň odešle do prohlížeče držitele karty stránku, která jej přesměruje na Vaši NOK URL.

Platba je v ProxyPay úspěšně dokončena v okamžiku, kdy ProxyPay přijme [OK] odpověď od confirmation skriptu. Může nastat případ, kdy Vaše odpověď nedorazí do ČS (dojde ke ztrátě zprávy během přenosu) nebo odpověď skriptu nemá správnou podobu. Jako dodatečný kontrolní mechanismus lze implementovat XML Interface a dotázat se po zaplacení na stav dané transakce.

TIP: DOPORUČUJEME IMPLEMENTOVAT XML

XML INTERFACE

Přes XML rozhraní se můžete systému ProxyPay dotázat na stav jakékoliv transakce. XML User tak pro Vás může být dodatečným kontrolním mechanismem, který například minutu po provedení transakce zjistí její finální stav.

e-commerce – Integrace do systému obchodního partnera

9

2.2.

JAK INICIOVAT PLATBU? (NEW PAYMENT POST)

Nyní již víme, jak transakce probíhá. Jak tedy iniciovat platbu? Na Vaší stránce „Shop URL“ (označované také jako referrer), kde bude docházet k inicializaci platby, je třeba naimplementovat kód, který zajistí odeslání informací o platbě metodou HTTP POST na adresu platební brány systému ProxyPay https://3dsecure.csas.cz/transaction. Tento požadavek na vytvoření platby se jinak nazývá také New Payment POST.

Jak New Payment POST vypadá:

...

Atribut „messageId“ je osmimístné číslo, které může být použito ve Vašem pro párování odpovědi z ProxyPay s konkrétní XML zprávou. Na straně ProxyPay není kontrolována unikátnost tohoto čísla, ale pro snadnější orientaci v komunikaci doporučujeme používat unikátní messageId pro každou novou XML zprávu.

4.3 XML DOTAZ (XML REQUEST) XML dotaz je zpráva zasílaná Vaším systémem do systému ProxyPay. Každá akce prováděná v systému ProxyPay má přiřazen určitý typ XML zprávy. Tyto zprávy se liší strukturou, použitými elementy a hodnotami elementů. Dle typu zprávy (a odpovídající akce v ProxyPay) je nutné zprávu zapouzdřit do správného elementu.

!

UPOZORNĚNÍ: AKCE, PRO KTERÉ LZE XML POUŽÍVAT

XML VYTVÁŘENÍ PLATBY

XML zprávy pro vytváření nových plateb (SaleRequest a AuthorisationRequest) jsou povoleny pouze pro rozhraní MO/TO a nelze je využívat pro e-commerce.

Seznam zpráv povolených pro jednotlivá rozhraní a názvy příslušných zapouzdřujících elementů je uveden v následující tabulce:

e-commerce – Integrace do systému obchodního partnera

26

AKCE V PROXYPAY

ZAPOUZDŘUJÍCÍ ELEMENT

MO/TO

E-COM

Prodej

<SaleRequest>

ANO

NE

Předautorizace



ANO

NE

Dokončení předautorizace



ANO

ANO

Zrušení předautorizace



ANO

ANO

Refundace



ANO

ANO

Zjištění stavu transakce



ANO

ANO

Výpis posledních transakcí



ANO

ANO

Operace s recurring transakcemi



ANO

ANO

XML ELEMENT

SALE

AUTHORISATION

CAPTURE

CANCEL

REFUND

STATUS

LAST TRX

RECURRING

Seznam elementů a jejich povinnost pro konkrétní XML zprávy:

Authentication

M

M

M

M

M

M

M

M

MerchantID

M

M

M

M

M

M

M

M

UserName

M

M

M

M

M

M

M

M

Password

M

M

M

M

M

M

M

M

M

M

M

M

M

M

Amount

M

M

M

M

M

M

MerchantRef

M

M

M

M

M

M

M

ServerRef

O

O

O

O

O

O

O

SubReference

O

O

M

M

M

M

O

MerchantDesc

O

O

Currency

M

M

CustomerEmail

O

O

MOTO

M

M

Var1 - Var9

O

O

OrderInfo

NumberOfTransactions

e-commerce – Integrace do systému obchodního partnera

M

M

27

RECURRING

LAST TRX

STATUS

REFUND

CANCEL

CAPTURE

AUTHORISATION

SALE

XML ELEMENT

M

Operation PaymentInfo

M

M

Brand

M

M

Pan

M

M

ExpDate

M

M

CvvCvc2

M

M

M – povinný element, O – nepovinný element, prázdné – element musí být vynechán

Definice jednotlivých elementů a jejich datových typů: TYP

XML ELEMENT

POPIS

Authentication MerchantID

N 1-6

ID obchodního partnera přidělené ČS

UserName

AN 1-50

uživatelské jméno přidělené ČS

Password

AN 7-16

uživatelské heslo přidělené ČS

Amount

N 1-11

částka transakce v haléřích/centech

MerchantRef *

AN 1-12 *

unikátní referenční číslo transakce

ServerRef

N 1-12

číslo transakce přidělené systémem ProxyPay

SubReference **

N 1-3

sub-referenční číslo transakce

MerchantDesc

AN 1-1024

popis objednávky

Currency ***

N3

{203|978|826|840}

CustomerEmail

AN 1-50

emailová adresa držitele karty

MOTO ****

N1

{1|0}

Var1 – Var9

AN 1-255

volitelná proměnná

OrderInfo

e-commerce – Integrace do systému obchodního partnera

28

TYP

XML ELEMENT

POPIS

NumberOfTransactions

N 1-3

požadovaný počet transakcí na výpisu (max. 100)

Operation

AN 6-7

{Suspend|Cancel|Resume}

Brand

A 4-12

typ karty (VISA, VisaElectron, MasterCard)

Pan

N 11-19

číslo karty

ExpDate

N4

datum expirace karty (MMYY)

CvvCvc2

N3

CVV/CVC kód

PaymentInfo

* pro MOTO transakce je max. povolená délka 10 znaků, pro počáteční recurring transakce 8 znaků ** číslo dceřinné transakce – viz kapitola 5.2. *** kódy měn: CZK - 203, EUR - 978, GBP - 826, USD – 840 **** 1 – MO/TO transakce, 0 – e-commerce transakce

4.3.1. Příklad: SaleRequest (pouze pro MO/TO transakce) <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <SaleRequest> <MerchantID>123456 <UserName>xmluser <Password>heslo 100 <MerchantRef>110161408 203 [email protected] <MOTO>1 <PaymentInfo> VISA <Pan>4912345678901234 <ExpDate>1015 123

e-commerce – Integrace do systému obchodního partnera

29

4.3.2. Příklad: AuthorisationRequest (pouze pro MO/TO transakce) <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo 100 <MerchantRef>110231649 203 [email protected] <MOTO>1 <PaymentInfo> VISA <Pan>4912345678901234 <ExpDate>1015 123

4.3.3. Příklad: CaptureRequest <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo 100 <MerchantRef>110231649 <SubReference>0

e-commerce – Integrace do systému obchodního partnera

30

4.3.4. Příklad: CancelRequest <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo 100 <MerchantRef>110231649 <SubReference>0

4.3.5. Příklad: RefundRequest <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo 100 <MerchantRef>110161408 <SubReference>0

e-commerce – Integrace do systému obchodního partnera

31

4.3.6. Příklad: TransactionStatusRequest <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo <MerchantRef>3303203652 <ServerRef>0 <Subreference>0

4.3.7. Příklad: LastTransactionsRequest <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo 5

e-commerce – Integrace do systému obchodního partnera

32

4.3.8. Příklad: Pozastavení recurring transakce <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo <MerchantRef>12345672 Suspend

4.3.9. Příklad: Obnovení recurring transakce <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo <MerchantRef>12345672 Resume

4.3.10. Příklad: Zrušení recurring transakce <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas ../../Xtra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>123456 <UserName>xmluser <Password>heslo <MerchantRef>12345672 Cancel

e-commerce – Integrace do systému obchodního partnera

33

4.4 XML ODPOVĚĎ (XML RESPONSE) Systém ProxyPay vrací na každý zaslaný XML dotaz odpovídající XML odpověď. Struktura a obsah této odpovědi je závislý na původním dotazu - pro různé dotazy existují různé XML odpovědi, které se liší jak strukturou elementů, tak jejich hodnotami. Seznam jednotlivých zapouzdřujících elementů v dotazu a odpovídajících elementů v odpovědi je uveden v následující tabulce: ZAPOUZDŘUJÍCÍ ELEMENT DOTAZU

ZAPOUZDŘUJÍCÍ ELEMENT ODPOVĚDI

<SaleRequest>

<SaleResponse>





























N/A

<ErrorMessage>

<ErrorMessage> je specifická odpověď odeslaná ProxyPay v případě, že dojde k chybě, která není asociována s konkrétním XML požadavkem. Příkladem může být odmítnutí XML požadavku z důvodu nesprávné struktury zprávy nebo kvůli zadání špatných přihlašovacích údajů XML uživatele.

XML ELEMENT

SALE

AUTHORISATION

CAPTURA

CANCEL

REFUND

STATUS

LAST TRX

RECURRING

ERROR

Seznam elementů a jejich výskyt v jednotlivých typech odpovědi:

Zapouzdřující element odpovědi (viz výpis v předchozí tabulce)

M

M

M

M

M

M

M

M

M

MerchantRef

M

M

M

M

M

M

M

ServerRef

M

M

M

M

M

M

M

SubReference

M

M

M

M

M

M

M

e-commerce – Integrace do systému obchodního partnera

34

AUTHORISATION

CAPTURA

CANCEL

REFUND

STATUS

RECURRING

ERROR

M

M

M

M

M

M

M

M

Description

O

O

O

O

O

O

O

M

AuthCode

M

M

TransactionStatus

M

TransactionStatusDesc

M

LAST TRX

SALE

ErrorCode

XML ELEMENT

TransactionList

M

Transaction

M

MerchantRef

M

ServerRef

M

SubReference

M

TransactionDate

M

PurchaseAmount

M

AuthAmount

M

CaptureAmount

M

Currency

M

MerchantDesc

M

TransactionStatus

M

TransactionStatusDesc

M

M – povinný element, O – nepovinný element, prázdné – element je vynechán

e-commerce – Integrace do systému obchodního partnera

35

Definice jednotlivých elementů a jejich datových typů:

XML ELEMENT

TYP

POPIS

MerchantRef

AN 1-12

unikátní referenční číslo transakce

ServerRef

N 1-12

číslo transakce přidělené systémem ProxyPay

SubReference *

N 1-3

sub-referenční číslo transakce

ErrorCode **

N 1-8

číselná hodnota označující typ chyby

Description ***

AN 1-512

textový popis chyby

AuthCode

AN 1-6

autorizační kód přidělený autoriz. systémem ČS

TransactionStatus

N 1-7

kód aktuálního stavu transakce

TransactionStatusDesc

AN 1-512

textový popis aktuálního stavu transakce

TransactionDate

Date string

datum tr. (příklad: 2012-10-30T12:45:56+0100)

PurchaseAmount

N 1-11

částka transakce v haléřích

AuthAmount

N 1-11

autorizovaná částka v haléřích

CaptureAmount

N 1-11

stržená částka v haléřích

Currency

A3

textový kód měny – {CZK|EUR|GBP|USD}

MerchantDesc

AN 1-1024

textový popis objednávky zvolený obchodníkem

* číslo dceřinné transakce – viz kapitola 5.2. ** pokud je ErrorCode = 0, akce proběhla úspěšně *** popis chyby (Description) je obsažen pouze v případě, že ErrorCode > 0

Významy jednotlivých kódů v a popisů stavu v jsou uvedeny v kapitole 4.5

e-commerce – Integrace do systému obchodního partnera

36

4.4.1. Příklad SaleResponse – neúspěšná transakce <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <SaleResponse> <MerchantRef>110161408 <ServerRef>22892 <SubReference>0 <ErrorCode>4096 Bad card.

4.4.2. Příklad AuthorisationResponse – úspěšná předautorizace <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <MerchantRef>110161408 <ServerRef>20727 <SubReference>0 <ErrorCode>0 1922512

4.4.3. Příklad TransactionStatusResponse <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> 8192 OK <MerchantRef> <ServerRef>1023250 <SubReference>0 <ErrorCode>0

e-commerce – Integrace do systému obchodního partnera

37

4.4.4. Příklad LastTransactionsResponse <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <ServerRef>1023630 <MerchantRef>3320688606 <Subreference>0 2012-02-03T14:24:03+0100 10 10 0 EUR <MerchantDesc>Description for order 3320688606 8192 OK <ServerRef>1023620 <MerchantRef>3320687909 <Subreference>0 2012-02-03T14:22:56+0100 10 0 0 EUR <MerchantDesc>Description for order 3320687909 4096 Failed <ServerRef>1023600 <MerchantRef>3320515812 <Subreference>0 2012-02-02T19:12:53+0100 10 0 0 EUR <MerchantDesc>Description for order 3320515812 1048576 Pending Authentication <ServerRef>1023590 <MerchantRef>3320515812 <Subreference>0 2012-02-02T19:12:10+0100 10 0 0 EUR <MerchantDesc>Description for order 3320515812 1 Initiated

e-commerce – Integrace do systému obchodního partnera

38

4.4.5. Příklad RecurringOperationResponse – úspěšná akce <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <MerchantRef>12345672 <ServerRef>23350 <SubReference>0 <ErrorCode>0

4.4.6. Příklad ErrorMessage – nesprávné přihlašovací údaje <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <ErrorMessage> <ErrorCode>00000015 Bad user or password

4.5 SEZNAM MOŽNÝCH STAVŮ TRANSAKCE V následující tabulce jsou uvedeny možné hodnoty elementů (kódy stavu) a (popisy stavu): ČÍSELNÝ KÓD STAVU

POPIS STAVU

0

unknown

1

Initiated

2

Initiated

4

OneTimePayment

6

Redirection To ProxyPay2

8

Send Payment

16

Data Gathered

32

AfterAuth

e-commerce – Integrace do systému obchodního partnera

39

ČÍSELNÝ KÓD STAVU

POPIS STAVU

64

Validation

128

Pending

256

Confirmation Post

512

Technical Reversal

4096

Failed

8192

OK

65536

Split

131072

Partial

1048576

Pending Authentication

2097152

Failed Authentication

4194304

Refused Authorisation

4.6 ČÍSLOVÁNÍ SUBREFERENCE Hodnota elementu <SubReference> představuje pořadové číslo dceřinné transakce v ProxyPay. Dceřinná transakce je transakce odvozená od původní transakce typu prodej (sale) nebo předautorizace (authorisation). Číslo (merchantref) této transakce je tvořeno merchantref původní transakce a pořadovým číslem odděleným lomítkem („/001“, „/002“, „/003“ atd.). Hodnota elementu <SubReference> značí číslo za lomítkem, tedy 001, 002, 003 atd.

ProxyPay dceřinné transakce vytváří automaticky, a to ve dvou případech: 1 - při refundaci (i částečné) (RefundRequest) – pro každou (i částečnou) refundaci k původní transakci je vytvořena dceřinná transakce s unikátním pořadovým číslem. Dceřinné transakce jsou číslovány chronologicky v pořadí „/001“, „/002“, „/003“ atd. 2 - při částečném dokončení předautorizace (CaptureRequest) – pro každé částečné dokončení předautorizace k původní transakci je vytvořena dceřinná transakce s unikátním pořadovým číslem. Dceřinné transakce jsou číslovány chronologicky v pořadí „/001“, „/002“, „/003“ atd.

V případě, že na jednu původní transakci jsou navázány jak refundace, tak částečná dokončení předautorizace, číslování je pro refundaci i dokončení společné a probíhá taktéž chronologicky.

e-commerce – Integrace do systému obchodního partnera

40

Příklady použití: Následující scénáře slouží jako příklady způsobu vytváření a číslování dceřinných transakcí. Pro názornost uvažujme, že byla provedena transakce v režimu předautorizace na 10 Kč.

1. Transakce byla dokončena (CaptureRequest) na celou částku, tedy 10 Kč. Dceřinná transakce se nevytváří. Následně byla provedena refundace (RefundRequest) na stejnou částku 10 Kč. V ProxyPay se vytvoří dceřinná transakce pro refundaci s merchantref 123456/001.

2. Transakce byla stejně jako v předchozím případě dokončena na 10 Kč. Dceřinná transakce se nevytváří. Následně byly provedeny dvě refundace na 3 Kč a 5 Kč (v tomto pořadí). V ProxyPay se vytvoří dvě dceřinné transakce pro obě refundace s merchantref 123456/001 (3 Kč) a 123456/002 (5 Kč).

3. Transakce byla částečně dokončena na 8 Kč. V ProxyPay se vytvoří dceřinná transakce pro částečné dokončení s merchantref 123456/001. Následně byla provedena refundace na 5 Kč. V ProxyPay se vytvoří dceřinná transakce pro refundaci s merchantref 123456/002. Na závěr byla dokončena autorizace na zbývající 2 Kč. V ProxyPay se vytvoří další dceřinná transakce pro částečné dokončení s merchantref 123456/003.

e-commerce – Integrace do systému obchodního partnera

41

5. ONE CLICK PAYMENTS (OCP) - VOLITELNÉ Toto řešení má za cíl poskytnout obchodním partnerům a jejich klientům službu umožňující rychlou on-line platbu bez nutnosti zobrazovat držiteli karty platební bránu při každé platbě. Z pohledu držitele karty tak první transakce proběhne na platební bráně, další transakce však probíhají na pozadí. Průběh je následující: Při první platbě se zobrazí držiteli karty klasická platební brána. Pokud je PRVNÍ PLATBA

platební karta zabezpečena 3-D Secure, je transakce provedena včetně ověření 3-D Secure u vydavatelské banky. Každá další platba držitele karty ve Vašem eshopu proběhne bez zobrazení

DALŠÍ PLATBY

platební karty. Transakce je z Vaší strany iniciována přes XML dotaz. Na dotaz obdržíte po autorizaci XML odpověď s výsledkem transakce.

5.1. PRVNÍ TRANSAKCE Zapnutí funkce OCP u první (iniciační) transakce klienta provedete přidáním následujícího parametru do New Payment POSTu:

Validační post iniciační transakce obsahuje následně nové pole: NÁZEV PARAMETRU Ocpflag

TYP String

POŽADOVÁNA VALIDACE ANO

POPIS Příznak OCP transakce

Konfirmační post iniciační transakce je doplněn rovněž o další pole: NÁZEV PARAMETRU

TYP

POŽADOVÁNA KONFIRMACE

POPIS

ocpvaliddate

String

ANO

Expirace platební karty

ocp

Number

ANO

Příznak pro registraci OCP iniciační transakce

U rejection post nedochází k žádné změně.

e-commerce – Integrace do systému obchodního partnera

42

5.2. DALŠÍ TRANSAKCE Pro další transakce klienta je použito již XML rozhraní a to skrze následující zprávy: SubsequentOCPRequest

Vámi odeslaný požadavek na provedení následné OCP platby

SubsequentOCPResponse

Bankou zaslaná odpověď na přijatý požadavek na provedení následné OCP platby.

CancelOCPRequest

Vámi odeslaný požadavek na zrušení dalších OCP plateb pro danou iniciační transakci.

CancelOCPResponse

Bankou zaslaná odpověď na požadavek na zrušení dalších OCP plateb pro danou iniciační transakci.

Příklad SubsequentOCPRequest: <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas file://c:/opt/jboss_posmpi/server/pp3m_mpi/extra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <SubsequentOCPRequest> <MerchantID>222 <UserName>name <Password>Pass 100 <MerchantRef>860271196 203 [email protected] CZ <MOTO>0 819887505

Příklad SubsequentOCPResponse: <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <SubsequentOCPResponse> <MerchantRef>860271196 <ServerRef>1156260

e-commerce – Integrace do systému obchodního partnera

43

<SubReference>2 <ErrorCode>0 308467

Příklad CancelOCPRequest: <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas file://c:/opt/jboss_posmpi/server/pp3m_mpi/extra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678"> <MerchantID>222 <UserName>name <Password>Pass <MerchantRef>819887505 <ServerRef>0

Příklad CancelOCPResponse: <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> <MerchantRef>819887505 <ServerRef>1156260 <SubReference>0 <ErrorCode>0

5.3. NASTAVENÍ ZABEZPEČENÍ PRO OCP Pro OCP je možno využít pro komunikaci klientský certifikát kvůli vyššímu zabezpečení XML transakcí. Pro aktivaci této funkce kontaktujte podporu e-commerce.

e-commerce – Integrace do systému obchodního partnera

44

5.4. CHYBOVÉ HLÁŠKY OCP Funkce OCP přináší nové chybové hlášky, které se mohou objevit např. v Rejection POSTu: KÓD CHYBY

ZPRÁVA

POPIS

56001

OCP flag must contain value ‘1’

Chybná hodnota v parametru “ocp”.

56002

OCP transaction must be sale type

OCP transakce musí být typu PRODEJ (transactiontype=”sale”).

56003

OCP is not enabled

OCP funkce není povolena pro dané MerchantID.

56004

Referenced transaction is not OCP registration

Iniciační transakce, na kterou se odkazuje tato transakce, není typu OCP.

56005

OCP registration transaction is invalidated.

Iniciační (první) OCP transakce byla zrušena.

56006

Referenced transaction not found.

Iniciační (první) transakce nebyla nalezena.

39401

Client certificate was not sent.

Klientský certifikát nebyl použit pro SSL připojení k XML rozhraní.

39402

Untrusted client certificate was received.

Certifikační autorita, která podepsala klientský certifikát není přítomna v seznamu důvěryhodných certifikačních autorit.

39403

Client certificate verification was unsuccessful.

Ověření klientského certifikátu neproběhlo úspěšně.

Client certificate is invalid for merchant.

Subjectname certifikátu nebo jeho alternativní názvy nesouhlasí s regexem definovaným ve Vašem nastavení v ČS.

39404

5.5. DALŠÍ XML DOTAZY PRO OCP Aktuální XML rozhraní v případě OCP plateb se rozšiřuje o další funkce, které lze využít. Pokud je OCP parametr zaslán v XML dotazu, v XML odpovědi je obsažen nový OCP parameter OCPValidDate. Dotčené XML funkce jsou TransactionStatusRequest a TransactionStatusResponse. Příklad TransactionStatusRequest u OCP: <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.element.be/schemas file://c:/opt/jboss_posmpi/server/pp3m_mpi/extra/xsd/ele-envelope.xsd" version="1.00.000" messageId="12345678">

e-commerce – Integrace do systému obchodního partnera

45

<MerchantID>222 <UserName>name <Password>Pass <MerchantRef>822108072 <ServerRef>0 <Subreference>0 1

Příklad TransactionStatusResponse u OCP: <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageId="12345678"> 8192 OK SALE <MerchantRef>822108072 <ServerRef>1156300 <SubReference>0 <ErrorCode>0 20141231

e-commerce – Integrace do systému obchodního partnera

46

6. EMAILOVÉ ŠABLONY (VOLITELNÉ) Systém ProxyPay umožňuje po úspěšném provedení transakce zasílání potvrzovacích emailů Vám i držiteli karty. E-maily jsou zasílány na adresu uvedenou v registračním formuláři v poli „Notification E-mail“, držiteli karty jsou zasílány na adresu uvedenou v proměnné „emailcustomer“, která je součástí inicializačního POST formuláře. Tyto e-maily jsou generovány po každé úspěšně provedené transakci a jsou kombinací statického textu a níže popsaných zástupců. Šablony lze upravit podle potřeb obchodního partnera, stačí je zaslat ve dvou *.txt souborech (jeden pro předmět, druhý pro tělo zprávy) technické osobě ČS.

Seznam zástupců, které lze pro potvrzovací e-maily použít: ##@@##%%MERCHANTREF%%

##@@##%%COMPANY%%

##@@##%%FIRSTNAME%%

##@@##%%LASTNAME%%

##@@##%%MERCHANTID%%

##@@##%%SHOPNAME%%

##@@##%%PASSWORD%%

##@@##%%AMOUNTCENTS%%

##@@##%%SERVERREF%%

##@@##%%CURRENCYCODE%%

##@@##%%REALAMOUNT%%

##@@##%%LANGUAGE%%

##@@##%%CURRENCYSYMBOL%%

##@@##%%REFERRER%%

##@@##%%VAR3%%

##@@##%%MERCHANTDESC%%

##@@##%%VAR1%%

##@@##%%VAR4%%

##@@##%%PAYMENTMETHOD%%

##@@##%%VAR2%%

##@@##%%VAR5%%

##@@##%%VAR6%%

##@@##%%VAR7%%

##@@##%%VAR8%%

##@@##%%VAR9%%

##@@##%%IP%%

##@@##%%USERAGENT%%

##@@##%%DATETIME%%

##@@##%%BRAND%%

6.1 EMAIL PRO OBCHODNÍHO PARTNERA Systém České spořitelny po úspěšné transakci vygeneruje potvrzovací email, který odešle na emailovou adresu, kterou jste si zvolil při registraci. Nedoporučujeme, abyste obdržení emailu považovali za potvrzení úspěšnosti transakce bez další kontroly. E-mail může být podvržený a tak jej nelze chápat jako stoprocentní potvrzení úspěšné transakce ze strany banky. Má pouze informativní charakter.

ČESKÁ VERZE PŘEDMĚT: Nova transakce c. ##@@##%%MERCHANTREF%% - Online Platebni System Ceske Sporitelny a.s.

e-commerce – Integrace do systému obchodního partnera

47

TĚLO ZPRÁVY: Byla zrealizovana nova transakce na Online Platebnim Systemu Ceske Sporitelny a.s. Udaje o transakci: Cislo transakce: ##@@##%%MERCHANTREF%% Castka: ##@@##%%REALAMOUNT%% ##@@##%%CURRENCYSYMBOL%% Datum a cas transakce: ##@@##%%DATETIME%% Typ platebni karty: ##@@##%%BRAND%% Udaje o obchodu: Nazev obchodu: ##@@##%%SHOPNAME%% Spolecnost: ##@@##%%COMPANY%% ID obchodnika: ##@@##%%MERCHANTID%% Udaje o objednavce: Popis objednavky: ##@@##%%MERCHANTDESC%% Dalsi informace o objednavce: Var1=##@@##%%VAR1%% Var2=##@@##%%VAR2%% Var3=##@@##%%VAR3%% Var4=##@@##%%VAR4%% Var5=##@@##%%VAR5%% Var6=##@@##%%VAR6%% Var7=##@@##%%VAR7%% Var8=##@@##%%VAR8%% Var9=##@@##%%VAR9%%

Udaje o drziteli karty: Browser: ##@@##%%USERAGENT%% jazyk: ##@@##%%LANGUAGE%%

PROSIM NEODPOVIDEJTE NA TENTO EMAIL, JE AUTOMATICKY GENEROVAN PLATEBNI BRANOU CS. PRO KOMUNIKACI S BANKOU POUZIJTE EMAIL: [email protected]

6.2 EMAIL PRO DRŽITELE KARTY Stejně jako Vám, i držiteli karty mohou být zaslány potvrzovací emaily s údaji o provedené transakci. Předpokladem odeslání je, že v NewPaymentPost obdržíme jeho emailovou adresu.

ČESKÁ VERZE PŘEDMĚT: Vase objednavka c.##@@##%%MERCHANTREF%% v obchode: ##@@##%%SHOPNAME%%, datum: ##@@##%%DATETIME%%

e-commerce – Integrace do systému obchodního partnera

48

TĚLO ZPRÁVY: POTVRZENI Vazena pani, vazeny pane, potvrzujeme, ze jste provedl/a transakci v obchode ##@@##%%SHOPNAME%%. Udaje o transakci: Cislo transakce: ##@@##%%MERCHANTREF%% Castka: ##@@##%%REALAMOUNT%% ##@@##%%CURRENCYSYMBOL%% Datum a cas transakce: ##@@##%%DATETIME%% Platebni karta: ##@@##%%BRAND%% Popis transakce: ##@@##%%MERCHANTDESC%%

Udaje o obchodu: Nazev obchodnika: ##@@##%%COMPANY%% ID obchodnika: ##@@##%%MERCHANTID%% Udaje o drziteli karty: Browser: ##@@##%%USERAGENT%% Jazyk: ##@@##%%LANGUAGE%% PROSIM NEODPOVIDEJTE NA TENTO EMAIL, JE AUTOMATICKY GENEROVAN PLATEBNI BRANOU CS. PRO KOMUNIKACI S BANKOU POUZIJTE EMAIL: [email protected]

ANGLICKÁ VERZE PŘEDMĚT: Your order ##@@##%%MERCHANTREF%% in ##@@##%%SHOPNAME%% shop, date: ##@@##%%DATETIME%%

TĚLO ZPRÁVY: CONFIRMATION Dear customer, this is to confirm your transaction in ##@@##%%SHOPNAME%% shop.

Transaction details: Transaction ID: ##@@##%%MERCHANTREF%% Amount: ##@@##%%REALAMOUNT%% ##@@##%%CURRENCYSYMBOL%% Transaction date and time: ##@@##%%DATETIME%% Payment Card Brand: ##@@##%%BRAND%% Description: ##@@##%%MERCHANTDESC%%

e-commerce – Integrace do systému obchodního partnera

49

Merchant details: Merchant name: ##@@##%%COMPANY%% Merchant ID: ##@@##%%MERCHANTID%%

Customer system detail: Browser: ##@@##%%USERAGENT%% Language: ##@@##%%LANGUAGE%% PLEASE DO NOT REPLY TO THIS EMAIL. IT IS GENERATED AUTOMATICALLY BY THE CS PAYMENT GATEWAY. TO GET IN TOUCH WITH THE BANK, USE THE FOLLOWING ADDRESS: [email protected]

NĚMECKÁ VERZE PŘEDMĚT: Ihre Bestellung Nr. ##@@##%%MERCHANTREF%% im ##@@##%%SHOPNAME%% Geschaft, Datum: ##@@##%%DATETIME%%

TĚLO ZPRÁVY: BESTATIGUNG Sehr geehrte Frau, sehr geehrter Herr, wir bestatigen die Transaktion im ##@@##%%SHOPNAME%% Geschaft. Angaben zur Transaktion: ---------------------------------------Transaktion Nr.: ##@@##%%MERCHANTREF%% Betrag: ##@@##%%REALAMOUNT%% ##@@##%%CURRENCYSYMBOL%% Datum und Uhrzeit der Transaktion: ##@@##%%DATETIME%% Zahlungskarte: ##@@##%%BRAND%% Beschreibung der Transaktion: ##@@##%%MERCHANTDESC%% Angaben zum Geschaft: ---------------------------------------Handler: ##@@##%%COMPANY%% ID des Handlers: ##@@##%%MERCHANTID%% Angaben zum Karteninhaber: ---------------------------------------Browser: ##@@##%%USERAGENT%% Sprache: ##@@##%%LANGUAGE%% Fur eventuelle Reklamation bitte aufheben. Online-Zahlungssystem von Ceska Sporitelna a.s.

7. e-commerce – Integrace do systému obchodního partnera

50

7. MERCHANT BACKOFFICE Rozhraní Merchant Back Office slouží k prohlížení transakcí v reálném čase (status a detaily transakce), správě transakcí - zrušení, refundace (i částečná), realizace předautorizací (i částečná) a prohlížení a správě účetních dávek. Přístup do webového rozhraní Merchant Back Office naleznete na adrese: https://3dsecure.csas.cz/merchant

Pro přístup je vyžadováno číslo pokladny (MerchantID) a přístupové jméno a heslo, které obdržíte od technické osoby ČS na začátku integrace.

Při prvním přihlášení systém uživatele

automaticky vyzve ke změně hesla. Nové heslo pak musí být délkou mezi 8 a 15 znaky včetně a musí obsahovat alespoň jeden nealfanumerický znak (čárku, tečku apod.). Po třech neúspěšných pokusech o přihlášení bude účet automaticky zablokován. Odblokování může provést technická osoba ČS.

TIP: POTŘEBUJETE POMOC?

PASS

Merchant BackOffice

Nezapomeňte si vyžádat detailní příručku k rozhraní Merchant BackOffice. Rádi Vám je na požádání poskytneme!

Změna hesla

Pro změnu hesla, odblokování účtu a podobně se obraťte na HelpDesk ČS (tel.: 220 874 625, 724 172 301) nebo na podporu e-commerce.

e-commerce – Integrace do systému obchodního partnera

51

8. ZABEZPEČENÍ Banka předpokládá, že vyhovíte bezpečnostním požadavkům uvedeným ve smluvním vztahu a zajistíte, aby bylo Vaše řešení odolné vůči útokům typu Cross-Site Scripting (XSS), SQL Injection a podobně. Zejména je nutné zajistit kontrolu vstupních polí (například při registraci zákazníka nebo zadávání údajů o objednávce) tak, aby případný útočník nemohl do těchto polí vložit vlastní kód, který by způsobil napadení aplikace. Zamezíte tak špatnému renomé a především hmotným škodám jak na Vaší straně, tak na straně banky.

8.1

PREVENCE PROTI CROSS-SITE SCRIPTING

Zde najdete příklady, jak lze ošetřit vstupní pole a zabránit tak možným XSS útokům: Kontrola délky vstupu: final static int maxLength = 8; final String input = request.getParametr(“input”); if (input.length() > maxLength) { /* neplatná délka vstupu – zobraz upozornění */ }

Kontrola formátu vstupu (číslo, text, e-mailová adresa atd.): final String input = request.getParameter(“input”); final String numericPattern = “^\\d+$”; if (!input.matches(numericPattern)) { /* vstup není číselný – zobraz upozornění */ }

Nahrazení speciálních znaků (<,>,{,} atd.): final String filterPattern = “[<>{}\\[\\];\\&]”; String input = s.replaceAll(filterPattern, “ ”);

8.2 PREVENCE PROTI SQL INJECTION Při útoku typu SQL Injection se útočník pokouší odeslat prostřednictvím některého z formulářových polí do aplikace kód, který vygeneruje jím požadovaný SQL dotaz.

e-commerce – Integrace do systému obchodního partnera

52

Následuje jednoduchý příklad takového útoku: Proměnná idZakaznika je jednoznačný identifikátor zákazníka v systému obchodního partnera. Způsob obsloužení této proměnné je následující: final String idZakaznika = httpRequest.getParameter(“idZakaznika”); final String sql = “SELECT * FROM zakaznici WHERE idzakaznika =‘” + idZakaznika +“’” Do této proměnné vloží útočník následující řetězec: zak123’ or 1=1 -Vzniklý vstup potom ve výsledku vygeneruje následující dotaz... SELECT * FROM zakaznici WHERE idzakaznika=‘zak123’ or 1=1 --’ ...který vypíše všechny důvěrné záznamy z tabulky „zakaznici“, protože 1=1 je vždy pravda. Ještě závažnějším je případ, kdy se útočníkovi podaří změnit data v databázi: zak123’; drop table zakaznici --

Obranou proti těmto útokům je: •

Nastavení oprávnění na úrovni databáze (operace, které nepotřebují zapisovat by měly mít pouze práva na čtení)

•

Využití Prepared Statements, které provádějí kontrolu typů (nedovolí vložit číslo tam, kde je očekáván text) a ruší význam speciálních znaků

Příklad využití Prepared Statements: final String sql = “SELECT * FROM zakaznici WHERE idZakaznika=?”; final PreparedStatement ps = connection.prepareStatement(sql); ps.setString(1, idZakaznika); Při pokusu o stejný útok jako v přechozím případě (vložení řetězce „zak123‘ or 1=1 --“) by tentokrát vznikl následující dotaz: final String sql = “SELECT * FROM zakaznici where idZakaznika=‘zak123’ or 1=1 --” Pak by byl celý vstup „zak123’ or 1=1 --“ kontrolován proti hodnotám ve sloupci idZakaznika.

e-commerce – Integrace do systému obchodního partnera

53

9. NEJČASTĚJŠÍ DOTAZY Q:

V registračním formuláři e-commerce je možné u jednotlivých adres zadat URL adresu jak s http://, tak https://. Je nutné zadat obě verze?

A:

Je nutné si vybrat právě jednu z nich. Validation, confirmation a rejection skripty musí být umístěny na HTTPS, u ostatních adres je to nepovinné.

Q:

Je nutné mít stránky e-shopu zabezpečené SSL certifikátem? Musí být tento certifikát vydán certifikační autoritou?

A:

Validation, Confirmation a Rejection skripty musí být umístěny na https://, na webu proto musí být uložen serverový SSL certifikát. Ostatní URL mohou být umístěny na http://, doporučujeme ale užít také https://, aby se zákazníkům při placení nezobrazovalo upozornění o přechodu ze zabezpečené části webu na nezabezpečenou (při přesměrování na OK/NOK URL). Certifikát nemusí být potvrzený certifikační autoritou, připouštíme užití vlastních certifikátů. Certifikát musí být vydaný pro tu konkrétní doménu a délka jeho klíče nesmí překročit 4096 bitů.

Q:

Je možné využít u URL vlastní porty?

A:

Ano.

Q:

Je možné do URL přidávat vlastní GET parametry?

A:

Pouze v případě referreru (Shop URL). Ostatní adresy nesmí obsahovat vlastní parametry přidané GET metodou (např. https://www.xy.cz/?validace=1).

Q:

K čemu slouží Confirmation POST Password? Kdo ho generuje?

A:

Confirmation POST Password, neboli potvrzovací heslo, je jedním ze zabezpečujících prvků při provádění transakce. Posílá se pro zvýšenou kontrolu společně s ostatními parametry na Validation, Confirmation a Rejection skripty. Toto heslo si před začátkem integrace vygeneruje obchodní partner a vyplní ho do Registračního formuláře E-Commerce.

Q:

Jak postupovat při přesunu e-shopu na jinou doménu nebo při změně struktury URL adres?

A:

Veškeré změny adres uvedených ve formuláři (referrer, val., conf., OK a NOK) je třeba zanést do systému ProxyPay. Obchodní partner zašle novou podobu adres technickému kontaktu ČS, který adresy podle potřeby upraví. V případě změny domény u validation a confirmation skriptů je nutné počítat s přibližně dvoudenním zpožděním.

e-commerce – Integrace do systému obchodního partnera

54

Q:

Je možné otestovat platby před spuštěním e-shopu? Za jak dlouho je možné spustit ostrý provoz přijímání platebních karet?

A:

Ano, obchodnímu partnerovi jsou před spuštěním poskytnuty údaje o čtyřech virtuálních testovacích platebních kartách a je mu zpřístupněn testovací režim. Pokud je ze strany obchodního partnera vše připraveno podle této příručky, je možné spustit ostrý provoz do týdne od dodání veškerých materiálů.

Q:

Lze měnit podobu notifikačních e-mailů?

A:

Ano, pomocí textových šablon (viz kapitolu 5). Pro změnu e-mailových šablon je nutné je předat integrátorovi systému ProxyPay, a to ve dvou *.txt souborech – jeden pro předmět emailu a druhý pro tělo emailu. Pokud si obchodní partner nenadefinuje vlastní šablony, použijí se defaultní systémové.

Q:

Lze měnit jazyk platební brány?

A:

Ano, pomocí proměnné „language“. Tato proměnná je součástí inicializačního POST formuláře a musí být povinně vyplněná. Přikazuje systému, jakou jazykovou podobu brány má zobrazit a jakou jazykovou šablonu má použít pro oznamovací e-mail pro držitele karty. Proměnná může mít hodnoty CZ (čeština), DE (němčina), EN (angličtina), SK (slovenština), RU (ruština), ES (španělština), PT (portugalština) a UA (ukrajinština)

Q:

V rozhraní Back Office jsou tlačítka pro práci s transakcemi neaktivní, přestože mám ke zpracování oprávnění. Kde je chyba?

A:

Pro práci s transakcemi je třeba se v menu vlevo nahoře přepnout do režimu zpracování transakcí (transactions – process). Pak budou tlačítka aktivní.

Q:

Lze testování platební brány provést i v případě, že e-shop je stále ve fázi vývoje a není veřejně přístupný?

A:

Ano, stačí povolit přístup na e-shop z několika IP adres tak, aby mohla probíhat komunikace se systémem ProxyPay. Adresy na požádání zašle technická osoba ČS.

e-commerce – Integrace do systému obchodního partnera

55

PŘÍLOHY Příloha A – povolené znaky pro proměnnou cardholderID

Dec

Hex

Znak

Dec

Hex

Znak

33

21

!

80

50

P

34

22

"

81

51

Q

35

23

#

82

52

R

36

24

$

83

53

S

37

25

%

84

54

T

38

26

&

85

55

U

39

27

'

86

56

V

40

28

(

87

57

W

41

29

)

88

58

X

42

2a

*

89

59

Y

43

2b

+

90

5a

Z

44

2c

,

91

5b

[

45

2d

-

92

5c

\

46

2e

.

93

5d

]

47

2f

/

94

5e

^

48

30

0

95

5f

_

49

31

1

96

60

`

50

32

2

97

61

a

51

33

3

98

62

b

52

34

4

99

63

c

53

35

5

100

64

d

54

36

6

101

65

e

55

37

7

102

66

f

56

38

8

103

67

g

57

39

9

104

68

h

58

3a

:

105

69

i

59

3b

;

106

6a

j

60

3c

<

107

6b

k

61

3d

=

108

6c

l

62

3e

>

109

6d

m

63

3f

?

110

6e

n

64

40

@

111

6f

o

e-commerce – Integrace do systému obchodního partnera

56

65

41

A

112

70

p

66

42

B

113

71

q

67

43

C

114

72

r

68

44

D

115

73

s

69

45

E

116

74

t

70

46

F

117

75

u

71

47

G

118

76

v

72

48

H

119

77

w

73

49

I

120

78

x

74

4a

J

121

79

y

75

4b

K

122

7a

z

76

4c

L

123

7b

{

77

4d

M

124

7c

|

78

4e

N

125

7d

}

79

4f

O

126

7e

~

e-commerce – Integrace do systému obchodního partnera

57

Příloha B - podporované certifikáty ALGORITMUS

DSA

RSA

DÉLKA

KOMUNIKACE MEZI SYSTÉMY

KOMUNIKACE ZÁKAZNÍKA PŘES PROHLÍŽEČ (IE, Firefox)

1024

OK

OK

2048

OK

NEFUNGUJE

4096

OK

NEFUNGUJE

1024

OK

OK

2048

OK

OK

4096

OK

OK

e-commerce – Integrace do systému obchodního partnera

58

Příloha C – Text určený pro web obchodního partnera Platba kartou na název Vaší společnosti se vyplatí! •

na rozdíl od dobírky je platba kartou bez poplatku

•

v okamžiku přebírání zboží u sebe nemusíte mít hotovost ani kartu

•

úspěšnost platby se dozvíme okamžitě po zaplacení, není třeba čekat na připsání na účet

•

bezpečný, pohodlný a rychlý způsob nakupování

Jak je řešeno zabezpečení? •

údaje ze své platební karty zadáváte přímo na zabezpečeném webu České spořitelny

•

veškeré operace s kartou probíhají mimo naše systémy, přístup k Vašim citlivým karetním údajům má pouze Česká spořitelna a Vaše banka

•

přenosy dat při platbě jsou vždy šifrovány protokolem HTTPS

•

podporujeme nejmodernější řešení 3-D Secure, které Vám zaručí nadstandardní úroveň zabezpečení

Informujte se u své banky, zda Vaše karta podporuje 3-D Secure. Pokud ano, budete po zadání karty na platební bráně ČS přesměrováni ještě na web Vaší banky, kde vložíte své 3-D Secure heslo.

Jaké karty přijímáme? Platební brána akceptuje karty typu VISA, VISA Electron, MasterCard a Maestro. Ne všechny vydávané karty mají povolené online transakce. Pokud si nejste jisti, obraťte se na svou banku s dotazem, zda Vaše karta umožňuje platby online.

Jak u nás zaplatíte? Při vytváření objednávky vyberte v nákupním košíku platbu kartou online. Po dokončení objednávky dojde k přesměrování na platební bránu ČS, která zobrazí rekapitulaci platby (částka, popis objednávky) a vyzve Vás k zadání karetních údajů: •

číslo karty (PAN)

•

expirace karty (měsíc/rok)

•

CVV2/CVC2 kód karty (tento 3místný kód najdete na zadní straně karty, většinou vedle podpisového proužku)

Po zadání jsou tyto karetní údaje přeneseny na pozadí do Vaší banky, která ověří možnost provést platbu (zkontroluje dostatečný zůstatek na Vašem účtě, platnost karty atd.). Pokud je vše v pořádku, ČS provede autorizaci transakce a do našich systémů odešle potvrzení o úspěšnosti platby. Po autorizaci platby se na platební bráně zobrazí potvrzující hláška a dojde k přesměrování zpět na naše stránky. O výsledku transakce budete informováni také e-mailem. e-commerce – Integrace do systému obchodního partnera

59

Platba byla zamítnuta, co dál? Důvodů k zamítnutí platby může být několik, zde uvádíme ty nejčastější: •

karetní údaje nebyly vyplněny správně

•

číslo karty nesedí k vybranému typu karty

•

platnost Vaší karty vypršela

•

máte nedostatečný zůstatek na účtě

•

došlo k vyčerpání denního limitu nebo limitu pro platby online

•

bylo špatně zadáno 3-D Secure heslo

•

Vaše karta není určena pro platby online

Pokud máte pocit, že Vaše karta i účet jsou v pořádku a transakce byla přesto zamítnuta, kontaktujte nás.

e-commerce – Integrace do systému obchodního partnera

60

Příloha D – Informace pro registraci Pro zavedení e-shopu do systémů ČS po Vás bude obchodní zástupce vyžadovat následující údaje do registračního formuláře e-commerce. Tento formulář následně předáte obchodnímu zástupci ČS.

INFORMACE O SPOLEČNOSTI Název společnosti Adresa sídla společnosti

ulice, č.p., město, PSČ, stát

Kontakt na jednatele společnosti

jméno, telefon, fax, e-mail

IČ/DIČ

Vaše IČ/DIČ

Adresa oficiálního webu

INFORMACE O PROVOZOVNĚ Název provozovny Číslo provozovny (MerchantID) Adresa provozovny

pod tímto názvem bude e-shop zaveden do systémů ČS; většinou stejný jako název společnosti, případně adresa webu přidělí obchodní zástupce ČS po obdržení registračního formuláře ulice, č.p., město, PSČ, stát

Číslo bankovního účtu Provozní kontakty (obchodní, účetní, technický)

jméno, telefon, e-mail

TECHNICKÉ INFORMACE

E-mail Merchant Notification (aktivní/neaktivní)

adresa, ze které bude odcházet požadavek na platbu (inicializační POST formulář, viz kapitolu 2.2.). Referrer se nemusí shodovat se skutečnou adresou, ze které bude požadavek odcházet, ale skutečná adresa musí referrerem začínat. Referrerů může být v systému více, ale jejich celková délka je omezena na maximálních 2048 znaků. Příklad: pokud je referrer nastaven na http://www.xy.cz, bude systém přijímat platby z celé domény. Pokud je nastaven na http://www.xy.cz/platba/, bude přijímat platby z jakékoliv adresy, která začíná na http://www.xy.cz/platba/, ať už je za posledním lomítkem cokoliv v případě povolení budou obchodnímu partnerovi po každé úspěšné transakci zasílány oznamovací e-maily na uvedenou adresu (Notification E-Mail)

Notification E-mail

adresa pro zasílání oznamovacích e-mailů pro obchodního partnera

E-mail Customer Notification (aktivní/neaktivní)

v případě povolení budou zákazníkům po každé úspěšné transakci zasílány oznamovací e-maily na adresu uvedenou v proměnné „emailcustomer“ (viz kapitolu 2.2.)

Confirmation URL

adresa skriptu, který provádí konečné potvrzení transakce. Adresa nesmí obsahovat vlastní přidané GET parametry.

Shop URL (referrer)

e-commerce – Integrace do systému obchodního partnera

61

Skript musí být zabezpečený SSL certifikátem s délkou klíče maximálně 4096 bitů (lze použít i self-signed certifikát) a musí být umístěn na standardním portu (443). Confirmation POST Password

heslo zasílané s ostatními parametry pro kontrolu v Confirmation, Validation a Rejection skriptu

OK URL

na tuto adresu je zákazník přesměrován po úspěšném dokončení transakce. Měl by zde být informován, že jeho platba proběhla v pořádku. Adresa nesmí obsahovat vlastní přidané GET parametry. Zabezpečení certifikátem je nepovinné, ale stránka musí být umístěna na standardním portu (80 nebo 443).

NOK URL

na tuto adresu je zákazník přesměrován po neúspěšném pokusu o zaplacení. Měl by zde být informován, že jeho platba neproběhla. Adresa nesmí obsahovat vlastní přidané GET parametry. Zabezpečení certifikátem je nepovinné, ale stránka musí být umístěna na standardním portu (80 nebo 443).

Rejection URL

adresa skriptu, na který systém ProxyPay zašle informace o neúspěšné platbě, pokud dojde během zpracování k chybě. Adresa nesmí obsahovat vlastní přidané GET parametry. Skript musí být zabezpečený SSL certifikátem s délkou klíče maximálně 4096 bitů (lze použít i self-signed certifikát) a musí být umístěn na standardním portu (443).

Validation URL

adresa skriptu, který ověřuje platební údaje na začátku transakce. Adresa nesmí obsahovat vlastní přidané GET parametry. Skript musí být zabezpečený SSL certifikátem s délkou klíče maximálně 4096 bitů (lze použít i self-signed certifikát) a musí být umístěn na standardním portu (443).

OSTATNÍ INFORMACE Popis používaného serveru a prohlížečů pro přístup do Merchant Back Office

(nepovinné, nemusíte vyplňovat)

Jazyková verze Merchant BackOffice

Vyberte jazyk, pod kterým bude uživatel přistupovat Úroveň 1 – pouze prohlížení transakcí

Jména uživatelů s přístupem do MBO

Úroveň 2 – prohlížení a práce s MO/TO transakcemi Úroveň 3 – prohlížení a práce s veškerými transakcemi

Způsob, formát a frekvence zasílání avíz Adresa (fyzická, e-mailová) pro zasílání avíz Povolené typy karet Povolené typy transakcí Povolené měny Povolení akceptace zahraničních karet (karet vydaných mimo CZ/SK)

e-commerce – Integrace do systému obchodního partnera

62