ProxyPay 3/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 3.0 Richard Švec, Petr Štefko, Tomáš Novotný, Zbyšek Strnad 30.3.2006 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) 3.3 Ing. Radovan Bryx, Tomáš Žák» Rejection POST (kap. 4.5)» Zjišťování stavu transakce (kap. 7.2)» Proměnná brand nepovinná (kap 4.2) 13.6.2012» Změna max. délky certifikátu (Příloha B) 3.3.3 Ing. Radovan Bryx» Nové jazyky platební brány (kap. 4.2) 9.10.2013 4.0 Ing. Radovan Bryx» Texty pro internetové stránky(příloha C)» Oprava chyb 9.4.2014» Grafické úpravy (celý dokument) 4.1. Ing. Radovan Bryx» Doplnění odpovědí v XML (kap. 4.4)» Změna podporovaných portů (kap.8)» Nová pole OrderID1 a OrderID2 (kap.2) 3.10.2014 4.2. Ing. Radovan Bryx, Tomáš Žák» Nová funkce OneClickPayments (kap.5) 20.10.2014 e-commerce Integrace do systému obchodního partnera 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. DALŠÍ XML DOTAZY PRO OCP... 45 6. 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 Merchant BackOffice Název pro systém platební brány České spořitelny 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 POTŘEBNÉ ÚDAJE 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. 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 Váš systém odešle metodou POST formulář s informacemi o platbě a objednávce na adresu systému ProxyPay e-commerce Integrace do systému obchodního partnera 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: X <html><head></head><body>[ok]</body></html> 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: X <html><head></head><body>[ok]</body></html> 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

KROK Pokud v kterémkoliv bodě při zpracování transakce dojde k chybě, ProxyPay odešle Rejection POST na Vaši Rejection URL. 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á: <form NAME="MERCHANTFORM" method="post" action="https://3dsecure.csas.cz/transaction"> <INPUT TYPE="hidden" NAME="merchantid" VALUE="259999"> <INPUT TYPE="hidden" NAME="amount" VALUE="500"> <INPUT TYPE="hidden" NAME="currency" VALUE="203"> <INPUT TYPE="hidden" NAME="brand" VALUE="VISA" > <INPUT TYPE="hidden" NAME="transactiontype" VALUE="sale" > <INPUT TYPE="hidden" NAME="merchantref" VALUE="123456789" > <INPUT TYPE="hidden" NAME="merchantdesc" VALUE="Your Order 123456789"> <INPUT TYPE="hidden" NAME="extension_recurringfrequency" VALUE="28"> <INPUT TYPE="hidden" NAME="extension_recurringenddate" VALUE="20151231"> <INPUT TYPE="hidden" NAME="language" VALUE="EN"> <INPUT TYPE="hidden" NAME="emailcustomer" VALUE="cardholder@email.cz"> <INPUT TYPE="hidden" NAME="cardholderid" VALUE="cardholder12345"> <INPUT TYPE="hidden" NAME="orderid1" VALUE="F120152"> <INPUT TYPE="hidden" NAME="orderid2" VALUE="ABC123456789 > <INPUT TYPE= hidden NAME= merchantvar1 VALUE= ERPFunction1_12 > <INPUT TYPE= hidden NAME= merchantvar2 VALUE= ERPRef1_45 > <INPUT TYPE= hidden NAME= merchantvar3 > <INPUT TYPE= hidden NAME= var1 VALUE= Produkt ABC123 > <INPUT TYPE= hidden NAME= var2 > <INPUT TYPE= hidden NAME= var3 > <INPUT TYPE= hidden NAME= var4 > <INPUT TYPE= hidden NAME= var5 > <INPUT TYPE= hidden NAME= var6 > <INPUT TYPE= hidden NAME= var7 VALUE= Bubenska 1 > <INPUT TYPE= hidden NAME= var8 VALUE= 150 00 Praha 5 > <INPUT TYPE= hidden NAME= var9 VALUE= http://www.shop.cz > <INPUT TYPE=image SRC= button.gif BORDER=0 VALUE= SSL Alt= Zaplatit kartou > </form> e-commerce Integrace do systému obchodního partnera 10

Popis jednotlivých proměnných ve formuláři: Tabulka č.1: Proměnné v inicializaci platby NÁZEV POVINNÉ? POPIS MERCHANTID ANO Šestimístné unikátní identifikační číslo provozovny (95xxxx nebo 25xxxx) AMOUNT ANO Celková částka za objednávku v haléřích. Zobrazuje se i na platební stránce ČS, kam držitel karty zadává údaje o kartě. Více informací v dalším bodě. CURRENCY ANO Kód měny dle ISO 4217 (v číselném formátu). Je třeba věnovat pozornost kombinaci částky a měny měna s exponentem 0 je v poli amount reprezentována v jednotkách, zatímco měna s exponentem 2 v centech. Povolené měny, jejich číselné kódy a exponenty: MĚNA KÓD ČÍSLO EXPONENT Česká koruna CZK 203 2 Euro EUR 978 2 Britská libra GBP 826 2 Americký dolar USD 840 2 V praxi to znamená, že všechny povolené měny jsou reprezentovány v centech. Pokud je hodnota proměnné amount nastavena na 500, jedná se o částku 5,00 (CZK, EUR, GBP nebo USD). BRAND NE DOPORUČUJEME VYNECHAT. Typ karty. Je nepovinná a od října 2014 redundantní, protože platební brána již detekuje typ karty automaticky na základě zadaného čísla karty. Zpětná kompatibilita je zajištěna, ale hodnota proměnné už nemá žádný vliv. TRANSACTIONTYPE ANO Typ transakce. Proměnná může mít hodnoty authorisation nebo sale (více o typu transakce pod touto tabulkou): Authorisation (předautorizace) po úspěšné autorizaci se pouze zablokuje požadovaná částka na účtu držitele karty. Transakci pak musí do 7 kalendářních dnů od vytvoření dokončit obchodní partner prostřednictvím Back Office (tzv. capture). Pokud dokončení do sedmi dnů neprovede, předautorizace se automaticky zruší (lze ji zrušit manuálně dříve). Sale (přímý prodej) po úspěšné autorizaci se transakce ihned automaticky dokončí, obchodní partner ji už nemusí manuálně potvrzovat. e-commerce Integrace do systému obchodního partnera 11

MERCHANTREF ANO Referenční číslo transakce. Proměnná musí být unikátní pro každý pokus o zaplacení, tedy pro každé odeslání úvodního POST formuláře na adresu platební brány. Maximální délka proměnné je 12 znaků (pro opakované platby maximálně 8 znaků) a lze použít pouze alfanumerické znaky. Při přesměrování na OK a NOK URL se tato proměnná vrací jako ref. MerchantRef lze snadno použít pro párování transakcí ve Vašich systémech, je totiž uváděna mimo jiné i v zasílaných avízech a v přehledu transakcí v Merchant Back Office. NOVÉ ORDERID1 NE Pole pro uvedení čísla objednávky nebo dalšího řetězce. Maximální délka proměnné je 12 znaků. Tuto proměnnou lze snadno použít pro párování transakcí ve Vašich systémech, je totiž uváděna mimo jiné i v zasílaných avízech. NOVÉ ORDERID2 NE Pole pro uvedení čísla objednávky nebo dalšího řetězce. Maximální délka proměnné je 20 znaků. Tuto proměnnou lze snadno použít pro párování transakcí ve Vašich systémech, je totiž uváděna mimo jiné i v zasílaných avízech. MERCHANTDESC NE Krátký popis objednávky (název zboží, číslo objednávky apod.). Zobrazuje se v oznamovacích e-mailech i na platební bráně, kde zákazník zadává údaje o kartě. Maximální možná délka proměnné je 125 znaků pokud je delší, systém automaticky ořízne konec. EXTENSION_RECURRINGFREQUENCY ** Počet dní mezi jednotlivými pravidelnými platbami. Speciální hodnoty jsou 1 (denní platba), 28 (měsíční) a 365 (roční). V případě, že se jedná o jednorázovou platbu, je nutné odeslat prázdnou hodnotu nebo proměnnou úplně vypustit. EXTENSION_RECURRINGENDDATE ** Datum ukončení opakované platby. Po tomto datu se už další transakce neprovede. Formát je YYYYMMDD. V případě, že se jedná o jednorázovou platbu, je nutné odeslat prázdnou hodnotu nebo proměnnou úplně vypustit. LANGUAGE ANO Touto proměnnou nastavujete jazykovou verzi platební brány a oznamovacího e-mailu pro zákazníka. Povolené hodnoty jsou CZ (čeština), SK (slovenština), DE (němčina), EN (angličtina), RU (ruština), ES (španělština), PT (portugalština) a UA (ukrajinština). Dále je možné zasílat specifické hodnoty E-EN a E-DE, které zobrazují na platební bráně místo loga ČS logo Erste Group. Pokud máte požadavek na přidání dalších jazyků, obraťte se na podporu e-commerce. e-commerce Integrace do systému obchodního partnera 12

EMAILCUSTOMER NE E-mailová adresa zákazníka pro zaslání oznamovacího mailu. Má smysl pouze v případě, že je zasílání oznamovacích mailů povolené. Adresa zákazníka výrazně napomáhá k odhalení podezřelých/podvodných plateb, proto silně doporučujeme adresu vyžadovat při každé platbě. CARDHOLDERID *** Unikátní identifikátor zákazníka v systému obchodního partnera. Obchodní partner proměnnou zasílá pouze v případě, že se jedná o registrovanou platbu (viz kapitola 5). Maximální povolená délka je 50 znaků. Proměnné definovatelné obchodním partnerem. Maximální povolená délka jedné proměnné je 255 znaků. Zavedené použití je následující (pro inspiraci): VAR 1-9 NE var1-6 vhodné především pro zanesení adresy pro doručení zboží, názvu zboží, způsobu dodání atd. var7-8 adresa obchodního partnera var9 adresa webu obchodního partnera Proměnné var1-9 se zobrazují i v oznamovacích e- mailech pro držitele a obchodního partnera. VLASTNÍ PROMĚNNÉ NE Obchodní partner má možnost si nadefinovat vlastní proměnné. Ty se pak posílají jako součást Confirmation POSTu, Rejection POSTu a při přesměrování na OK/NOK URL. Pokud v New Payment POSTu pošlete proměnnou, jejíž název není definován v této tabulce, systém ji považuje za vlastní proměnnou. Poznámka: Povinné proměnné musí být součástí každého inicializačního POST formuláře! ** povinné proměnné v případě, že se jedná o recurring (opakovanou) platbu *** povinná proměnná v případě, že se jedná o registrovanou platbu UPOZORNĚNÍ: OMEZENÍ DÉLKY ZPRÁVY MSG DÉLKA ZPRÁVY Maximální možná délka všech proměnných i s jejich názvy je 2048 znaků. e-commerce Integrace do systému obchodního partnera 13

TIP: POPIS TYPŮ TRANSAKCÍ TRX TRX TRX TRANSAKCE SALE (PRODEJ) TRANSAKCE AUTHORISATION (PŘEDAUTORIZACE) TRANSAKCE RECURRING (OPAKOVANÁ PLATBA) Transakce sloužící pro autorizaci a následné zpracování platební transakce. Je shodná s transakcí typu prodej na platebních terminálech. Obvykle se využívá pro úhradu zboží a služeb tam, kde je platba požadována bez odkladu po objednání zboží. Je kombinací autorizace a realizace v jednom procesu. Transakce sloužící k předautorizaci platby a k blokaci prostředků na účtu držitele karty po dobu 7 dnů. V této lhůtě máte možnost buď blokované peníze klientovi strhnout, nebo předautorizaci zrušit a tím mu je odblokovat, například pokud nemůžete objednávku dodat. Dokončení (realizace) předautorizace je možné v prostředí Merchant Back Office nebo pomocí XML rozhraní (viz kap. 4). Řetězec transakcí, které jsou automaticky zpracovávány bankou na základě zaslaných parametrů v první transakci. Částka je vždy stejná, stejně jako interval mezi jednotlivými platbami. S transakcemi je možné pracovat (pozastavovat, spouštět, rušit, atd.) v prostředí Merchant Back Office nebo přes XML rozhran (viz kap. 4). U těchto transakcí neprobíhá standardní validace transakce, ale pokud budete mít zájem, je možné zapnout zasílání confirmation postu při každé platbě. 2.3. VALIDATION POST (POVINNÉ) Validation POST neboli validace je bezpečnostní opatření, které zamezuje zpracování transakcí, jejichž citlivé údaje byly pozměněny útokem třetí strany. Obvyklým útokem hackera je snaha změnit údaje odesílané v inicializačním POST formuláři (změnit částku, měnu apod.). Validace ověřuje, že údaje přijaté od obchodního partnera nebyly nijak pozměněny. e-commerce Integrace do systému obchodního partnera 14

Obrázek č.1: Validation post 1. Váš systém uloží do své databáze údaje o transakci (viz kapitolu 2.2.). Ukládání se obvykle provádí ve chvíli, kdy je klientovi zaslána do prohlížeče závěrečná stránka s potvrzením typu platby a Vy už znáte všechny údaje o objednávce. 2. Obchodní partner odešle údaje do systému ProxyPay (inicializační formulář, viz kapitolu 2.2.). 3. ProxyPay přijaté údaje odešle zpět na Vaši Validation URL metodou HTTP POST (3a). Validation skript musí údaje přijaté ze systému ProxyPay křížově zkontrolovat s údaji zapsanými v databázi (3b), které byly odeslány v bodě 2. 4. Pokud údaje souhlasí, skript vygeneruje html stránku se zprávou [OK] : <html><head></head><body>[ok]</body></html> 5. ProxyPay po přijetí odpovědi považuje validaci za úspěšnou a pokračuje v provádění transakce. Pokud skript odpoví jinak než výše uvedenou stránkou, validace je neúspěšná, transakce je zrušena, systém odešle Rejection POST (viz 2.5) a zákazník je přesměrován na NOK URL. Jak je vidět na obrázku č.1 validation skript může být součástí systému obchodního partnera, nebo může fungovat odděleně. Skript může být v průběhu transakce volán více než jednou. Může být vytvořen v jakémkoliv programovacím jazyce (PHP, ASP, Perl, atd.). Skript musí provést kontrolu údajů odeslaných metodou POST ze systému ProxyPay. Údaje jsou zasílané ve formě řetězce složeného z proměnných definovaných v kapitole 2.2. v tabulce č.1. e-commerce Integrace do systému obchodního partnera 15

Tabulka č.2: Seznam proměnných v řetězci PROMĚNNÁ FORMÁT KONTROLA POPIS POLE merchantref * ALPHANUM povinná Referenční číslo transakce. merchantid NUMERIC povinná Identifikační číslo obchodního partnera. amountcents NUMERIC povinná Částka v haléřích bez desetinné čárky. amountreal nepovinná Reálná částka s desetinnou čárkou. exponent NUMERIC povinná Exponent měny (viz 2.2. currency). currencycode NUMERIC povinná Číselný kód měny. password povinná Potvrzující heslo (confirmation password) extension_rec urringfrequen cy ** NUMERIC povinná Interval (počet dní) mezi opakovanými platbami. extension_rec urringenddate ** YYYYMMDD povinná Datum konce cyklu opakovaných plateb. cardholderid *** povinná Identifikátor zákazníka ve Vašem systému pro účely registrovaných plateb * proměnná merchantref může obsahovat pouze alfanumerické znaky (a-z, A-Z, 0-9) ** proměnná se používá pouze v případě, že se jedná o opakovanou (periodickou) platbu *** proměnná se používá pouze v případě, že se jedná o registrovanou platbu Příklad dat odeslaných na Validation URL: https://www.obchod.cz/ecommerce/validation.php merchantid=259999 merchantref=35 amountcents=20000 amountreal=200.00 currencycode=203 password=12345abcde exponent=2 cardholderid=cardholder12345 e-commerce Integrace do systému obchodního partnera 16

2.4 CONFIRMATION POST (POVINNÉ) Confirmation POST neboli konfirmace (krok 2 v kapitole 2.1) je podobně jako validation POST HTTP POST požadavek, který slouží jako finální potvrzení z Vaší strany před dokončením transakce. Součástí požadavku jsou všechny údaje potřebné pro další zpracování na straně obchodního partnera. Tyto údaje se obvykle používají pro generování potvrzovacích e-mailů, změny v databázi (změna počtu zboží, stavu objednávky) a podobně. Obrázek č.2: Confirmation post 1. Systém ProxyPay obdrží potvrzení, že platební karta úspěšně prošla autorizací a lze s ní zaplatit. 2. ProxyPay odešle veškeré údaje o platbě na Confirmation URL metodou HTTP POST. 3. Váš Confirmation skript zkontroluje, zda přijaté údaje souhlasí s údaji v databázi. 4. Pokud údaje souhlasí, Váš skript vygeneruje html stránku se zprávou [OK] : <html><head></head><body>[ok]</body></html> 5. ProxyPay přesměruje držitele karty na Vaši OK URL. 6. Po úspěšném dokončení transakce můžete provést potřebné změny v databázi (změna počtu zboží, změna stavu objednávky atd.). 7. Dodatečně můžete na OK URL znovu potvrdit držiteli karty, že jeho transakce proběhla úspěšně. Pokud skript odpoví jinak než výše uvedenou stránkou, konfirmace je neúspěšná, transakce se zruší, systém odešle Rejection POST (viz 2.5) a držitel je přesměrován na NOK URL. e-commerce Integrace do systému obchodního partnera 17

Obdobně jako validation skript může být i confirmation skript součástí Vašeho systému nebo může fungovat odděleně. Může být vytvořen v jakémkoliv programovacím jazyce. Skript musí provést kontrolu údajů odeslaných metodou HTTP POST ze systému ProxyPay. Údaje jsou zasílané ve formě řetězce složeného z proměnných definovaných v kapitole 2.2 a v následující tabulce. Tabulka č.3: Seznam proměnných PROMĚNNÁ FORMÁT KONTROLA POPIS POLE merchantref * ALPHANUM povinná Referenční číslo transakce. company nepovinná Název obchodního partnera (firmy). firstname nepovinná Jméno kontaktní osoby. lastname nepovinná Příjmení kontaktní osoby. merchantid NUMERIC povinná Identifikační číslo obchodního partnera. shopname nepovinná Název Vaší provozovny v systémech ČS. password povinná Potvrzovací heslo. amountcents NUMERIC povinná Částka v haléřích bez desetinné čárky. amountreal nepovinná Reálná částka s desetinnou čárkou. currencycode NUMERIC povinná Číselný kód měny. currencysymbol ALPHA nepovinná Symbol měny (CZK, EUR, GBP, USD). serverref nepovinná Unikátní číslo transakce přiřazené v ProxyPay. merchantdesc nepovinná Váš slovní popis transakce. language ALPHA nepovinná Jazyk vybraný držitelem karty. var1-9 nepovinná Proměnné var1-var9. referrer nepovinná URL, ze kterého přišel požadavek na transakci. ip nepovinná IP adresa držitele karty. useragent nepovinná Prohlížeč držitele karty. datetime nepovinná Datum a čas provedení transakce. extension_recurri ngenddate ** extension_recurri ngfrequency ** YYYYMMDD povinná Datum ukončení opakovaných plateb. NUMERIC povinná Interval mezi opakovanými platbami. brand ALPHA nepovinná Typ použité karty. merchantvar1-9 nepovinná Proměnné merchantvar1-9. e-commerce Integrace do systému obchodního partnera 18

PROMĚNNÁ FORMÁT KONTROLA POPIS POLE cardholderid*** povinná Identifikátor zákazníka ve Vašem systému pro účely registrovaných plateb vlastní proměnné nepovinná Vámi definované vlastní proměnné * proměnná merchantref může obsahovat pouze alfanumerické znaky (a-z, A-Z, 0-9) ** proměnná se používá pouze v případě, že se jedná o recurring (opakovanou) platbu *** proměnná se používá pouze v případě, že se jedná o registrovanou platbu Příklad dat odeslaných na Confirmation URL: https://www.obchod.cz/ecommerce/confirmation.php merchantref=113 merchantid=259999 password=12345abcde amountcents=50000 currencycode=203 amountreal=500.00 company=firma+s.r.o. firstname=i.+c. lastname=wiener shopname=eshop.cz currencysymbol=czk serverref=259999-113 merchantdesc=vase+objednavka+c.+113 language=cz var1=produkt+123abc var2= var3= var4= var5= var6= var7= var8= var9= referrer=http%3a%2f%2f10.182.34.206%2feshop.com%2fplatba.php ip=10.182.34.211 useragent=mozilla%2f4.0+%28compatible%3b+msie+6.0%3b+windows+nt+5.1%3b+ CSIE60SP01%3B+.NET+CLR+1.0.3705%3B+.NET+CLR+1.1.4322%29 datetime=31%2f05%2f2012+16%3a39%3a23 brand=visa cardholderid=cardholder12345 e-commerce Integrace do systému obchodního partnera 19

2.5 REJECTION POST (POVINNÉ) Rejection POST je HTTP POST požadavek zasílaný z ProxyPay do Vašeho systému, který slouží jako zpráva o tom, že během zpracování transakce došlo k chybě. Součástí zprávy jsou všechny údaje potřebné pro další zpracování na Vaší straně včetně chybového kódu a popisu chyby. Obrázek č.3: Rejection post 1. ProxyPay obdrží informaci, že při zpracování transakce došlo k chybě (např. neúspěšný validation/confirmation POST, neúspěšná autorizace/autentizace karty apod.) 2. ProxyPay odešle veškeré údaje o platbě a popis chyby na Rejection URL metodou HTTP POST. 3. Váš Rejection skript zkontroluje, zda přijaté údaje souhlasí s údaji v databázi. 4. Pokud údaje souhlasí, skript vygeneruje html stránku se zprávou [OK] : <html><head></head><body>[ok]</body></html> 5. Držitel karty je přesměrován na Vaši NOK URL. 6. Po obdržení zamítavé informace můžete provést potřebné změny v databázi (změna stavu objednávky, odeslání zamítavého e-mailu zákazníkovi atd.). Pozn.: Odpověď na rejection POST nemá vliv na výsledek transakce, kontroluje se pouze pro informaci, aby bylo zřejmé, že Váš systém přijal zprávu o neúspěchu transakce. Rejection skript může být součástí Vašeho systému nebo může fungovat odděleně. Může být vytvořen v jakémkoliv programovacím jazyce. Skript musí provést kontrolu údajů odeslaných metodou HTTP e-commerce Integrace do systému obchodního partnera 20

POST ze systému ProxyPay. Údaje jsou zasílané ve formě řetězce složeného z proměnných definovaných v kapitole 2.2 a v následující tabulce. Tabulka č.4: Seznam proměnných PROMĚNNÁ FORMÁT KONTROLA POPIS POLE errorcode nepovinná Chybový kód transakce. errorstring nepovinná Popis chybového kódu transakce. merchantref * ALPHANUM povinná Referenční číslo transakce. company nepovinná Název obchodního partnera (firmy). firstname nepovinná Jméno kontaktní osoby. lastname nepovinná Příjmení kontaktní osoby. merchantid NUMERIC povinná Identifikační číslo obchodního partnera. shopname nepovinná Název Vaší provozovny v systémech ČS. password povinná Potvrzovací heslo. amountcents NUMERIC povinná Částka v haléřích bez desetinné čárky. amountreal nepovinná Reálná částka s desetinnou čárkou. currencycode NUMERIC povinná Číselný kód měny. currencysymbol ALPHA nepovinná Symbol měny (CZK, EUR, GBP, USD). serverref nepovinná Unikátní číslo transakce přiřazené v ProxyPay. merchantdesc nepovinná Slovní popis transakce. language ALPHA nepovinná Jazyk vybraný držitelem karty. var1-9 nepovinná Proměnné var1-var9. referrer nepovinná URL, ze kterého přišel požadavek na transakci. ip nepovinná IP adresa držitele karty. useragent nepovinná Prohlížeč držitele karty. datetime nepovinná Datum a čas provedení transakce. extension_recurring enddate ** extension_recurringf requency ** YYYYMMDD povinná Datum ukončení opakovaných plateb. NUMERIC povinná Interval mezi opakovanými platbami. brand ALPHA nepovinná Typ použité karty. merchantvar1-9 nepovinná Proměnné merchantvar1-9. vlastní proměnné nepovinná Proměnné definované obchodním partnerem. e-commerce Integrace do systému obchodního partnera 21

PROMĚNNÁ FORMÁT KONTROLA POPIS POLE errorcode nepovinná Chybový kód transakce. errorstring nepovinná Popis chybového kódu transakce. cardholderid *** povinná Identifikátor zákazníka ve Vašem systému pro účely registrovaných plateb * - proměnná merchantref může obsahovat pouze alfanumerické znaky (a-z, A-Z, 0-9) ** - proměnná se používá pouze v případě, že se jedná o opakovanou (periodickou) platbu *** - proměnná se používá pouze v případě, že se jedná o registrovanou platbu Příklad dat odeslaných na Rejection URL: https://www.obchod.cz/ecommerce/rejection.php errorcode=45011 errorstring=card+blocked merchantref=113 merchantid=259999 password=12345abcde amountcents=50000 currencycode=203 amountreal=500.00 company=firma+s.r.o. firstname=i.+c. lastname=wiener shopname=eshop.cz currencysymbol=czk serverref=259999-113 merchantdesc=vase+objednavka+c.+113 language=cz var1=produkt+123abc var2= var3= var4= var5= var6= var7= var8= var9= referrer=http%3a%2f%2f10.182.34.206%2ffotoshop%2fplatba.php ip=10.182.34.211 useragent=mozilla%2f4.0+%28compatible%3b+msie+6.0%3b+windows+nt+5.1%3b +CSIE60SP01%3B+.NET+CLR+1.0.3705%3B+.NET+CLR+1.1.4322%29 datetime=31%2f05%2f2004+16%3a39%3a23 brand=visa cardholderid=cardholder12345 e-commerce Integrace do systému obchodního partnera 22

3. REGISTROVANÉ PLATBY (VOLITELNÉ) Registrované platby je označení pro novou funkcionalitu systému ProxyPay, která umožňuje držiteli karty uložit údaje o kartě pro další platby, aniž by musel znovu vyplňovat číslo karty a datum expirace. Uložené údaje jsou vázané vždy na jeden e-shop (jedno merchantid). Registrované platby přinášejí zásadní zjednodušení a zrychlení platby z pohledu Vašich zákazníků/držitelů karet v rámci Vašeho e-shopu (systému). Poté, co zákazník zaplatí první objednávku a uloží si příslušnou použitou kartu, nemusí už při následujících platbách vyplňovat nic kromě CVV2/CVC2 kódu dané karty. Řešení je zcela zabezpečené a údaje o platební kartě jsou uloženy v prostředí banky. Banka uchovává maskované číslo karty a expiraci karty. Tyto údaje nejsou nijak šířeny ani využívány k jiným účelům než k provádění Registrovaných plateb. Obrázek č.4: Registrované platby Systém umožňuje zákazníkovi uložit u každého obchodníka neomezené množství karet, které si může pro jednodušší orientaci pojmenovat. Grafické rozhraní platební brány bylo upraveno tak, aby umožnilo jak výběr požadované karty pro zaplacení, tak i správu jednotlivých registrovaných karet, to vše samozřejmě při zachování původní funkcionality brány (tzn. bez využití registrace karty). TIP: DOPORUČUJEME IMPLEMENTOVAT CARD REGISTROVANÉ PLATBY Tato funkcionalita je volitelná, ale neváhejte ji implementovat. Na e-shopech, kde je již nasazena, dochází stále ke zvyšování podílu plateb uloženou kartou, ke zvýšení konverzí a loajality klienta. Atraktivita pro zákazníky je ověřená a vyplatí se službu implementovat. e-commerce Integrace do systému obchodního partnera 23

JAK IMPLEMENTOVAT K využití registrovaných plateb je potřeba pouze jedna úprava Vašeho systému, a sice zavedení cardholderid proměnné, která slouží jako unikátní identifikátor zákazníka v systému obchodního partnera. Identifikace držitele karty a následná správa jeho registrovaných karet na platební bráně probíhá právě na základě tohoto ID. Pokud zašlete cardholderid do ProxyPay v rámci požadavku na platbu (New Payment Post, viz kapitola 2.2), systém zpřístupní funkcionalitu registrovaných plateb. Pokud ne, zůstane zachována původní funkcionalita a nabídka pro uložení karty se nezobrazí. Požadavky na proměnnou cardholderid: ID musí být unikátní v rámci Vašeho systému (e-shopu) a musí být jednoznačně přiřazeno jednomu konkrétnímu zákazníkovi. Musí být zaručeno, že zákazník bude mít při každém svém přihlášení do e-shopu a tedy při každém nákupu u obchodníka stejné ID. Váš systém bude hodnotu ID kontrolovat jako ostatní povinné proměnné ve validation, confirmation a rejection POSTech tedy pokud ID přijaté z ProxyPay nebude souhlasit s ID uloženým v databázi obchodního partnera, validation / confirmation skript platbu zamítne. Délka proměnné může být mezi 1 až 50 znaky. Doporučená délka je minimálně 8 znaků. Povolené znaky jsou ASCII znaky v rozsahu 33 (21h) až 126 (7Eh), tedy tisknutelné znaky bez řídících a bílých znaků (viz příloha A). Praktické využití cardholderid v rámci New Payment POSTu je uvedeno v kapitole 2.2. Praktické využití cardholderid v rámci Validation POSTu je uvedeno v kapitole 2.3. Praktické využití cardholderid v rámci Confirmation POSTu je uvedeno v kapitole 2.4. Praktické využití cardholderid v rámci Rejection POSTu je uvedeno v kapitole 2.5. e-commerce Integrace do systému obchodního partnera 24

4. XML INTERFACE (VOLITELNÉ) Rozhraní XML Interface Vám umožňuje provádět a zpracovávat transakce v systému ProxyPay, aniž by bylo nutné se přihlašovat do rozhraní ProxyPay Merchant Back Office. Doporučujeme před přečtením této kapitoly pročíst také dokument Příručka Back Office. Co Vám XML rozhraní umožňuje: vytváření nových transakcí typu přímý prodej MOTO vytváření nových transakcí typu předautorizace MOTO dokončování předautorizací MOTO E-COMMERCE rušení předautorizací refundace transakcí MOTO MOTO E-COMMERCE E-COMMERCE zjišťování stavu transakcí MOTO E-COMMERCE výpis posledních transakcí (max. 100) MOTO E-COMMERCE pozastavení/obnovení/rušení recurring transakcí MOTO E-COMMERCE Zásadní výhodou, kterou Vám XML rozhraní přináší, je možnost automatizování XML dotazů, což může výrazně usnadnit a urychlit práci s větším množstvím transakcí (například při dokončení desítek/stovek předautorizací při aktivaci slevy na slevových portálech apod.) 4.1 PRINCIP XML ROZHRANÍ Rozhraní je postaveno na principu obousměrné komunikace mezi Vaším systémem a systémem ProxyPay. Váš systém zasílá do ProxyPay XML dotazy, na jejichž základě se v ProxyPay provádějí požadované akce (zpracování/vytváření transakcí). ProxyPay na každý zaslaný požadavek generuje odpověď, taktéž ve formátu XML. Pro fungování řešení je nezbytné, aby Váš systém dokázal generovat a zpracovávat XML zprávy tak, jak je popsáno dále v této kapitole. Kam XML zprávy odesílat: https://3dsecure.csas.cz/backoffice/merchant ProxyPay na zaslanou zprávu vrátí XML odpověď. Důležitý je v této odpovědi zejména element <ErrorCode>, jehož hodnota udává, zda bylo zpracování požadavku úspěšné (nulová hodnota úspěšné, nenulová hodnota neúspěšné). V případě neúspěšného zpracování označuje hodnota ErrorCode konkrétní typ chyby. e-commerce Integrace do systému obchodního partnera 25

4.2 SPECIFIKACE XML ZPRÁVY XML zpráva by měla splňovat následující formát: Kódování zprávy musí být nastaveno na utf-8. Content-type zprávy musí být nastaven na application/xml. Zpráva musí být zasílána jako HTTP POST s XML zprávou v těle. Názvy elementů začínají velkým písmenem. Názvy atributů začínají malým písmenem. Každá XML zpráva je zapouzdřena v elementu Merchant-PP3M_POS: <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/eleenvelope.xsd" version="1.00.000" messageid="12345678">... </Merchant-PP3M_POS> 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 <AuthorisationRequest> ANO NE Dokončení předautorizace <CaptureRequest> ANO ANO Zrušení předautorizace <CancelRequest> ANO ANO Refundace <RefundRequest> ANO ANO Zjištění stavu transakce <TransactionStatusRequest> ANO ANO Výpis posledních transakcí <LastTransactionsRequest> ANO ANO Operace s recurring transakcemi <RecurringOperationRequest> ANO ANO Seznam elementů a jejich povinnost pro konkrétní XML zprávy: XML ELEMENT SALE AUTHORISATION CAPTURE CANCEL REFUND STATUS LAST TRX RECURRING 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 OrderInfo 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 NumberOfTransactions M e-commerce Integrace do systému obchodního partnera 27

XML ELEMENT SALE AUTHORISATION CAPTURE CANCEL REFUND STATUS LAST TRX RECURRING Operation M 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ů: XML ELEMENT TYP 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 OrderInfo 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 *** N 3 {203 978 826 840} CustomerEmail AN 1-50 emailová adresa držitele karty MOTO **** N 1 {1 0} Var1 Var9 AN 1-255 volitelná proměnná e-commerce Integrace do systému obchodního partnera 28

XML ELEMENT TYP POPIS NumberOfTransactions N 1-3 požadovaný počet transakcí na výpisu (max. 100) Operation AN 6-7 {Suspend Cancel Resume} PaymentInfo Brand A 4-12 typ karty (VISA, VisaElectron, MasterCard) Pan N 11-19 číslo karty ExpDate N 4 datum expirace karty (MMYY) CvvCvc2 N 3 CVV/CVC kód * 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) <?xml version="1.0" encoding="utf-8"?> <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> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <OrderInfo> <Amount>100</Amount> <MerchantRef>110161408</MerchantRef> <Currency>203</Currency> <CustomerEmail>cardholder@nekde.cz</CustomerEmail> <MOTO>1</MOTO> </OrderInfo> <PaymentInfo> <Brand>VISA</Brand> <Pan>4912345678901234</Pan> <ExpDate>1015</ExpDate> <CvvCvc2>123</CvvCvc2> </PaymentInfo> </SaleRequest> </Merchant-PP3M_POS> e-commerce Integrace do systému obchodního partnera 29

4.3.2. Příklad: AuthorisationRequest (pouze pro MO/TO transakce) <?xml version="1.0" encoding="utf-8"?> <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"> <AuthorisationRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <OrderInfo> <Amount>100</Amount> <MerchantRef>110231649</MerchantRef> <Currency>203</Currency> <CustomerEmail>cardholder@nekde.cz</CustomerEmail> <MOTO>1</MOTO> </OrderInfo> <PaymentInfo> <Brand>VISA</Brand> <Pan>4912345678901234</Pan> <ExpDate>1015</ExpDate> <CvvCvc2>123</CvvCvc2> </PaymentInfo> </AuthorisationRequest> </Merchant-PP3M_POS> 4.3.3. Příklad: CaptureRequest <?xml version="1.0" encoding="utf-8"?> <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"> <CaptureRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <OrderInfo> <Amount>100</Amount> <MerchantRef>110231649</MerchantRef> <SubReference>0</SubReference> </OrderInfo> </CaptureRequest> </Merchant-PP3M_POS> e-commerce Integrace do systému obchodního partnera 30

4.3.4. Příklad: CancelRequest <?xml version="1.0" encoding="utf-8"?> <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"> <CancelRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <OrderInfo> <Amount>100</Amount> <MerchantRef>110231649</MerchantRef> <SubReference>0</SubReference> </OrderInfo> </CancelRequest> </Merchant-PP3M_POS> 4.3.5. Příklad: RefundRequest <?xml version="1.0" encoding="utf-8"?> <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"> <RefundRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <OrderInfo> <Amount>100</Amount> <MerchantRef>110161408</MerchantRef> <SubReference>0</SubReference> </OrderInfo> </RefundRequest> </Merchant-PP3M_POS> e-commerce Integrace do systému obchodního partnera 31

4.3.6. Příklad: TransactionStatusRequest <?xml version="1.0" encoding="utf-8"?> <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"> <TransactionStatusRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <TransactionReference> <MerchantRef>3303203652</MerchantRef> <ServerRef>0</ServerRef> <Subreference>0</Subreference> </TransactionReference> </TransactionStatusRequest> </Merchant-PP3M_POS> 4.3.7. Příklad: LastTransactionsRequest <?xml version="1.0" encoding="utf-8"?> <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"> <LastTransactionsRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <NumberOfTransactions>5</NumberOfTransactions> </LastTransactionsRequest> </Merchant-PP3M_POS> e-commerce Integrace do systému obchodního partnera 32

4.3.8. Příklad: Pozastavení recurring transakce <?xml version="1.0" encoding="utf-8"?> <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"> <RecurringOperationRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <TransactionInfo> <MerchantRef>12345672</MerchantRef> </TransactionInfo> <Operation>Suspend</Operation> </RecurringOperationRequest> </Merchant-PP3M_POS> 4.3.9. Příklad: Obnovení recurring transakce <?xml version="1.0" encoding="utf-8"?> <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"> <RecurringOperationRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <TransactionInfo> <MerchantRef>12345672</MerchantRef> </TransactionInfo> <Operation>Resume</Operation> </RecurringOperationRequest> </Merchant-PP3M_POS> 4.3.10. Příklad: Zrušení recurring transakce <?xml version="1.0" encoding="utf-8"?> <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"> <RecurringOperationRequest> <Authentication> <MerchantID>123456</MerchantID> <UserName>xmluser</UserName> <Password>heslo</Password> </Authentication> <TransactionInfo> <MerchantRef>12345672</MerchantRef> </TransactionInfo> <Operation>Cancel</Operation> </RecurringOperationRequest> </Merchant-PP3M_POS> 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 <SaleRequest> <AuthorisationRequest> <CaptureRequest> <CancelRequest> <RefundRequest> <TransactionStatusRequest> <LastTransactionsRequest> <RecurringOperationRequest> N/A ZAPOUZDŘUJÍCÍ ELEMENT ODPOVĚDI <SaleResponse> <AuthorisationResponse> <CaptureResponse> <CancelResponse> <RefundResponse> <TransactionStatusResponse> <LastTransactionsResponse> <RecurringOperationResponse> <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. Seznam elementů a jejich výskyt v jednotlivých typech odpovědi: XML ELEMENT SALE AUTHORISATION CAPTURA CANCEL REFUND STATUS LAST TRX RECURRING ERROR 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

XML ELEMENT SALE AUTHORISATION CAPTURA CANCEL REFUND STATUS LAST TRX RECURRING ERROR ErrorCode M M M M M M M M Description O O O O O O O M AuthCode M M TransactionStatus TransactionStatusDesc M M TransactionList Transaction MerchantRef ServerRef SubReference TransactionDate PurchaseAmount AuthAmount CaptureAmount Currency MerchantDesc TransactionStatus TransactionStatusDesc M M M M M M M M M M M M 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 A 3 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 <TransactionStatus> a popisů stavu v <TransactionStatusDesc> 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 <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <SaleResponse> <MerchantRef>110161408</MerchantRef> <ServerRef>22892</ServerRef> <SubReference>0</SubReference> <ErrorCode>4096</ErrorCode> <Description>Bad card.</description> </SaleResponse> </Merchant-PP3M_POS> 4.4.2. Příklad AuthorisationResponse úspěšná předautorizace <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <AuthorisationResponse> <MerchantRef>110161408</MerchantRef> <ServerRef>20727</ServerRef> <SubReference>0</SubReference> <ErrorCode>0</ErrorCode> <AuthCode>1922512</AuthCode> </AuthorisationResponse> </Merchant-PP3M_POS> 4.4.3. Příklad TransactionStatusResponse <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <TransactionStatusResponse> <TransactionStatus>8192</TransactionStatus> <TransactionStatusDesc>OK</TransactionStatusDesc> <MerchantRef></MerchantRef> <ServerRef>1023250</ServerRef> <SubReference>0</SubReference> <ErrorCode>0</ErrorCode> </TransactionStatusResponse> </Merchant-PP3M_POS> e-commerce Integrace do systému obchodního partnera 37

4.4.4. Příklad LastTransactionsResponse <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <LastTransactionsResponse> <TransactionList> <Transaction> <ServerRef>1023630</ServerRef> <MerchantRef>3320688606</MerchantRef> <Subreference>0</Subreference> <TransactionDate>2012-02-03T14:24:03+0100</TransactionDate> <PurchaseAmount>10</PurchaseAmount> <AuthAmount>10</AuthAmount> <CaptureAmount>0</CaptureAmount> <Currency>EUR</Currency> <MerchantDesc>Description for order 3320688606</MerchantDesc> <TransactionStatus>8192</TransactionStatus> <TransactionStatusDesc>OK</TransactionStatusDesc> </Transaction> <Transaction> <ServerRef>1023620</ServerRef> <MerchantRef>3320687909</MerchantRef> <Subreference>0</Subreference> <TransactionDate>2012-02-03T14:22:56+0100</TransactionDate> <PurchaseAmount>10</PurchaseAmount> <AuthAmount>0</AuthAmount> <CaptureAmount>0</CaptureAmount> <Currency>EUR</Currency> <MerchantDesc>Description for order 3320687909</MerchantDesc> <TransactionStatus>4096</TransactionStatus> <TransactionStatusDesc>Failed</TransactionStatusDesc> </Transaction> <Transaction> <ServerRef>1023600</ServerRef> <MerchantRef>3320515812</MerchantRef> <Subreference>0</Subreference> <TransactionDate>2012-02-02T19:12:53+0100</TransactionDate> <PurchaseAmount>10</PurchaseAmount> <AuthAmount>0</AuthAmount> <CaptureAmount>0</CaptureAmount> <Currency>EUR</Currency> <MerchantDesc>Description for order 3320515812</MerchantDesc> <TransactionStatus>1048576</TransactionStatus> <TransactionStatusDesc>Pending Authentication </TransactionStatusDesc> </Transaction> <Transaction> <ServerRef>1023590</ServerRef> <MerchantRef>3320515812</MerchantRef> <Subreference>0</Subreference> <TransactionDate>2012-02-02T19:12:10+0100</TransactionDate> <PurchaseAmount>10</PurchaseAmount> <AuthAmount>0</AuthAmount> <CaptureAmount>0</CaptureAmount> <Currency>EUR</Currency> <MerchantDesc>Description for order 3320515812</MerchantDesc> <TransactionStatus>1</TransactionStatus> <TransactionStatusDesc>Initiated</TransactionStatusDesc> </Transaction> </TransactionList> </LastTransactionsResponse> </Merchant-PP3M_POS> e-commerce Integrace do systému obchodního partnera 38

4.4.5. Příklad RecurringOperationResponse úspěšná akce <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <RecurringOperationResponse> <MerchantRef>12345672</MerchantRef> <ServerRef>23350</ServerRef> <SubReference>0</SubReference> <ErrorCode>0</ErrorCode> </RecurringOperationResponse> </Merchant-PP3M_POS> 4.4.6. Příklad ErrorMessage nesprávné přihlašovací údaje <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <ErrorMessage> <ErrorCode>00000015</ErrorCode> <Description>Bad user or password</description> </ErrorMessage> </Merchant-PP3M_POS> 4.5 SEZNAM MOŽNÝCH STAVŮ TRANSAKCE V následující tabulce jsou uvedeny možné hodnoty elementů <TransactionStatus> (kódy stavu) a <TransactionStatusDesc> (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í: PRVNÍ PLATBA DALŠÍ PLATBY Při první platbě se zobrazí držiteli karty klasická platební brána. Pokud je 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í 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: <INPUT TYPE="hidden" NAME="ocp" VALUE="1"> Validační post iniciační transakce obsahuje následně nové pole: NÁZEV PARAMETRU TYP POŽADOVÁNA VALIDACE POPIS Ocpflag String ANO 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 SubsequentOCPResponse CancelOCPRequest CancelOCPResponse Vámi odeslaný požadavek na provedení následné OCP platby Bankou zaslaná odpověď na přijatý požadavek na provedení následné OCP platby. Vámi odeslaný požadavek na zrušení dalších OCP plateb pro danou iniciační transakci. Bankou zaslaná odpověď na požadavek na zrušení dalších OCP plateb pro danou iniciační transakci. Příklad SubsequentOCPRequest: <?xml version="1.0" encoding="utf-8"?> <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> <Authentication> <MerchantID>222</MerchantID> <UserName>name</UserName> <Password>Pass</Password> </Authentication> <OrderInfo> <Amount>100</Amount> <MerchantRef>860271196</MerchantRef> <OrderID1></OrderID1> <OrderID2></OrderID2> <Currency>203</Currency> <CustomerEmail>ipavlik@trask.cz</CustomerEmail> <Language>CZ</Language> <MOTO>0</MOTO> <OriginalMerchantRef>819887505</OriginalMerchantRef> </OrderInfo> </SubsequentOCPRequest> </Merchant-PP3M_POS> Příklad SubsequentOCPResponse: <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <SubsequentOCPResponse> <MerchantRef>860271196</MerchantRef> <ServerRef>1156260</ServerRef> e-commerce Integrace do systému obchodního partnera 43

<SubReference>2</SubReference> <ErrorCode>0</ErrorCode> <AuthCode>308467</AuthCode> </SubsequentOCPResponse> </Merchant-PP3M_POS> Příklad CancelOCPRequest: <?xml version="1.0" encoding="utf-8"?> <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"> <CancelOCPRequest> <Authentication> <MerchantID>222</MerchantID> <UserName>name</UserName> <Password>Pass</Password> </Authentication> <TransactionInfo> <MerchantRef>819887505</MerchantRef> <ServerRef>0</ServerRef> </TransactionInfo> </CancelOCPRequest> </Merchant-PP3M_POS> Příklad CancelOCPResponse: <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <CancelOCPResponse> <MerchantRef>819887505</MerchantRef> <ServerRef>1156260</ServerRef> <SubReference>0</SubReference> <ErrorCode>0</ErrorCode> </CancelOCPResponse> </Merchant-PP3M_POS> 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 56003 OCP is not enabled 56004 56005 Referenced transaction is not OCP registration OCP registration transaction is invalidated. 56006 Referenced transaction not found. 39401 Client certificate was not sent. 39402 39403 Untrusted client certificate was received. Client certificate verification was unsuccessful. 39404 Client certificate is invalid for merchant. OCP transakce musí být typu PRODEJ (transactiontype= sale ). OCP funkce není povolena pro dané MerchantID. Iniciační transakce, na kterou se odkazuje tato transakce, není typu OCP. Iniciační (první) OCP transakce byla zrušena. Iniciační (první) transakce nebyla nalezena. Klientský certifikát nebyl použit pro SSL připojení k XML rozhraní. Certifikační autorita, která podepsala klientský certifikát není přítomna v seznamu důvěryhodných certifikačních autorit. Ověření klientského certifikátu neproběhlo úspěšně. Subjectname certifikátu nebo jeho alternativní názvy nesouhlasí s regexem definovaným ve Vašem nastavení v ČS. 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: <?xml version="1.0" encoding="utf-8"?> <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"> <TransactionStatusRequest> <Authentication> e-commerce Integrace do systému obchodního partnera 45

<MerchantID>222</MerchantID> <UserName>name</UserName> <Password>Pass</Password> </Authentication> <TransactionReference> <MerchantRef>822108072</MerchantRef> <ServerRef>0</ServerRef> <Subreference>0</Subreference> <OCP>1</OCP> </TransactionReference> </TransactionStatusRequest> </Merchant-PP3M_POS> Příklad TransactionStatusResponse u OCP: <?xml version="1.0" encoding="utf-8"?> <Merchant-PP3M_POS xmlns="http://www.element.be/schemas" version="1.00.000" messageid="12345678"> <TransactionStatusResponse> <TransactionStatus>8192</TransactionStatus> <TransactionStatusDesc>OK SALE</TransactionStatusDesc> <MerchantRef>822108072</MerchantRef> <ServerRef>1156300</ServerRef> <SubReference>0</SubReference> <ErrorCode>0</ErrorCode> <OCPValidDate>20141231</OCPValidDate> </TransactionStatusResponse> </Merchant-PP3M_POS> 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 e- mailů 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: E-COMMERCE@CSAS.CZ 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