eAPI 1.8

Novinky ve verzi platební brány 1.8

Apple Pay je možné používat nejen jako NFC platbu telefonem nebo hodinkami, ale i online. Platební brána umožňuje integrovat Apple Pay přímo do vašeho e-shopu. Zákazník na iPhonu, iPadu nebo při nákupu z Macu v Safari neopouští při platbě e-shop, celá komunikace s Apple Pay a následně i platební bránou se odehraje na pozadí. Apple Pay funguje jak v nativních aplikacích na iOS, tak v browseru. Chcete-li zákazníkům Apple Pay nabídnout, přečtěte si prosím detailnější informace o funkci Apple Pay na webu a v aplikacích. Nové API funkce pro Apple Pay jsou pak technicky popsány zde.

Chcete vašim zákazníkům dát možnost vyzkoušet si zboží a zaplatit za nákup až za dva týdny? Na platební bráně můžete nyní používat i odloženou platbu Mall Pay, která za vás vyřeší odloženou splatnost (úhradu dostanete za dva až tři dny od doručení zboží zákazníkovi, zatímco zákazník platí za dva týdny) a přebírá i riziko nezaplacení zákazníkem. Máte-li o Mall Pay zájem, přečtěte si více informací o platbě Mall Pay, technickou specifikaci nových API metod pro Mall Pay a kontaktujte obchodního zástupce, který vám připraví novou smlouvu na Mall Pay.

Platba na míru

Platba na míru umožňuje zaplatit na platební bráně i takové nákupy, při kterých zákazník neprochází typickým procesem nákupu na e-shopu. Obchodník platbu založí na platební bráně, získá platební odkaz, který pak doručí zákazníkovi tím způsobem, který je aktuálně nejlepší: e-mailem, smskou, nebo jako QR kód vytištěný na faktuře. Po otevření platebního linku může zákazník zaplatit všemi platebními metodami, které má obchodník na platební bráně aktivní.

SHA-256 podpis API požadavků a odpovědí brány

eAPI v1.8 nově používá pro podpis komunikace mezi obchodníkem a platební bránou algoritmus SHA-256 (na místo SHA-1 používaného v eAPI v1.0 až v1.7).

Detailní mikrostavy pro platební metodu Mall Pay

Pro novou platební metodu Mall Pay platební brána vrací detailnější stavy transakce, než jsou základní stavy v životním cyklu transakce. V následujících API releasech budou tyto mikrostavy rozšířeny i na všechny ostatní platební metody. Mikrostavy lze použít pro získání detailnější informace například o pohybu zákazníka v platebním procesu (u stavu 2 - platba probíhá) nebo o konkrétním důvodu zamítnutí platby (ve stavu 6 - platba zamítnuta). Seznam a význam aktuálně podporovaných mikrostavů najdete v přehledu mikrostavů.

Chcete si jen zkusit, jak brána funguje?

Pro integraci a otestování napojení e-shopu na eAPI platební brány je pro obchodníka k dispozici integrační prostředí (tzv. iBrána) bežící na adrese https://iapi.iplatebnibrana.csob.cz. iBrána není nic jiného než pískoviště otevřené na hraní - bez smlouvy a komplikací. Dokumentaci i nástroj pro generování šifrovacích klíčů najdete tady na Gitu a můžete si naši platební bránu vyzkoušet ihned.

V tomto prostředí je 3DS autentizace a vlastní autorizace plateb prováděna oproti simulátoru (takže prosím používejte tyto karty), nicméně samotná funkcionalita platební brány včetně eAPI a uživatelského rozhraní je identická s produkčním prostředím. Můžete si tak otestovat nejenom vlastní přechod z e-shopu na platební bránu a zpět (předávání parametrů pomocí API) ale i finální vzhled platební brány - zobrazení loga obchodníka a jeho kontaktních údajů, zobrazení košíku a barevného schématu.

Průběh platby

Z pohledu plátce e-shopu se platba odehrává standardním způsobem, na který je plátce zvyklý u obdobných řešení využívaných bankami v České republice. Po dokončení nákupu proběhne z e-shopu přesměrování na platební bránu, kde plátce vyplní údaje karty a potvrdí platbu. Pokud má u své karty nastaveno 3D Secure ověření, je přesměrován na stránku své banky, kde provede ověření. V českém prostředí toto ověření probíhá nejčastěji pomocí SMS zprávy obsahující kód. Tuto SMS banka zašle plátci na jeho mobilní telefon a plátce přepisuje kód do ověřovacího formuláře. Následně proběhne platba, plátce je informován o jejím výsledku a přesměrován zpět do e-shopu.

Pod pokličkou se ovšem odehrává mnohem více událostí, které plátce nevidí. Jednotlivé operace odehrávající se na pozadí zachycuje následující obrázek. Dále projdeme jednotlivé kroky platebního procesu, popíšeme si data předávaná mezi jednotlivými systémy a probereme události odehrávající se uvnitř.

Diagram ukazuje provedení platby ze strany plátce a předpokládá, že dojde k úspěšnému obchodu a odeslání zboží e-shopem. Pokud dojde ke komplikacím, změnám či zrušení objednávky ze strany plátce či obchodníka, je v dalším procesu k dispozici rozhraní umožňující správu platby a její dodatečné zrušení. To si ale probereme až v dále popsané sekci správa stavu transakce.

Životní cyklus transakce

Transakce platby prochází několika kroky, které ovlivňuje obchodník, plátce a stav platební karty. Celý životní cyklus od založení platby po její dokončení a možné následné stavy na popud obchodníka ukazuje diagram níže, popíšeme si je detailně:

1) Platba založena je úvodní stav po volání metody payment/init. Po úspěšném založení se vyčkává na přesměrování plátce z e-shopu na stránku platební brány. Pokud založení transakce nelze provést, například z důvodu chyby ve vstupních datech nebo nepovolené operace daného obchodníka, požadavek spadne do stavu 6) Platba zamítnuta.

2) Platba probíhá po přesměrování plátce na stránku platební brány. Na pozadí probíhající platby se odehrává mnoho kroků od ověření parametrů až po zjištění, zda karta patří do 3D ověření, jeho samotný průběh u vydavatelské banky a následné provedení platby kartou. Tyto kroky jsou pro obchodníka skryty za průběhem platby, zajímá ho až samotný výsledek. Ten může být:

3) Platba zrušena - platba byla zrušena plátcem na platební bráně;
6) Platba zamítnuta - zamítnuto bankou z důvodu nedostatku prostředků, nepotvrzení 3D ověření plátcem či z jiného důvodu a nebo byl proces přerušen, např. protože plátce zavřel prohlížeč;
4) Platba potvrzena - platba byla provedena a čeká, až ji obchodník zařadí do zúčtování. Do tohoto stavu se úspěšná platba dostane, pokud je automatické zařazení do zúčtování vypnuto;
7) Čekání na zúčtování - platba byla provedena a automaticky zařazena do zúčtování.

3) Platba zrušena: Tento stav nastane, pokud plátce na stránce platební brány klikne na tlačítko zrušit. Plátce se vrací automaticky do e-shopu (platební brána jej přesměruje) a z pohledu životního cyklu transakce je tento stav koncový. Chce-li plátce znovu tu samou objednávku v e-shopu zaplatit kartou, e-shop musí vygenerovat zcela nový platební požadavek.

4) Platba potvrzena: Tento stav nastane po úspěšném provedení transakce v případě, že je automatické zařazení do zúčtování vypnuto. Již v založení platby říkáme, zda chceme transakci ihned po potvrzení automaticky poslat do zúčtování a převést tak peníze na účet obchodníka, nebo zda necháme autorizovanou transakci čekat, např. až připravíme zboží, a teprve po odeslání zboží pošleme transakci do zúčtování.

V tomto stavu je možné ponechat platbu maximálně po dobu sedmi dní, kdy je platba ze strany banky garantována a na kartě plátce jsou prostředky blokovány. POZOR! Po uplynutí této doby již není možné transakci zařadit do zúčtování! (Platba je odvolána, prostředky na kartě plátce jsou systémem automaticky odblokovány a banka platbu již negarantuje).

5) Platba odvolána: Dokud neprojde potvrzená platba zúčtováním, lze ji odvolat. To znamená, že nebude vůbec držiteli karty účtována, blokované prostředky na kartě se uvolní a neplatí se žádný poplatek. Tento stav je koncový a nelze jej vrátit. Počet odvolaných plateb obchodníkem je bankou monitorován.

Spoléhat na možnost odvolání platby lze pouze u transakcí, které dosud nebyly zúčtovány. Odvolat platbu lze u transakcí ve stavu „Platba potvrzena“ (4) pouze do té doby, dokud nebude zařazena do zúčtování a neproběhne samotné zúčtování. U transakcí ve stavu „Čekání na zúčtování“ (7) lze odvolat platbu maximálně do půlnoci daného dne, po této době se provádí zúčtování transakcí, u zúčtované platby lze již jen provést operaci vrácení prostředků.

6) Platba zamítnuta: Tento stav byl již popsán výše, důvodů zamítnutí platby je více a jsou detailně rozlišeny v návratovém kódu operace. Principiálně je lze řadit do několika skupin:

inicializace platby obsahovala chybná data
obchodník nemá povolenou platební operaci
plátce neprovedl správně 3D ověření
banka plátce (vydavatel karty) nepovolila platbu kartou
plátce zavřel prohlížeč a transakce vypršela

Specifickým stavem je zamítnutí platby ze strany banky. Teprve návratový kód upřesňuje, z jakého důvodu banka vydavatele karty transakci zamítla. Z pohledu obchodníka jde však o neúspěšnou platbu a tento detail je pouze informativní.

Platební brána v případě neúspěchu platby kartou plátce ihned neodsoudí k neúspěchu, ale sama mu znovu nabídne možnost platit jinou kartou. Tím se sníží skupina plátců, které neúspěch a návrat do e-shopu odradí. Z pohledu obchodníka je takováto "transakce napodruhé" po celou dobu ve stavu Platba probíhá a až výsledný úspěch či neúspěch ji přesune do příslušného stavu.

7) Čekání na zúčtování je stav, kdy jsou transakce již řazeny do fronty a dle nastavení zúčtovacích pravidel banky jsou zpracovávány. Dokud transakce není zúčtována, lze ji stále odvolat. Tento postup již byl popsán výše.

8) Platba zúčtována je pro obchodníka ten správný koncový stav. Vše proběhlo, transakce byla zařazena do zúčtování, zúčtování bylo provedeno a peníze jsou na cestě. Tento stav je sice koncový, nicméně pokud se obchodník rozhodne transakci zrušit (např. pokud zákazník objednávku zruší nebo zboží vrátí v zákonné lhůtě), může prostředky vrátit zákazníkovi pomocí operace vrácení prostředků. POZOR! Při platbě platebním tlačítkem ČSOB / Poštovní spořitelna se autorizovaná transakce dostane ze stavu 2 přímo do stavu 8. Je proto nutné, aby e-shop vyhodnocoval i stav 8 jako zaplaceno.

9) Zpracování vrácení: Pokud obchodník přesto zažádá o vrácení prostředků, přesune se existující transakce do tohoto stavu a operace probíhá. Zpracování vrácení je v bance schvalováno na základě podkladů dodaných obchodníkem bance, proto může tento stav trvat i několik dní.

10) Platba vrácena: Sem se dostává životní cyklus transakce po schválení jejího vrácení a reálném provedení transakce opačným směrem k původnímu plátci.

Jednotlivé kroky platebního procesu

Založení platby: payment/init V okamžiku, kdy je na e-shopu iniciována koncová fáze nákupu, přechází se k platbě a je vybrána metoda platby kartou, e-shop zakládá platbu na platební bráně. Kromě standardních údajů, jako je vlastní identifikace obchodníka, částka a referenční číslo objednávky, může e-shop zaslat do platební brány také detail nákupu včetně položek košíku. Tím se výrazně zpřehlední platební proces a zvýší důvěra zákazníka v korektní průběh operací na e-shopu a platební bráně.

Referenční číslo objednávky přiděluje e-shop obchodníka. Ve výsledku se referenční číslo objednávky objeví na výpisu transakcí z banky. Použije se tedy v systému obchodníka (účetnictví) pro párování plateb e-shopu proti bankovnímu účtu, a musí tedy splňovat podmínku variabilního symbolu - numerickou hodnotu o maximálně deseti místech. V aplikaci POSMerchant je referenční číslo objednávky zobrazeno ve sloupci Variabilní symbol.

Po založení platby přiřadí platební brána každé transakci jednoznačné ID platby payId. Tento identifikátor se vrací v odpovědi na payment/init a nese se celou platební transakcí ve všech stavech.

Číslo objednávky, které obchodník předává platební bráně při založení platby, musí být v rámci jeho e-shopu unikátní. V případě, že obchodník založí na platební bráně dvě transakce se stejným číslem objednávky, mají tyto transakce sice odlišné payId, ale na výpisu z banky se objeví jako dvě platby se stejným variabilním symbolem.

Pokud je zákazník na e-shopu přihlášen a jeho identita je známá, je možné předat také jednoznačný identifikátor zákazníka. To umožní, aby si zákazník na bráně svou platební kartu bezpečně uložil a při následných návštěvách tohoto e-shopu ji mohl znovu použít bez opisování dlouhého čísla karty.

Přesměrování na bránu: payment/process Pokud je platba na bráně úspěšně založena, může v následných krocích e-shop přesměrovat plátce na bránu. V odkazu předává pouze svůj jednoznačný identifikátor této platby, všechna ostatní data platební operace stejně jako obsah košíku a identita obchodníka jsou již na bráně připraveny během kroku Založení platby.

Operaci přesměrování na bránu je potřeba použít v případě, že zákazník opakovaně přechází tam a zpět mezi e-shopem a platební bránou (např. pomocí navigace v prohlížeči). Pro jednou založenou platbu s již nastaveným číslem objednávky, kdy tato platba má na platební bráně přidělené unikátní payId, nelze znovu založit transakci se stejným číslem objednávky. Potřebujete-li používat jako číslo objednávky opakovaně např. klientské číslo vašeho zákazníka, kontaktujte prosím podporu, kontrolu duplicitních čísel objednávek pro vás rádi vypneme.

Zjištění stavu platby: payment/status Systém e-shopu může kdykoli zjistit stav kterékoli své platby na platební bráně. Zavoláním této metody dostává zpět informaci, zda platba probíhá, případně ve kterém kroku se nachází, a po dokončení platby pak dostává informaci o tom, s jakým výsledkem byla platba dokončena.

Toto volání je nepovinné, u jednodušších implementací e-shopu nemusí být použito a čeká se pouze na návrat plátce zpět jeho přesměrováním na návratovou URL e-shopu.

Správa stavu transakce, vratky

E-shop může ověřit stav transakce v jejím průběhu, nebo po jejím dokončení. Transakce je držena v aktivní části brány následujících 48 hodin po jejím provedení. Pokud plátce (například omylem) vyvolá z historie prohlížeče opět platební bránu, nedojde k žádným komplikacím. Bude mu zobrazena korektní potvrzovací stránka platební brány s informací, jak tato platba dopadla.

Jak vyplývá z výše popsaného životního cyklu transakce, po úspěšném dokončení platby je ještě několik kroků, kterými může obchodník řídit její stav.

Odvolání transakce: payment/reverse Metoda odvolá úspěšně autorizovanou transakci a vyřadí ji ze systému, transakce nebude provedena a prostředky na kartě plátce se uvolní. Metodu lze použít pouze pro nezaúčtované transakce. Je nutno počítat s tím, že při volání metody ve stavu 7) Čekání na zúčtování může dojít ke zpracování zúčtování transakce, metoda vrátí chybu a transakce již bude proplacena.

Zařazení transakce do zúčtování: payment/close Tuto operaci voláme pouze v případě, že v založení platby máme vypnuto její automatické zařazení do zúčtování. Volání této funkce zařadí transakci do zúčtování a může být v e-shopu například spojena s okamžikem odeslání zboží.

Žádost o vrácení transakce: payment/refund Tuto operaci voláme v případě, že je třeba vrátit prostředky zpět plátci. Příkladem je reklamace zboží, zrušení objednávky nebo odstoupení od koupě na e-shopu v zákonné lhůtě. Nově od eAPI v1.5 lze provést tzv. částečný refund, vrácená částka je tedy menší než původní autorizovaná částka.

Detailní mikrostavy transakcí

Mikrostavy transakcí přinášejí e-shopu detailnější informace o průběhu nebo stavu zpracování transakce. Použití mikrostavů je nepovinné, jedná se o dodatečnou funkcionalitu. Pro obsluhu transakcí na platební bráně není nutné s mikrostavy pracovat, jako základ stačí pracovat se základními stavy životního cyklu transakce. Platební brána poskytuje mikrostav v odpovědích do e-shopu, které obsahují stav transakce (tj. např. v odpovědi na volání payment/status).

V eAPI 1.8 jsou mikrostavy dostupné pro platební metodu Mall Pay. V následujících API verzích budou mikrostavy rozšířeny na všechny platební metody.

Použití mikrostavů

Mikrostavy lze v e-shopu využít pro získání lepšího přehledu o průběhu nebo stavu transakce. Business hodnota významu mikrostavu se odvíjí od hlavního stavu, ve kterém se transakce nachází.

Mikrostavy ve stavu 2 (platba probíhá) jsou informací o tom, co zákazník na platební bráně dělá, resp. v jakém je kroku platebního procesu. Pro platební metody integrované přímo do e-shopu (např. Apple Pay, Platba Na klik atd.) je to pak informace o interakci zákazníka s externím poskytovatelem platební metody - tyto informace bývají ale velice omezené, nejlepší informace o průběhu platby ve stavu 2 má platební brána o platbě kartou, kterou zpracovává sama.

Mikrostavy ve stavu 3 (platba zrušena) jsou informací o způsobu zrušení platby, případně (je-li to možné) dávají e-shopu i informaci o tom, zda zákazník provedl pokus o platbu.

Mikrostavy ve stavu 6 (platba zamítnuta) jsou informací o důvodu zamítnutí, případně expirace platby.

Mikrostavy ve stavu 10 (platba vrácena) umožňují rozlišit mezi úplnou vratkou (další vratky na takovou transakci již není možné zadat) a částečnou vratkou (je možné provést další vratky až do výše původně autorizované částky).

Mikrostavy pro platební metody

Mikrostavy pro jednotlivé platební metody se liší podle průběhu platebního procesu, logiky platební metody a situací, do kterých se může zákazník dostat. Mikrostav vždy nese informaci o platební metodě, která právě probíhá nebo kterou byla transakce dokončena. Je-li to možné, mikrostavy dávají e-shopu i informaci o tom, zda zákazník provedl pokus o platbu.

Mikrostavy platební metody Mall Pay

Platební metoda Mall Pay podporuje mikrostavy pouze ve stavech 3, 6 a 10.

Mikrostavy Mall Pay | stav 3 "platba zrušena"

Pro transakce zrušené obchodníkem (poté, co zavolal operaci mallpay/cancel) rozlišuje platební brána následující mikrostavy:

statusDetail	popis
`canceled.aborted#mallpay`	zrušeno zákazníkem
`canceled.other_payment#mallpay`	změna způsobu platby a zánik objednávky
`canceled.undeliverable#mallpay`	nedoručitelné
`canceled.unavailable#mallpay`	zboží nedostupné
`canceled.abandoned#mallpay`	objednávka opuštěna zákazníkem
`canceled.changed#mallpay`	objednávka byla změněna a zanikla
`canceled.unprocessed#mallpay`	jinak nezpracovaná objednávka

Mikrostavy Mall Pay | stav 6 "platba zamítnuta"

Pro zamítnuté transakce rozlišuje platební brána následující mikrostavy:

statusDetail	popis
`declined.abandoned#mallpay`	opuštěno v žádosti – timeout PayID
`declined.rejected#mallpay`	obecné zamítnutí – zamítnutí žádosti v MALL Pay
`declined.shipping_timeout#mallpay`	obchodník nepředal logistický stav v limitu

Mikrostavy Mall Pay | stav 10 "platba vrácena"

Pro transakce, u nichž došlo k vratce, rozlišuje platební brána následující mikrostavy:

statusDetail	popis
`refunded.full#mallpay`	provedena plná vratka (jedna nebo více částečných)
`refunded.partial#mallpay`	provedena částečná vratka (jedna nebo více částečných, přičemž nebyla dosažena suma původní transakce)

Postup integrace a zabezpečení pomocí klíčů

eCommerce se pohybuje ve světě otevřeného internetu, proto je nutné data putující mezi systémy e-shopu a platební bránou zabezpečit proti útokům zvenčí. Komunikační kanál je zabezpečen protokolem SSL, pro ověření autenticity obchodníka jsou však navíc všechny požadavky odesílané na platební bránu podepsané jeho privátním klíčem.

Platební brána má k dispozici veřejnou část klíče, pomocí které může ověřit, že požadavek vygeneroval právě tento obchodník. Pro správnou funkčnost je tedy nutné vygenerovat tento pár: privátní klíč + veřejný klíč, privátní část předat do systému obchodníka (e-shopu, backoffice apod.) a veřejnou část předat platební bráně, tedy bance. Tento proces je součástí integrace obchodníka a platební brány.

První fáze integrace následuje po sjednání poskytování služeb eCommerce v bance, kde obdržel obchodník své MerchantID a uvedl, ze které e-mailové adresy bude s bankou komunikovat. V tomto okamžiku již jeho identita v systému platební brány existuje a vyčkává na další kroky takto:

Generování testovacích klíčů: Prostředky pro generování testovacích klíčů jsou dostupné na stránkách banky. Generátor zajišťuje, že přímo na stránce se do počítače obchodníka stáhne JavaScriptová aplikace obsahující generátor klíčů. Průvodce tohoto generátoru pak provede následující kroky:

Vyžádá od plátce jeho MerchantID a registrovanou e-mailovou adresu
Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
Nabídne pouze možnost generování testovacích klíčů
Lokálně vygeneruje testovací pár klíčů private key/public key
Privátní část private key uloží do souboru v počítači obchodníka
Veřejnou část odešle zabezpečeným kanálem na platební bránu

Integrace: V tomto okamžiku může obchodník spustit integraci svého řešení (e-shopu) s platební bránou. Privátní klíč předá vývoji, který může vyvíjet a testovat proti veřejné iBráně. Jeho klíč je tam automaticky zaveden ihned po vygenerování.

Integrační prostředí (iBrána)

Pro integraci a otestování napojení e-shopu na eAPI platební brány je pro obchodníka k dispozici integrační prostředí (tzv. iBrána) bežící na adrese https://iapi.iplatebnibrana.csob.cz.

V tomto prostředí je 3DS autentizace a vlastní autorizace plateb prováděna oproti simulátoru, nicméně samotná funkcionalita platební brány včetně eAPI a uživatelského rozhraní je identická s produkčním prostředím. Obchodník tak může otestovat nejenom vlastní přechod z e-shopu na platební bránu a zpět (předávání parametrů), ale i finální vzhled platební brány - zobrazení loga obchodníka a jeho kontaktních údajů, zobrazení košíku a barevného schématu.

Schválení: Jakmile je integrace dokončena, obchodník o této skutečnosti informuje banku a provede sérii předepsaných testů. Banka ověří jejich výsledky oproti záznamům testovací iBrány a v pozitivním případě obchodníka aktivuje.

Generování ostrých klíčů: V tomto okamžiku může obchodník vygenerovat nové, ostré klíče, které použije pro provozní prostředí. Použije generátor produkčních klíčů dostupný na stránkách banky, který pracuje následovně:

Vyžádá od plátce jeho MerchantID a registrovanou e-mailovou adresu
Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
Zjistí, že obchodník je aktivován a má splněny integrační testy
Lokálně vygeneruje ostrý pár klíčů private key/public key
Privátní část private key uloží do souboru v počítači obchodníka
Veřejnou část odešle zabezpečeným kanálem na platební bránu
Platební brána odešle na registrovanou adresu obchodníka aktivační kód

Potvrzení ostrého klíče obchodníkem Pro vyšší bezpečnost, ale také pro případ, kdy za běhu systému potřebuje obchodník svůj klíč vyměnit, je zde ještě jeden krok oproti testovacímu prostředí:

Obchodník má přístup do systému PosMerchant, kde se mu jeho nově vygenerovaný klíč objeví v částí eCommerce. Teprve zde jej potvrdí a zaktivuje. K této operaci je třeba jednorázový aktivační kód, který při převzetí veřejné části klíče odeslala brána na e-mail obchodníka. Okamžikem této aktivace se klíč přenese na platební bránu a ta jej ihned začne používat. Tímto krokem je dvojitě zabezpečeno předání klíče a současně obchodník sám určuje okamžik jeho zavedení na platební bránu.

Pískoviště

Systém umožňuje implementaci API rozhraní a přípravu na integraci e-shopu ještě před návštěvou banky a bez jakýchkoli závazků. Tomuto postupu říkáme nultá fáze - pískoviště, na kterém si můžete s bránou hrát (ale nezlobit). Lze tedy nejdříve zapojit vývoj, ověřit funkčnost napojení a teprve pak přejít do první fáze, navštívit banku a s obdrženým merchantID se napojit na testovací prostředí.

Ve skutečnosti ale probíhá stejně jako první fáze. V průvodci generováním klíčů na adrese https://iplatebnibrana.csob.cz/keygen se však vybere možnost Anonymní vývoj (nevyplňuje se merchantID ani e-mail) a průvodce následně zažádá platební bránu o přidělení vývojového merchantID. K tomuto merchantID pak obchodník vygeneruje na svém lokálním počítači klíče, veřejnou část přenese na platební bránu a privátní uloží do souboru.

Testovací přístup pro anonymní vývoj je platný jeden měsíc stejně jako testovací klíče. Přístupy jeho prostřednictvím jsou monitorovány a v případě zatížení neúměrného vývoji a testování mohou být služby pro toto merchantID omezeny.

Testovací karty

POZOR: Tyto karty jsou určeny pouze pro použití na integračním prostředí platební brány (autorizace oproti simulátoru). V případě, že se použije číslo karty, které není v seznamu testovacích karet, je autorizace zamítnuta.

Hledáte-li způsob, jak provést testovací transakce vyžadované bankou po uzavření smlouvy pro aktivaci plateb ve vašem e-shopu, použijte prosím tento postup testovacího scénáře a pro něj vyhrazené karty.

V rámci integračního prostředí provádí platební brána u testovacích karet ověření oproti simulátoru VISA/Mastercard directory serveru - detekuje, zda je zadaná testovací karta 3DS. Pro 3DS karty se provádí následná simulace autentizace oproti serveru vydavatelské banky (simulace zadání SMS kódu nebo zadání hesla). Pokud se použije karta, která není 3DS anebo 3DS servery neběží, provádí se pouze autorizace platby.

Výsledek 3DS autentizace závisí na zvoleném čísle testovací karty, pokud 3DS autentizace proběhne úspěšně, je následná autorizace platby závislá pouze na zadaném CVC/CVV kódu.

Testovací VISA karty (3DS1)

Číslo karty	Popis
4125010001000208	3DS VISA karta. Simulace úspěšné autentizace uživatele. Pokračuje se do autorizace (odpověnost za případný fraud je na straně vydavatelské banky).
4140920001000209	3DS VISA karta. Simulace neúspěšné autentizace uživatele. Uživatel má možnost zadat jinou kartu nebo zaplatit jiným způsobem.
4154610001000225	3DS VISA karta. Simulace neúplné autentizace uživatele. Pokračuje se do autorizace (odpověnost za případný fraud je na straně platební brány).
4154610001000217	3DS VISA karta. Simulace chyby na straně 3DS serveru vydavatelské banky. Uživatel má možnost zadat jinou kartu nebo zaplatit jiným způsobem.
4154610001000209	VISA karta bez 3DS oveření. Pokračuje se do autorizace (odpověnost za případný fraud je na straně platební brány).
4154610001000308	VISA karta. Simulace nefunkčnosti VISA Directory serveru. Pokračuje se do autorizace.
4154610001000407	VISA karta. Simulace chybné odpovědi VISA Directory serveru. Pokračuje se do autorizace.

Testovací MasterCard karty (3DS1)

Číslo karty	Popis
5168440001000202	3DS MC karta. Simulace úspěšné autentizace uživatele. Pokračuje se do autorizace (odpověnost za případný fraud je na straně vydavatelské banky).
5402980001000211	3DS MC karta. Simulace neúspěšné autentizace uživatele. Uživatel má možnost zadat jinou kartu nebo zaplatit jiným způsobem.
5542860001000232	3DS MC karta. Simulace neúplné autentizace uživatele. Pokračuje se do autorizace (odpovědnost za případný fraud je na straně platební brány).
5542860001000216	3DS MC karta. Simulace chyby na straně 3DS serveru vydavatelské banky. Uživatel má možnost zadat jinou kartu nebo zaplatit jiným způsobem.
5542860001000224	MC karta bez 3DS oveření. Pokračuje se do autorizace.
5542860001000323	MC karta. Simulace nefunkčnosti MC Directory serveru. Pokračuje se do autorizace.
5542860001000422	MC karta. Simulace chybné odpovědi MC Directory serveru. Pokračuje se do autorizace.

Testovací DINERS karty

Číslo karty	Popis
30569309025904	DINERS karta (bez 3DS ověření)
38520000023237	DINERS karta (bez 3DS ověření)

Testovací karty pro platbu na klik

Číslo karty	Popis
5332290001000202	Určeno pro test zamítnutí platby (z jakéhokoli důvodu, např. nedostatek prostředků) při volání `payment/recurrent` (eAPI v1 a v1.5) nebo `payment/oneclick/start` (eAPI v1.6, v1.7). Test proveďte tak, že nejprve kartu zaregistrujete pro příslušného klienta e-shopu pro prvotní platbu (tato transakce bude autorizována). Následně použijte kartu pro platbu na klik a ověřte, že e-shop korektně zpracuje zamítavou odpověď z brány.

Testovací karty dle regionů a vydavatelů

Číslo karty	Popis
4407520211155310	Určeno pro test restrikce akceptace na ČSOB karty. Tuto kartu použijí při testování jen ti obchodníci, kteří chtějí akceptovat pouze karty ČSOB. Většiny obchodníků se proto tento test netýká.
4550550001000207	Určeno pro test restrikce karty vydané v České republice a na Slovensku. Tuto kartu použijí při testování pouze obchodníci, kteří chtějí akceptovat pouze karty vydané v ČR a SR. Karta simuluje kartu vydanou v jiné evropské zemi.
4543320001000205	Určeno pro test restrikce karty vydané mimo Evropu. Karta simuluje kartu vydanou v USA.

Pravidla pro autorizace transakcí

Hodnota CVC/CVV

CVC/CVV	Popis
200	obecné zamítnutí
300	nedostatek prostředků
400	blokovaná karta
500	simulace technické chyby autorizace (zobrazení výsledku až po uplynutí timeoutu cca 30 sekund)
xxx	jakákoli hodnota mimo výše uvedené znamená úspěšnou autorizaci v případě použití testovacích karet uvedených výše

Hodnota expirace karty

Lze zadat jakoukoli platnou, neexpirovanou kombinaci MM/RR. Hodnota nemá vliv na autorizaci.

Loga a prezentace platebních metod

Na stránku košíku ve vašem e-shopu (případně do popisu platebních metod) umístěte loga platebních metod, které příjímáte. U platebních karet jsou to tzv. akceptační loga (acceptance marks) asociací Visa, MasterCard a Diners Club. Peněženky Apple Pay, platební tlačítka ČSOB / Poštovní spořitelny a Mall Pay mají vlastní loga a pravidla. Obecně platí, že žádné logo by nemělo být zobrazeno ve větší velikosti než ostatní loga. Použijete-li PNG ikony, nezvětšujte je. Potřebujete-li konkrétní velikost, vyrobte si ji z vektorových formátů nebo použijte SVG.

Platební karty (Visa, MasterCard, Diners Club)

Stáhněte si balík webových ikon ve formátu PNG: zip

Stáhněte si balík ikon ve vektorových formátech: zip

Stáhněte si balík vybraných ikon (pouze MasterCard, Maestro, kombinace MasterCard + Visa, loga ověření pomocí 3D Secure - MasterCard Identity Check a Verified by Visa) jako SVG: zip

POZOR! Platební tlačítka ČSOB a Poštovní spořitelny mají veškerou grafiku (i akční platební tlačítka pro přímé integrace do e-shopu) hostovanou. Níže v popisu najdete způsob, jak na ni odkazovat.

Balíky ikon obsahují následující loga:

MasterCard
Maestro
Visa
Visa Electron
Visa VPay
Diners Club
kombinace Visa + MasterCard horizontální a vertikální

Obě asociace používají pro bezpečnostní technologii 3d-Secure odlišné komerční názvy, které mají i logo:

MasterCard Identity Check
Verified by Visa

Apple Pay

Akceptační loga a pravidla pro prezentaci Apple Pay v e-shopu a mobilních aplikacích použijte podle aktuálních pravidel Apple:

Mall Pay

Pravidla pro prezentaci platební metody Mall Pay a loga Mall Pay naleznete jako PDF zde. Logo Mall Pay je k dispozici ve formátu SVG.

Platební tlačítka ČSOB a Poštovní spořitelny

Logo platebních metod ČSOB a Poštovní spořitelna okamžitá platba jsou taktéž hostovaná, tentokrát však na platební bráně. Logo využijte pro informování klientů o tom, že akceptujete platbu platebním tlačítkem ČSOB a/nebo Poštovní spořitelny. Platební tlačítko slouží pro inicializaci transakce s přímým přesměrováním z e-shopu do internetového bankovnictví, resp. na mobilní rozcestník.

Logo

Při vkládání loga do e-shopu dodržujte tato pravidla:

minimální šířka je 34 px
ochranná zóna je 1/4 výšky loga

Česká verze ČSOB

Česká verze Poštovní spořitelna

Anglická verze ČSOB

Anglická verze Poštovní spořitelna

Platební tlačítka

Při vkládání platebních tlačítek do e-shopu dodržujte tato pravidla:

minimální šířka je 60 px
ochranná zóna je 1/4 výšky tlačítka

Česká verze ČSOB

Česká verze Poštovní spořitelna

Anglická verze ČSOB

Anglická verze Poštovní spořitelna

Platba Na klik

Jak probíhá platba Na klik a na co je vlastně dobrá

Platba Na klik umožňuje stálým zákazníkům platit výrazně pohodlněji a rychleji. Při první (registrační) transakci dává klient svolení s prováděním následných transakcí a provádí platbu standardním způsobem (přesměrování na bránu, zadání čísla karty, platnosti, CVC, 3D Secure proces). Při každé následující transakci již klient jen řekne, že chce použít kartu z předchozího nákupu. Komunikace s platební bránou se provede na pozadí, bez nutnosti zadávat znovu číslo karty, které je uloženo na platební bráně.

Funkce Platby na klik není přístupná univerzálně, musí být ze strany ČSOB pro konkrétního obchodníka povolena. V nastavení se rozlišuje následná platba (1) do výše první (registrační) transakce, nebo (2) v libovolné výši. Výchozí nastavení omezuje následné platby částkou první transakce. Při aktivaci služby si prosím vyžádejte nastavení, které odpovídá způsobu použití platby Na klik ve vašem e-shopu.

Založení platby Na klik (vznik platební šablony)

První (registrační) transakce probíhá velice podobně jako běžná platba kartou na platební bráně. Jen s tím rozdílem, že v e-shopu si klient vybere uložení karty pro příští platby. Tento souhlas je bezpodmínečně nutné získat, není povolené souhlas skrývat a souhlas musí proběhnout aktivní volbou klienta (nejsou povolené "defaultně zaškrtnuté checkboxy"). Po získání souhlasu indikujete bráně při založení transakce, že chcete založit šablonu pro platbu Na klik (viz níže v technickém postupu).

Registrační transakci pro Platbu na klik bohužel také není možné provést peněženkou MasterPass, ani pomocí Apple Pay. Zákazník musí kartu zadat na bráně a transakce musí být autorizována.

Následné transakce Na klik (již bez zadávání čísla karty)

Následné transakce, které jsou již z pohledu klienta "Na klik" (nemusí zadávat karetní údaje, případně se platba děje bez jeho přítomnosti v e-shopu), jsou prováděny na pozadí, aniž by klient odcházel z e-shopu na platební bránu. Klient po celou dobu vidí pouze "točící se kolečko" v e-shopu. Transakce je potvrzena (zaplacena) nebo zamítnuta a tím končí. Výsledek platby se klient dozví v e-shopu.

Doporučení pro řešení platby Na klik

Vždy získejte souhlas klienta s prováděním plateb Na klik před platbou, nikoli po ní. Souhlas klienta se založením šablony pro platbu Na klik potřebujete pro správné volání brány. Navíc máte před platbou větší šanci, že klient se bude Vaší žádosti věnovat (než po platbě, kdy je všechno hotovo a již na bráně se klient dozvídá, jak platba dopadla).
Vysvětlete klientovi, na co mu bude platba Na klik dobrá a zdůrazněte, že data ukládá banka, nikoli e-shop. Vysvětlení vždy ušijte na míru kontextu Vašeho obchodu. Hodnota platby Na klik je jiná při objednávání rychlého rozvozu než při nákupu lednice.
Používejte platbu Na klik aktivně na mobilních webech a v mobilních aplikacích. Hodnota funkce platby Na klik je na mobilním kanálu ještě vyšší než na desktopu. Tato pohodlná a rychlá platba je na mobilu nejpohodlnější platební metodou a odstraňuje jednu z největších bariér m-commerce z pohledu zákazníka - nepohodlnou platbu.
Pokud zpracování platby Na klik neprojde, vysvětlete klientovi, co se děje, a naveďte ho k alternativě. Podle návratového kódu řekněte klientovi, zda byla jeho transakce odmítnuta (a důvod), nebo informujte klienta, že dříve uložená karta již není dostupná. Pokud není dostupná karta pro platbu Na klik, nabídněte klientovi založení nové a snažte se klienta udržet aktivního v rámci schématu opakované platby.

Kdy platba Na klik končí nebo je zrušena?

Zákazník sice nemá možnost zrušit souhlas s prováděním plateb Na klik prostřednictvím vydavatele své karty, nicméně i přesto nastává několik situací, ve kterých již není platba Na klik možná:

Registrační transakce nebyla dokončena - pokud není registrační transakce dokončena a neprojde kompletním clearingem, nemůže být považována za registrační transakci k opakované platbě.
Od poslední transakce Na klik, provedené kartou u obchodníka, uplynulo více než 12 měsíců.
Platnost karty zaregistrované pro platbu Na klik uplynula.
Registrační transakce (případně jakákoli transakce z řady) byla zpochybněna klientem nebo jeho vydavatelskou bankou (reklamačním procesem, tzv. chargeback)
Klient si u svého vydavatele nechal kartu zrušit nebo převydat.

Platba na klik technicky

První (registrační) transakce

obchodník pošle při založení platby v rámci operace payment/init v parametru payOperation hodnotu oneclickPayment (platba je na bráně označena jako šablona pro platby);
platba dále probíhá klasickým způsobem, tzn. plátce je z e-shopu obchodníka přesměrován na platební bránu pomocí operace payment/process, na platební bráně zadá potřebné údaje pro vlastní platbu (číslo karty, expiraci a CVC kód), po dokončení autorizace je plátce přesměrován z platební brány zpět na e-shop;
vzniklá šablona pro platbu Na klik je připravena k použití.

Následné platby Na klik

obchodník volá na eAPI nejprve operaci oneclick/init. V parametrech odkazuje na dříve provedenou platbu, která byla označena jako šablona pro platby, tato platba musí být úspěšně autorizována;
v rámci operace oneclick/init se nejprve ověří vstupní parametry, transakci se přidělí unikátní payId, které se vrátí v odpovědi zpět obchodníkovi;
pro spuštění vlastní autorizace volá obchodník na eAPI operaci oneclick/start. Jako jeden ze vstupních parametrů předává payId platby Na klik přidělené v předchozím kroku. Platební brána provede načtení potřebných údajů z dříve provedené platby včetně čísla karty a expirace a požadavek se posílá do autorizace;
výsledek autorizace obchodník ověří pomocí volání payment/status.

Ověření stavu šablony pro platbu

Kromě výše uvedených operací může obchodník pomocí operace oneclick/echo ověřit, v jakém stavu se nachází šablona pro platbu. Pomocí této operace se můžete ještě před nabídnutím platby Na klik ujistit, že šablonu je možné použít. Pokud není šablona použitelná, platbu Na klik nenabízejte. Vysvětlete zákazníkovi, že platba dříve uloženou kartou již není možná a nabídněte uložení karty nové. Zabráníte tak zbytečnému odmítnutí platby a zvyšujete pravděpodobnost, že si zákazník uloží novou kartu.

Druhým příkladem použití je zjištění stavu šablony při zobrazování uložených karet v zákaznickém účtu. Podle výsledku volání oneclick/echo můžete v zobrazení graficky odlišovat aktivní a neaktivní šablony. U neaktivních lze případně nabízet výměnu za jinou kartu pomocí korunové registrační transakce.

Platba na míru

Platba na míru umožňuje zaplatit na platební bráně i takové nákupy, při kterých zákazník neprochází typickým procesem nákupu na e-shopu. Obchodník platbu založí na platební bráně, získá platební odkaz, který pak doručí zákazníkovi tím způsobem, který je aktuálně nejlepší - e-mailem, smskou nebo jako QR kód vytištěný na faktuře. Po otevření platebního linku může zákazník zaplatit všemi platebními metodami, které má obchodník na platební bráně aktivní.

Platba na míru je na platební bráně ČSOB dostupná od verze eAPI 1.8, které přidává právě podporu zakládání plateb a získávání platebních linků.

Kdy je vhodné platbu na míru použít?

Fantazii a obchodním potřebám se samozřejmě meze nekladou. Toto je jen pár příkladů situací, kdy se vám může platba na míru hodit:

při vystavování faktur nebo zálohových faktur
pokud je potřeba zaplatit při obsluze klienta na call centru
pokud potřebujete od klienta přijmout platbu za dodatečnou změnu objednávky, která způsobila vyšší cenu

A pak je tu ještě jeden případ: když žádný e-shop nemáte a nechcete ani implementovat eAPI platební brány do vašich interních systémů (např. pro obsluhu klientů na call centru). Platbu na míru si můžete založit i "ručně" v administračním systému ČSOB POS Merchant. Výsledkem bude opět platební link, pomocí kterého váš klient zaplatí – a vůbec nepozná, že platba byla zadána ručně.

Jak platba na míru funguje pro můj e-shop / systém?

Když víte, kolik má klient zaplatit, založíte na platební bráně transakci. Kromě údajů, které na bránu posíláte při "běžných" platbách (částka, vaše číslo objednávky pro párování, údaje pro zobrazení v košíku atd.), můžete nastavit i platnost platby na míru, která je maximálně 60 dnů. Po uplynutí této doby již platba nebude aktivní. Z brány získáte platební odkaz (v eAPI customerCode), který identifikuje platbu pro vašeho zákazníka. Kód je šestimístný a obsahuje jak číslice, tak písmena. Tím komunikace s bránou končí a nyní musíte k zákazníkovi dopravit platební link v podobě:

https://platebnibrana.csob.cz/zaplat/{customerCode}

Způsob doručení nijak neomezujeme a záleží na vašem použití platby na míru, zda kód pošlete e-mailem, smskou či na fakturu a zda jej pošlete jako odkaz nebo například QR kód.

Když zákazník otevře platební link, zobrazí se mu platební brána ve stejné podobě, jako kdyby se přesměroval z e-shopu. Může použít všechny platební metody (tj. může si přímo na bráně vybrat mezi kartou, peněženkou MasterPass a platebními tlačítky). Po dokončení platby je zákazník přesměrován do e-shopu, který se tak dozví o výsledku platby. Platební link je aktivní až do doby uplynutí jeho platnosti (max. 60 dnů, viz výše - nastavení při zakládání platby) nebo uhrazení platby – podle toho, co nastane dříve. Pokud si zákazník otevře platební link "jen tak", nebo je platba zamítnuta, je platební link nadále platný a zákazník se k platbě může vrátit až do doby uplynutí platnosti platebního linku.

Založíte-li platbu na míru ručně v aplikaci POS Merchant, můžete si zvolit i možnost platby bez návratu do e-shopu. Tato volba je vhodná pro případ, že nemáte žádný systém integrovaný s platební bránou a zákazník se tak nemá kam "vrátit". Zaplacené transakce si pak musíte ručně kontrolovat v ČSOB POS Merchantu.

Jak můžeme platbu na míru implementovat?

Platba na míru nevyžaduje žádné nové API metody. Obsluhuje se pouze rozšířenými parametry metod payment/init. Kód pro předání zákazníkovi obdržíte jako součást odpovědi na volání payment/init.

Platba na míru a EET

Používáte-li EET funkci platební brány, můžete samozřejmě použít i platbu na míru. Tržba bude nahlášena (stejně jako v jiných případech) bezprostředně po autorizaci platby. Tj. brána nehlásí žádnou tržbu za platbu na míru, která potenciálně až desítky dní čeká na úhradu. Údaje pro EET účtenku obdržíte stejným způsobem jako při běžných transakcích, tj. společně s informací o výsledku transakce.

Co ještě vědět o platbě na míru?

Jaké jsou poplatky?

Stejné jako u platby při přesměrování zákazníka z e-shopu. Platba na míru není nijak zvlášť zpoplatněna.

Jak platbu na míru získám?

Možnost provádět platby na míru aktivujeme na vaši žádost. Kontaktujte prosím obchodního zástupce.

Zaúčtování na menší částku

Od eAPI v1.5 byla přidána možnost uzavřít transakci na menší částku, než na jakou byla původně autorizovaná.

Z pohledu business procesu nově tedy eAPI umožňuje autorizovat a následně uzavřít transakci na menší částku. Ať už z důvodu neschopnosti (nemožnosti na straně) obchodníka dodat část zboží, nebo proto, že konečná cena nákupu vzniká až poté, co zákazník opustil e-shop. Obchodník ale tento okamžik umí předvídat - nezavře sice při inicializaci transakci automaticky pomocí "closePayment": true, je však schopen uzavřít transakci později na jeden pokus.

Dostupné je pro platby kartou (včetně OneClick) a pro Apple Pay a MasterPass platby.

Apple Pay

Apple Pay na webu a v mobilních iOS & iPadOS aplikacích

Apple Pay je známá zejména z bezkontaktních plateb na platebních terminálech, kde lze platit telefonem, nebo hodinkami Apple Watch. Kartami, které si uživatelé zavedou do iPhonu, iPadu a Apple Watch je možné platit i online. Platební brána ČSOB je nově připravena na zpracování online plateb Apple Pay. Platba se odehrává přímo v e-shopu (na webu nebo v nativní mobilní iOS aplikaci), aniž by zákazník odcházel na platební bránu. Implementace Apple Pay tak vyžaduje integraci nejen na platební bránu, ale i přímo na Apple Pay. Při platbě si e-shop zažádá do Apple Pay o kartu, zákazník tuto žádost potvrdí (biometricky pomocí Touch ID, Face ID nebo na hodinkách) a zašifrované platební údaje jsou od Applu předány do e-shopu. Teprve v tento moment začíná na pozadí komunikace s platební bránou, která přijímá od obchodíka platební údaje (které si obchodník nemohl přečíst, protože komunikace mezi Applem až na platební bránu je šifrovaná), které platební brána ověří a použije pro autorizaci transakce. Celý proces je tedy velice podobný tomu, kdy obchodník v kamenném obchodě žádá zákazníka o platbu (e-shop zakládá platbu v Apple Pay), zákazník vytahuje vybranou kartu z peněženky (zákazník se biometricky ověřuje na iPhonu, iPadu nebo Apple Watch), předává ji obchodníkovi (Apple Pay posílá obchodníkovi šifrované platební údaje) a následně se platba autorizuje.

Apple Pay funguje jak v prohlížeči (pouze Safari - platformy Mac OS, iOS), tak v nativních aplikacích pro iOS. Na iOS zařízeních (jak iPhone, tak iPad) může zákazník zaplatit těmi kartami, které má v iPhonu nebo iPadu zavedené. Při platbě na počítači (v Safari) je platba potvrzována na zařízení, které je poblíž počítače. Tím může být iPhone nebo Apple Watch. Zjišťování blízkých zařízení probíhá přes continuity a upřednostňovány jsou hodinky před telefonem. MacBooky s TouchID se obejdou bez potvrzování plateb na telefonu a hodinkách, protože je možné přidat si karty přímo do počítače a potvrzovat platby otiskem prstu.

Pokud má zákazník v Apple Pay více karet, má vždy v průběhu platby možnost si vybrat kartu, kterou chce platit. Interakci mezi zákazníkem a kartami v iOS zařízení (nebo Apple Watch) nemůže ani obchodník, ani platební brána ovlivnit; jedná se o systémové služby iOS a Watch OS. Při volání Apple Pay služeb je možné omezit výběr karet, nicméně tuto funkci nedoporučujeme používat.

Transakce vzešlé z Apple Pay

Apple Pay platba je běžnou karetní platbou ze všech hledisek s výjimkou klientské interakce. Autorizace platby, možnost manuálního uzavření transakce, zaúčtování na nižší částku i vratky probíhají stejně jako u běžných karetních transakcí.

Apple Pay a OneClick

Z platby Apple Pay není možné založit OneClick šablonu. Důvodem je bezpečnostní princip Apple Pay a tzv. karetní tokenizace. V iPhonu nebo v Apple Watch není uloženo číslo karty zákazníka, ale tzv. token. Ten sice "vypadá" jako běžné číslo karty, ale v průběhu autorizace transakce je překládán na původní číslo karty a v ten okamžik je kontrolováno, zda transakce pochází ze zařízení, pro které byl token vytvořen. Proto není možné uložit token na platební bráně a použít jej pro opakované transakce.

Poplatky

Pro obchodníky je Apple Pay zdarma. Apple sice na placení vydělává, ale poplatky si vybírá od vydavatelů karet.

Bezpečnost

Platby Apple Pay jsou zabezpečené plně v souladu se směrnicí PSD2 a požadavkem na silné (dvoufaktorové) ověření klienta. Při potvrzení platby pomocí FaceID, Touch ID nebo na hodinkách Apple Watch probíhá autentizace klienta nahrazující 3D Secure proces. Díky tomu je Apple Pay platba nejen rychlá a pohodlná, ale i bezpečná.

Nákupní data (nákupní košík) pro Apple Pay a platební bránu

Při zakládání transakce do Apple Pay prosím používejte alespoň popis nákupu, v lepším případě i položkový košík. Apple Pay je hlavním místem interakce zákazníka s platbou, místem, kde dává souhlas s provedením platby. Platební bránu zákazník v průběhu Apple Pay platby neuvidí. Proto není (na rozdíl od běžné karetní platby) posílán na platební bránu nákupní košík.

Pozor! Do Apple Pay a následně na platební bránu je nutné poslat stejnou (nebo nižší) částku. Důvodem jsou pravidla silné autentizace klienta dle Směrnice PSD2, která vyžaduje autorizaci (provádí platební brána) na stejnou (nebo nižší) částku než autentizovanou částku (autentizaci provádí Apple Pay).

Implementace - Registrace obchodníka pro Apple Pay

Kromě samotné integrace s platební bránou je nutné registrovat se jako obchodník u Applu a vytvořit dva certifikáty. První certifikát si vytvoříte sami, pro druhý si vygenerujete žádost (certificate request) v systému ČSOB POS Merchant, předáte ji Applu k vytvoření certifikátu a výsledek nahrajete zpět do systému ČSOB POS Merchant. Tento certifikát bude zabezpečovat platební údaje mezi Apple Pay a platební bránou.

Vytvoření Merchant ID

přihlásit se do https://developer.apple.com/
přejít do sekce "Certificates, Identifiers & Profiles"
v sekci "Identifiers / Merchant IDs" registrovat nové merchant ID

Vytvoření žádosti pro "Apple Pay Payment Processing Certificate" v ČSOB POS Merchant

přihlásit se do ČSOB POS Merchant a přejít do sekce "Platební brány"
vyhledat příslušnou platební bránu, pro kterou má být provedena registrace do Apple Pay
u vybrané platební brány kliknout na ikonku "Apple Pay certifikáty" a poté na tlačítko "Nový"
ve formuláři pro vytvoření žádosti (certificate request) vyplnit následující informace:
- Common Name (Název certifikátu) - označení (název), které bude uvedeno ve výsledném certifikátu, doporučujeme zadat hodnotu obsahující Merchant ID
- Email Address - může odpovídat použitému AppleID, pod kterým je obchodník přihlášený do https://developer.apple.com/
- Country Name (stát) - ve formátu "2 letter code", např. "CZ"
- Locality Name (sídlo) - zadejte sídlo (město) obchodníka
- Organization Name (název organizace) - název obchodníka
- Org. Unit Name (název oddělení) - název oddělení/obchodního místa/název e-shopu
po odeslání formuláře vygeneruje platební brána klíč a dále žádost pro vydání certifikátu, v seznamu certifikátů je zobrazen nový záznam, lze stáhnout soubor s žádostí (s příponou .CSR)

Vygenerování "Apple Pay Payment Processing Certificate"

přihlásit se do https://developer.apple.com/
přejít do sekce "Certificates, Identifiers & Profiles"
u příslušného merchant ID zvolit v části "Apple Pay Payment Processing Certificate" možnost "Create Certificate"
provést upload .CSR souboru, který obchodník vytvořil v předchozí části v ČSOB POS Merchant
provést download vygenerovaného certifikátu - jedná se o soubor s příponou .CER

Nahrání a aktivace "Apple Pay Payment Processing Certificate" v ČSOB POS Merchant

přihlásit se do ČSOB POS Merchant a přejít do sekce "Platební brány"
vyhledat příslušnou platební bránu, pro kterou má být provedeno nahrání "Apple Pay Payment Processing Certificate" do Apple Pay
u vybrané platební brány kliknout na ikonku "Apple Pay certifikáty", vyhledat v seznamu certifikátů příslušný záznam a provést nahrání souboru s příponou .CER z předchozí části
provést aktivaci vybraného certifikátu v ČSOB POS Merchant (vždy může být aktivní pouze jeden certifikát, aktivní certifikát musí odpovídat platnému "aktivnímu" certifikátu evidovanému v rámci https://developer.apple.com/)

Výše uvedený postup zaručí bezpečné vygenerování klíče, který bude použit na straně platební brány k dešifrování payloadu obsahujícího údaje pro autorizaci Apple Pay transakce. Pouze platební brána jako vlastník klíče bude moci payload dešifrovat a provést autorizaci.

Upozornění: Certifikát má dobu platnosti 25 měsíců, bude jej tedy potřeba před uplynutím doby platnosti nahradit novějším.

Ověření domény (integrace Apple Pay na eshopu obchodníka)

u merchant ID vytvořeného v rámci https://developer.apple.com/ zvolit možnost "Add domain" v části "Apple Pay Payment Processing on the Web"
zadat doménu odpovídající e-shopu obchodníka
provést download souboru apple-developer-merchantid-domain-association.txt a umístit jej do odpovídajícího adresáře .well-known v rootu webserveru
provést verifikaci https://developer.apple.com/ (Apple ověří, že na zadané doméně je přístupný apple-developer-merchantid-domain-association.txt soubor a provede ověření jeho konzistence)

Upozornění: výše popsané ověření domény, ze které lze platit pomocí Apple Pay, bude nutné periodicky obnovovat, má omezenou platnost.

Vytvoření "Apple Pay Merchant Identity Certificate"

Níže uvedený postup zaručí bezpečné vygenerování klíče a vystavení klienstkého certifikátu (Apple Pay Merchant Identity Certificate), který bude použit na straně obchodníka k navázání https spojení na servery Apple pro získání Apple Pay Session.

obchodník si vygeneruje certificate request, např. pomocí příkazu

 openssl req -new -newkey rsa:2048 -nodes -keyout merchant_identity.key -out merchant_identity.csr

u merchant ID vytvořeného v předchozí části zvolit možnost "Create Certificate" v části "Apple Pay Merchant Identity Certificate"
provést upload souboru merchant_identity.csr vytvořeného v prvním kroku
provést download vygenerovaného "Apple Pay Merchant Identity Certificate" (soubor s příponou .CER, v dalším popisu je používán název merchant_identity.cer)
soubory merchant_identity.key a merchant_identity.cer nastaví obchodník v konfiguraci e-shopu tak, aby pomocí nich bylo možné provést https spojení pomocí klientského certifikátu na servery Apple pro získání Apple Pay Session, viz dále.

Upozornění: Certifikát má dobu platnosti 25 měsíců, bude jej tedy potřeba před uplynutím doby platnosti měnit. "Apple Pay Merchant Identity Certificate" je použitý jen na straně obchodníka, platební brána jej pro applepay@shop nepotřebuje a nijak s ním nepracuje.

Integrace Apple Pay do e-shopu obchodníka

Apple umožňuje integrovat Apple Pay do e-shopu obchodníka buď pomocí Payment Request API (určeno pro iOS 11.3 a vyšší), nebo pomocí Apple Pay JS (pro iOS 10 a vyšší), volba konkrétního frameworku je na obchodníkovi, v případě Payment Request API se doporučuje implementovat Apple Pay JS jako fallback scénář. Viz detailní informace.

Ukázka integrace Apple Pay JS je k dispozici na https://applepaydemo.apple.com/ - je zde uveden detailní popis integrace obslužného javascriptu pro Apple Pay platbu. Obchodník musí na straně e-shopu v rámci obslužného js nastavit parametry platby (cena, košík, akceptované karty apod.) a dále musí naimplementovat dva endpointy pro založení Apple Pay Session a pro autorizaci transakce.

Implementace endpointu pro založení Apple Pay Session

Obchodník implementuje na straně e-shopu endpoint pro založení Apple Pay Session. Provede https požadavek na validationUrl získanou z requestu (volá se na server Apple, který provede validaci požadavku a vytvoří Apple Pay Session), pro ustanovení spojení je vyžadován klientský certifikát (viz "Apple Pay Merchant Identity Certificate"). Viz také Apple dokumentace.

Implementace endpointu pro poslání autorizačního požadavku

Obchodník implementuje na straně e-shopu endpoint, přes který provádí zpracování autorizačního požadavku. Přijatá data ve formátu JSON mají následující strukturu (hodnoty jednotlivých atributů jsou pro přehlednost zkráceny):

{
  "paymentData": {
    "version":"EC_v1",
    "data":"zDwclQ1....",
    "signature":"MIAGCSqGSI...",
    "header": {
      "ephemeralPublicKey":"MFkwEwY...",
      "publicKeyHash":"bHAaZK2k0SM...",
      "transactionId":"5324b499fab7..."
    }
  },
  "paymentMethod": {
    "displayName":"MasterCard 1234",
    "network":"MasterCard",
    "type":"debit"
  },
  "transactionIdentifier":"5324B499F..."
}

Obchodník vezme obsah parametru paymentData ...

{"version":"EC_v1","data":"zDwclQ1....","signature":"MIAGCSqGSI...","header": {"ephemeralPublicKey":"MFkwEwY...","publicKeyHash":"bHAaZK2k0SM...","transactionId":"5324b499fab7..."}}

... zakóduje jej do Base64 a přepošle na platební bránu ČSOB. Volá přitom nejprve metodu applepay/init (založení transakce), poté metodu applepay/start (kde v parametru payload předává paymentData zakódovaná do Base64), viz specifikace Apple Pay eAPI metod.

Platební tlačítko ČSOB a Poštovní spořitelny

Platební tlačítko umožňuje platbu převodem z účtů ČSOB a Poštovní spořitelny, ke které ale na rozdíl od běžného převodu získává obchodník okamžitou garanci platby (bez ohledu na denní či noční dobu). Z pohledu zpracování platby e-shopem je tak platba tlačítkem velice podobná platbě kartou. V reálném čase získává obchodník informaci o tom, zda byla/nebyla platba autorizována a vypořádání platby na účet obchodníka probíhá následující bankovní den.

Oproti pouhému poskytnutí bankovních údajů k platbě objednávky zákazníkovi (typicky číslo účtu a variabilní symbol) má platební tlačítko ještě jednu nespornou výhodu - inicializace platby probíhá automaticky a zákazník nemá po celou dobu možnost změnit platební údaje (nemůže se tak splést a v platebních údajích udělat chybu).

Používáte-li již nyní eAPI platební brány ČSOB (i v jakékoli verzi nižší než 1.7), je pro vás použití platebního tlačítka velice jednoduché:

Životní cyklus platby je stejný, jako při platbě kartou a tento životní cyklus platby se od verze eAPI 1.0 nezměnil. Veškerá logika e-shopu, odvozená z životního cyklu platby, není přidáním platebního tlačítka jakkoli dotčena. V případě, že jste dosud používali platební tlačítka ČSOB a Poštovní spořitelny prostřednictvím systému PaySec, můžete PaySec API ze svého systému odebrat a platební tlačítka obsluhovat přes eAPI platební brány.
Vypořádání transakcí je stejné jako v případě karet. Transakce platebním tlačítkem dostanete i na stejném výpisu.
Nechcete-li přímo implementovat platební tlačítko do svých stránek, nemusíte technicky na e-shopu dělat nic. Stačí si nechat v bance aktivovat platbu platebním tlačítkem a vaši zákazníci budou moci platbu tlačítkem vybrat na platební bráně.
Platbu tlačítkem lze zahájit přímo z e-shopu, aniž by zákazník musel jít přes platební bránu. Máte-li již naimplementované eAPI, stačí doplnit implementaci o jedno nové volání (button/init) dle API specifikace.

Jak probíhá transakce platebním tlačítkem - platba na bráně?

Po běžném přesměrování zákazníka z e-shopu na platební bránu si zákazník vybere platební tlačítko jako způsob, kterým chce zaplatit. Po kliku na tlačítko přesměruje platební brána zákazníka do internetového bankovnictví ČSOB nebo Poštovní spořitelny (podle toho, kterou bankovní značku zákazník používá).

Zákazník se přihlásí do elektronického bankovnictví (pomocí uživatelského jména a hesla dle pravidel konkrétního systému s potvrzením SMS kódem nebo aplikací ČSOB Smart klíč. Po přihlášení se zákazníkovi přímo otevře předvyplněný příkaz, ve kterém může změnit jen nedůležité údaje (např. si může k platbě napsat poznámku). Platbu zákazník podepíše SMS kódem, čipovou kartou nebo aplikací ČSOB Smart klíč a následně je automaticky přesměrován zpět na platební bránu. Po vyhodnocení transakce, které trvá několik vteřin, je zákazník přesměrován zpět do e-shopu. Pokud se platba tlačítkem nepovede, zůstává zákazník na platební bráně, kde může zaplatit i jiným způsobem (platební kartou nebo peněženkou MasterPass).

Jak probíhá transakce platebním tlačítkem - platba přímo v e-shopu?

Přímá integrace platebních tlačítek do e-shopu nabízí rychlejší a pohodlnější platbu pro zákazníka. Samotný proces platby v elektronickém bankovnictví je stejný jako v případě platby tlačítkem umístěným na bráně (přesměrování do elektronického bankovnictví, podpis platby a návrat). Samotná platební brána ale do platebního procesu vstupuje pouze na pozadí a zákazník vstupuje do elektronického bankovnictví přímo z e-shopu. Pro implementaci tlačítek přímo do e-shopu je použita nová API metoda button/init dle popisu ve specifikaci API. Samotná platební tlačítka pro umístění do e-shopu naleznete společně s logy ostatních platebních metod zde.

Platba tlačítkem na mobilu a tabletu

Platbu tlačítkem na smartphonu nebo tabletu dokáže zjednodušit aplikace mobilního bankovnictví ČSOB SmartBanking nebo SmartBanking Poštovní spořitelny. Platí-li zákazník na mobilním zařízení, nabídne mu brána dokončení platby v běžném elektronickém bankovnictví nebo ve SmartBankingu. Platební brána zajistí zpracování platby i přesměrování zákazníka z aplikace SmartBanking na návratovou URL, specifikovanou obchodníkem.

Vypořádání plateb a výpisy

Transakce platebními tlačítky, které proběhly v rámci jednoho dne, budou na váš účet obchodníka připsány následující bankovní den. Platby tlačítkem jsou součástí stejných výpisů jako platby karetní. Způsob vypořádání je tedy stejný jako u karet a umožňuje provozovat v e-shopu jen jednu párovací logiku pro všechny platební metody nabízené ČSOB platební bránou.

Návraty plateb

Návraty plateb se provádějí na běžný účet klienta, ze kterého bylo placeno. Nemusíte je provádět ručně v bance - stejně jako v případě platebních karet se transakce vrací prostřednictvím platební brány a její funkce /payment/refund. Vůči jedné transakci můžete poslat více vratek, nicméně vždy jen do výše původní transakce.

Platební tlačítko technicky

Platbu pomocí platebního tlačítka ČSOB / Poštovní spořitelny přímo z e-shopu bez přesměrování na bránu označujeme dále jako pt@shop. Po kliknutí na platební tlačítko v e-shopu je zákazník přesměrován na Internetové bankovnictví ČSOB nebo Poštovní spořitelny. Následně provede přihlášení do IB a potvrdí platbu. Poté je přesměrován na platební bránu ČSOB, kde je provedeno dokončení platby, zobrazení výsledku a následně přesměrování zpět na e-shop obchodníka.

Pro mobilní zařízení je výše popsané chování poněkud odlišné: zákazník je po kliknutí na platební tlačítko přesměrován nejprve na rozcestník na platební bráně, kde má možnost zvolit, zda chce pro provedení platby použít Internetové bankovnictví ČSOB / Poštovní spořitelny anebo zda se má otevřít Smartbanking mobilní aplikace dané banky.

Pro pt@shop je doplněna do eAPI od verze v1.7 následující operace:

Operace	Popis
`button/init`	získání parametrů pro přesměrování na IB ČSOB / Poštovní spořitelny nebo na rozcestník pro výběr mezi Smartbanking aplikací nebo Internetovým bankovnictvím ČSOB / Poštovní spořitelny

Upozornění: autorizované transakce platebním tlačítkem jsou automaticky zaúčtované, nelze volat operaci payment/reverse, pro vrácení je možné použít pouze operaci payment/refund.

Vložení platebního tlačítka ČSOB / Poštovní spořitelny

Do příslušné části html stránky e-shopu je potřeba vložit odkazy na platební tlačítka ČSOB / Poštovní spořitelny. Níže uvedené příklady ukazují linkování české verze tlačítka ČSOB v rozměrech 160x36 a anglické verze tlačítka Poštovní spořitelny ve velikosti 290x64. Podrobnější popis je uveden v článku věnovaném brandingu platebních metod.

<a href="/my-eshop/payment-button-handler-csob">
  <img src="https://platebnibrana.csob.cz/images/pay-csob-cz-160x36.png" alt="Okamžitá platba ČSOB">
</a>

<a href="/my-eshop/payment-button-handler-era">
  <img src="https://platebnibrana.csob.cz/images/pay-era-en-290x64.png" alt="Okamžitá platba Poštovní spořitelny">
</a>

Endpoint pro obsloužení kliknutí na platební tlačítko

Obchodník si na straně e-shopu implementuje obsloužení kliknutí na příslušné platební tlačítko, ve výše uvedeném příkladu je to endpoint pro GET /my-eshop/payment-button-handler-csob a endpoint pro GET /my-eshop/payment-button-handler-era.

Obchodník zavolá na e-shop serveru "voláním zadem" operaci button/init - je odpovědný za seskládání potřebných parametrů, podpis požadavku, poslání požadavku na platební bránu, následné přijetí odpovědi, ověření podpisu a provedení redirectu přes prohlížeč zákazníka.

Mall Pay

Proč nabízet platbu Mall Pay Vašim zákazníkům?

Platba Mall Pay je bezpečná platba pro zákazníka, navíc zcela zdarma. Nahrazuje dobírku a pomáhá odstraňovat obavy zákazníků z online nákupů. Zákazník si metodu vybírá v košíku na e-shopu mezi ostatními platebními metodami. Mall Pay může být zobrazen i dříve, např. na produktovém detailu. Zákazník si tedy volí platbu Mall Pay, spustí se automatické a pro zákazníka neviditelné ověření jeho bonity. V případě zamítnutí je mu okamžitě nabídnuta jiná platební metoda, se kterou objednávku může dokončit. V naprosté většině případů je ale jeho žádost schválena a on přechází do prostředí Mall Pay, kde objednávku dokončí. Zákazník nijak nepřijde do kontaktu s platební bránou, která v tomto případě pouze zajišťuje výměnu informací mezi obchodníkem a Mall Pay. Brána zajišťuje jen samotný settlement platby důležitý pro obchodníka. Zákazník přebírá nákup dle zvoleného typu dopravy (na poště, od dopravce), do 14 dnů pak hradí objednávku v zákaznické zóně Mall Pay. Platbu je možné provést převodem, kartou či platebním tlačítkem.

Obecné podmínky platby Mall Pay

Platba Mall Pay je umožněna jen zletilé fyzické osobě, která není omezena na svéprávnosti;
Zákazník nákupem zboží na e-shopu uzavírá kupní smlouvu s obchodníkem („Kupní smlouva“) ve smyslu příslušných ustanovení zákona č. 89/2012 Sb., Občanský zákoník, ve znění pozdějších předpisů;
Maximální limit na první nákup je 5 000 Kč, další nákupy jsou maximálně do 15 000 Kč;
Nejprve je nutné uhradit první nákup, aby zákazník mohl neomezeně nakupovat do výše svého limitu a to i opakovaně včetně více nákupů z různých e-shopů ve stejnou chvíli

User Experience

První objednávka s Mall Pay: Zákazník může mít pouze jednu nezaplacenou objednávku. Splatnost objednávky je vždy 16 nebo 14 dní od odeslání/doručení zboží. Zákazníkovi datum splatnosti a platební instrukce průběžně sdělujeme.

Druhá a další objednávky s Mall Pay: Zákazník může mít libovolný počet objednávek do výše svého přiděleného nákupního limitu. Splatnost objednávky je vždy 16 nebo 14 dní od odeslání/doručení zboží. Platit je možné za všechny objednávky pod jedním variabilním symbolem. Lhůta pro vrácení zboží zůstává zákonem daných 14 dní od doručení zboží.

Klientská nákupní zóna Mall Pay: Už při prvním využití služby Mall Pay zákazník získá přístup do zabezpečeného prostředí, kde má přehled o veškerých svých objednávkách, při kterých si jako platební metodu zvolil Mall Pay. Zákazník si může založit Mall Pay účet zdarma zadáním svého jména, příjmení, e-mailu a telefonního čísla na registrační stránce. Na zadaný e-mail přijde po registraci odkaz na dokončení registrace, kde si zákazník zvolí své přístupové heslo do Mall Pay účtu. E-mailová adresa slouží ke komunikaci se zákazníkem, a také jako přihlašovací jméno. Telefonní číslo slouží k autorizaci nákupů a ke komunikaci se zákazníkem. Pro vstup do zabezpečené Klientské zóny si zvolí zákazník své tajné a specifické heslo, verifikuje své tel. číslo, pokud ho neznáme z předchozí objednávky.

Self-care zóna umožňuje zákazníkovi vidět:

přehled Mall Pay plateb/objednávek (detail produktu, informace)
finanční hodnotu objednávek
termíny splatnosti, platební instrukce
osobní údaje (e-mail, telefon, nacionále, fakturační nebo doručovací adresy)
aktuálně odsouhlasené a platné VOP
různé marketingové akce včetně refferal programu a odměn (sbírání bodů za nákupy)

Proč je Mall Pay zajímavá platební metoda pro váš e-shop?

Platební metoda Mall Pay umožňuje obchodníkům prodat zboží i nerozhodnutým zákazníkům bez rizika za případné pozdější neuhrazení zboží. Toto riziko na sebe bere Mall Pay formou postoupení pohledávky od obchodníka. Obchodník umožní platbu metodou Mall Pay na svých webových stránkách. Pokud ji zákazník využije a je schválen na straně Mall Pay, je pak obchodníkovi připsána platba do dvou pracovních dnů od obdržení informace o odeslání nebo doručení. Případné reklamace nebo vrácení zboží je pak řešeno standardním způsobem jako u ostatních nákupů a platebních metod. Další výhodou této platební metody je její začlenění vedle ostatní platební metody z pohledu integrace a následného vypořádání. Pro komunikaci a předávání stavů je použito standardní eAPI platební brány. Úhrady transakcí vám pošleme na bankovní účet stejně jako například karetní platby, výpisy mají stejný formát i datovou strukturu. I díky tomu můžete Mall Pay jednoduše integrovat do finančních procesů v e-shopu.

Finanční principy platební metody Mall Pay

Odkup pohledávky

Pohledávka je uzavřená Kupní smlouva mezi Obchodníkem a Zákazníkem;
E-shop může postupovat na Mall Pay Pohledávku z každé uzavřené Kupní smlouvy, kterou Mall Pay schválí;
Schválení pohledávky ze strany Mall Pay je příslib budoucí platby vůči Obchodníkovi, pokud dojde k oznámení logistického stavu objednávky;
Pohledávky jsou propláceny Obchodníkovi v rámci denního vyúčtování od platební brány ČSOB, Mall Pay zahrnuje do vyúčtování pohledávky 2 pracovní dny po oznámení logistického stavu objednávky (expedice nebo doručení objednávky);
Pohledávka je proplácena celá, tj. včetně dopravy, doplňkových služeb, případně slev a poukazů, obchodníkovi je tedy částka za objednávku splacena v plné výši;
Mall Pay garantuje proplacení pohledávek a bere na sebe riziko jejich nezaplacení zákazníkem.

Nastavení zahrnutí do vyúčtování dle logistických stavů

Logistické stavy jsou pro platbu Mall Pay momentem, kdy postoupené pohledávky zahrnuje do vyúčtování. Logistickým stavem rozumíme moment expedice (moment, kdy nákup/zásilka odchází ze skladu obchodníka, nebo moment, kdy dochází k předání zásilky dopravci) nebo moment doručení zásilky zákazníkovi. Předávání logistické informace je ukotveno ve smluvním nastavení. Obchodník se tak tímto zavazuje, že tuto informaci bude přes platební bránu předávat do Mall Pay.

Doporučení pro vztah vyúčtování a postupování pohledávek

Pro většinu obchodníků je složité sdílet tracking zásilek od svých dopravců, proto si naši stávající partneři volí logistický stav na moment expedice (stav Odesláno). Pokud ale obchodník umí předat logistický stav Doručeno (předání zásilky zákazníkovi, ať už přes výdejní místo nebo napřímo od dopravce), je tento stav přívětivější.

Moment doručení a následně postoupení pohledávky od obchodníka je přívětivý především ze zákaznického pohledu. Lze se tak vyhnout zákaznickým negativním zušenostem, jako jsou například nevyzvednutí zásilky nebo storno objednávky, i když už byla zásilka expedovaná. Pokud takové situace totiž nastanou a moment fakturace je nastaven na expedici ze skladu, Mall Pay odkupuje pohledávku a obchodník se pak musí následně finančně vypořádat s Mall Pay.

Vratky a reklamace

Informace o nevyzvednutém, vráceném nebo reklamovaném zboží lze zpracovat přes funkcionalitu mallpay/refund platební brány. Vypořádání vratek se zpracovává na úrovni denního vyúčtování platební brány:

U nevyzvednutých, vrácených nebo reklamovaných objednávek obchodník neodesílá peníze, ale ponižuje se proplacená částka za přijaté platby v rámci denního vyúčtování;
Finanční prostředky v rámci mallpay/refund transakce mohou být ponížené o poštovné, balné a jiné - tj. vratka může být částečná a vracená částka se nemusí rovnat celkové částce transakce (výši pohledávky);
Platební brána ČSOB o této skutečnosti informuje Mall Pay;
V případě Mall Pay platby nesmí e-shop nikdy vrátit finanční prostředky zákazníkovi;
Pokud e-shop nevyužívá funkcionalitu Refund, pak vratky, reklamace a nevyzvednuté zásilky řeší manuálním procesem přes admin POS Merchant.

Storno, vratky & reklamace - Best Practices

Zákazník žádá storno objednávky nebo storno položky: Zákazníci mají samozřejmě možnost stornovat položky z objednávky, stejně jako obchodník, pokud se stane, že nějaké zboží není skladem. Obchodník by tuto informaci měl předat přes platební bránu ČSOB do Mall Pay, jedině před momentem expedice (v případě storna položky). Obchodník pak technicky volá storno na objednávku. Při „částečném vyskladnění“ obchodník předává informaci, které položky expedoval nebo doručil.

Zákazník zboží vracel, ale objednávku už hradil na Mall Pay: Tato situace může nastat, jakmile nám ale obchodník předá informaci o vrácení a finančně se s Mall Pay vyrovná, pak na objednávce z pohledu zákazníka vzniká přeplatek. Zákaznické centrum služby Mall Pay kontaktuje zákazníka s touto informací, vyžádá si od něj číslo účtu a finanční oddělení Mall Pay platbu posílá zpět zákazníkovi.

Zákazník si zásilku nepřevzal: V případě, že si zboží zákazník nevyzvedne, zásilka by se měla vrátit zpět do e-shopu, který považuje věc za standardní vrácení. Jelikož za Mall Pay odchází transakční komunikace na zákazníka s připomínkou o blížícím se datu splatnosti, zákazník zpravidla kontaktuje Mall Pay s touto informací. Mall Pay si skutečnost ověří s obchodníkem a objednávku interně upraví tak, aby zákazníkovi už komunikace neodcházela, následně čeká na potvrzení informace o Vrácení a finančním vyrovnání mezi Mall Pay a obchodníkem.

Vyúčtování provize

Jednou měsíčně fakturuje Mall Pay e-shopu poplatek za využití služby, který je počítán jako % z objemu plateb.
Poplatek je domluven individuálně s obchodníkem a zanesen do ACQ Smlouvy o akceptaci platebních karet a dalších platebních metod.
Rozdíl mezi účtováním za využití služby Mall Pay a za využití platební brány je ten, že platební brána si poplatky z karetních transakcí a dalších operací strhává automaticky a na účet obchodníka připisuje čistou částku bez poplatků. Poplatek za využití služby Mall Pay je obchodníkem hrazen až na základě vystavené faktury společnosti Mall Pay, tedy běžným příkazem k úhradě.
Fakturu zašleme na vámi zadaný kontakt (zpravidla finanční oddělení vaší společnosti).

Doklady a další náležitosti

Zákazník dostává od e-shopu fakturu za zboží, kopii faktury může e-shop manuálně předávat do administrativního rozhraní Mall Pay;
Zákazník hradí objednávky pod VS, který mu sděluje Mall Pay (transakční e-maily), informace k úhradě najde přímo ve svém zákaznickém účtu v Mall Pay;
V případě, že zákazník objednávku nebo její část vrací (odstupuje od kupní smlouvy do 14 dní) nebo reklamuje, pak e-shop vystavuje tzv. Dobropis (účetní doklad oproti původní faktuře).

Náležitosti faktury

a) Na dokladu je vyznačeno: Způsob platby: Mall Pay Včetně poznámky: Pohledávka byla postoupena společnosti Mall Pay s.r.o. Bankovní spojení: účet Obchodníka

b) Vyznačená splatnost faktury by měla být +14 dní od doručení nebo +16 dní od data odeslání zboží (v souladu s uzavřenou kupní smlouvou mezi obchodníkem a zákazníkem)

Náležitosti dobropisu

a) Na dokladu je vyznačeno: Způsob platby: Mall Pay Včetně poznámky: Pohledávka byla postoupena společnosti Mall Pay s.r.o. Bankovní spojení: účet Obchodníka Dobropis se vystavuje na jméno zákazníka (stejné jako jméno zákazníka na faktuře).

b) Dobropis by měl být doručen zákazníkovi elektronicky (zpravidla přes e-mail, pokud vratku doručil dopravce přímo na sklad), nebo vydán osobně (pokud zákazník vrací či reklamuje zboží přímo na výdejně). Stejný dobropis je potřeba doručit i do Mall Pay (což lze řešit přes e-mail finance@mallpay.cz nebo ručním nahráním do adminu Mall Pay).

Detailní popis procesu zpracování objednávky a přechody stavů žádosti

Založení žádosti (objednávky) a přesměrování na Mall Pay

Obchodník založí žádost (zákazníkova objednávka) pomocí funkce mallpay/init na eAPI brány. Na rozdíl od ostatních metod musí obchodník předat detailní informace o zákazníkovi (osobní údaje) a jeho nákupu (položky košíku). Platební brána provede tzv. pre-check v systému Mall Pay, který indikuje, zda zákazník platbu Mall Pay umožní či nikoliv. Pre-check odfiltruje například zákazníky, kteří jsou na blacklistu v Mall Pay nebo mají překročené limity (tj. musí splatit část dřívějších nákupů, aby mohli nakupovat dál). Při úspěšném pre-checku se pokračuje v procesu dál a v Mall Pay je úspěšně založena Žádost. Výsledkem založení transakce na bráně a založení žádosti v Mall Pay jsou pro obchodníka přesměrovávací parametry. Obchodník následně přesměrovává zákazníka do platebního prostředí Mall Pay. Od okamžiku založení je transakce ve stavu 2 - "Platba probíhá"

Zpracování žádosti

Zákazník prochází Mall Pay procesem schvalování v prostředí Mall Pay. Obchodník čeká na výsledek, transakce je stále ve stavu 2 - "Platba probíhá". Výsledkem zpracování Žádosti je její schválení nebo zamítnutí systémem Mall Pay. Délka na vyhodnocení žádosti je standardně nastavena v parametrizaci platební metody Mall Pay. Timeout pro možnost dokončení žádosti je nastaven na 12 hodin, tedy po tuto dobu je zákazník schopen se do objednávky vrátit, například pokud mu chybí doplnit nějaké údaje nebo nechce dokončit žádost na mobilu. Obchodník může tuto lhůtu v případě potřeby zkrátit v initu transakce (typicky u rychloobrátkového zboží – potraviny). Většina zákazníků dokončí žádost v řádu desítek sekund, objednávku pouze autorizují SMS kódem, který zasílá Mall Pay.

Schválení, zamítnutí nebo expirace žádosti

Po schválení nebo zamítnutí žádosti je zákazník přesměrován z prostředí Mall Pay přes platební bránu nazpět do e-shopu. V případě zamítnutí nabídněte zákazníkovi jinou platební metodu. V případě schválení přejde transakce do stavu 4 - "platba potvrzena" a obchodník začíná řešit logistiku zásilky – osobní odběr, předání zásilky dopravci, nebo v případě virtuálního zboží/služby přímé dodání. Schválení pohledávky ze strany Mall Pay je příslib budoucí platby vůči Obchodníkovi, pokud dojde k oznámení logistického stavu objednávky. Výsledkem může být také nedokončení žádosti, pokud zákazník objednávku nedokončí (opustí). V takovém případě přejde transakce na platební bráně do stavu 3 („platba zrušena“ pokud zákazník zrušil zpracování Žádosti v Mall Pay a vrátil se do e-shopu), nebo 6 („platba zamítnuta“ pokud zákazník zcela z Mall Pay odešel a žádost po uplynutí časového limitu expirovala). Pokud zákazník zruší zpracování žádosti, je přesměrován do e-shopu. Pokud se zákazník nevrátí do e-shopu před uplynutím životnosti transakce, zjistí si obchodník po uplynutí času životnosti transakcí pomocí funkce payment/status aktuální stav transakce.

Předání logistického stavu

Následně musí obchodník předat platební bráně pomocí funkce mallpay/logistics informaci o vyskladnění nebo dodání nákupu zákazníkovi. Volání obsahuje i identifikaci položek z nákupního košíku. Pokud obchodník dodává pouze část nákupu, identifikuje v logistickém volání položky, které byly skutečně zákazníkovi odeslány nebo dodány. Informaci o logistice může obchodník předávat buď v okamžiku odeslání, nebo při doručení. Tato informace je ukotvena ve smluvním nastavení. Úspěšným předáním informace o odeslání nebo doručení přechází transakce do stavu 7 - "čeká na zúčtování". Obchodník může logistický stav zadat i manuálně v systému ČSOB POS Merchant. Obchodník zvolí, zda odesílá doručeno nebo odesláno (v závislosti na smluvním nastavení s Mall Pay v závislosti na svých logistických možnostech a sledování zásilek od dopravců). Následně platební brána předává tyto informace na Mall Pay. Obchodník může danou objednávku editovat také přímo v Mall Pay backoffice systému a zaznamenat tak logistický stav doručeno/odesláno. V takovém případě tento záznam spustí v Mall Pay proces odkupu pohledávky stejně jako předání logistické informace prostřednictvím Mall Pay API.

Jakmile je transakce uhrazena od Mall Pay a částka transakce je připravena k převodu na účet obchodníka, přechází transakce do stavu 8 - "platba zúčtována".

Rekapitulace stavů transakce pro platební metodu Mall Pay

Zrušení žádosti (objednávky)

Obchodník může žádost Mall Pay zrušit pouze v okamžiku, kdy zákazník mění něco ve své objednávce (počet kusů zboží, způsob doprav) nebo zpravidla tehdy, pokud zjistí, že položky v objednávce nemá skladem a ani je mít nebude (skladová nedostupnost). Žádost o storno objednávky musí obchodník zaslat před zasláním logistického stavu. Zrušení probíhá pomocí funkce mallpay/cancel na eAPI a obchodník bude uvádět povinné důvody zrušení. (viz. technická specifikace).

Vratky a reklamace

Zákazník odstupuje od smlouvy v zákonné lhůtě pro část nákupu
Zákazník odstupuje od smlouvy v zákonné lhůtě pro celý nákup
Zákazník reklamuje zboží jako část svého nákupu
Zákazník reklamuje zboží jako celek

Vratky a reklamace obchodník provádí tak, že tuto informaci předá Mall Pay přes platební bránu a její funkcionalitu tzv. Refund platby. Obchodník volá mallpay/refund pro částečnou nebo úplnou vratku.

Ochrana osobních údajů a GDPR

Pro objednávky s platnou Mall Pay platbou se obchodník i firma Mall Pay s.r.o. stávají správci zákaznických údajů. Zákazník souhlasí s podmínkami VOP obchodníku, ideálně obsahujícími informace o platbě Mall Pay. Mall Pay s.r.o. nikterak nezasahuje do práva na odstoupení od kupní smlouvy, ani do jiných dohod mezi zákazníkem a e-shopem.

Zákazník souhlasí s podmínkami VOP obchodníka, ideálně obsahující informace o platbě Mall Pay.
Doporučujeme obchodníkům zobrazovat zákazníkům VOP i Informační memorandum platby Mall Pay v košíku dle svých možností, ať už přímo při vybrání způsobu platby v košíku, nebo při celkovém potvrzení a dokončení objednávky v košíku obchodníka. Ideálně tedy zakomponovat podmínky služby do svých VOP a URL linkem na ně odkazovat.
Souhlas je v technickém volání nepovinný údaj, pokud nám obchodník klientský souhlas nepředá, brána Mall Pay si požadavek na „přímý“ zákaznický souhlas vyvolá zde.

Link na VOP - obchodní podmínky -> https://mallpay.cz/vseobecne-obchodni-podminky

Link na Informační memorandum -> https://mallpay.cz/informacni-memorandum

Klientská data a data o nákupu

Platba Mall Pay vyžaduje předání následujících údajů o zákazníkovi a nákupu z e-shopu. Obchodník předává:

Informace o zákazníkovi

Jméno a příjmení
E-mail
Telefonní číslo

Informace o objednávce

Číslo objednávky
Celková cena včetně DPH
Celkem DPH rozdělená dle sazeb
Adresa (doručovací a/nebo fakturační, povinná je alespoň fakturační)
Země
Město
Ulice
Číslo domu a PSČ
Typ adresy

Informace o nákupu – pro každou položku

Kód
Název položky
Celková cena za položku
DPH z celkové ceny

Jak Mall Pay efektivně komunikovat na vašem e-shopu?

Nabídka a zobrazení dostupných plateb u obchodníků je různá a variabilní. Platba Mall Pay muže být zobrazena jen textově názvem platby (Mall Pay), logem nebo třeba prodejním claimem platby „Nakoupím teď, zaplatím za 14 dní“, "Zaplatím do 14 dní", "Prohlédnu, platím do 14 dní" a další. Konkrétní claim s námi vždy konzultujte předem. Obchodníkům doporučujeme po integraci platby Mall Pay službu promovat v produktovém detailu, ve způsobech platby a také na homepage obchodníka. Ideálně o platbě vytvořit na svých stránkách i microsite stránku, kde je služba detailněji popsána. S vytvořením stránky rádi pomůžeme, kontaktujte nás na marketing@mallpay.cz.

Na co si dát při implementaci pozor aneb rozdíly mezi Mall Pay a karetními transakcemi

Díky integraci Mall Pay do ČSOB platební brány jsou rozdíly mezi platbou kartou a platbou pomocí odložené platby minimální. Z technického pohledu musí obchodník předávat více dat, z procesního pohledu je pak nutné počítat s delšími lhůtami pro zpracování platby.

Odlišnosti Mall Pay oproti karetní transakci:

Založení transakce pomocí funkce mallpay/init vyžaduje předání informací o zákazníkovi a nákupu;
Transakce může mít životnost až 12 hodin (karta 30 minut) a je možné ji v průběhu zrušit pomocí funkce mallpay/cancel (u karet nelze);
Je nutné poslat informaci o doručení či odeslání nákupu pomocí funkce mallpay/logistics nebo zadáním v ČSOB POS Merchant. Bez informace o doručení / odeslání nebude transakce proplacena!
Ve funkcích mallpay/logistics a mallpay/refund je nutné identifikovat položky nákupu, které byly obsaženy v zakládání transakce funkcí mallpay/init;
Mall Pay má dopad do procesů fakturace dobropisování (viz náležitosti dokladů);
Vratku nákupu, uhrazeného platební metodou Mall Pay není v žádném případě povoleno vrátit jinou cestou než zadáním vratky transakce pomocí funkce mallpay/refund platební brány, nebo do ČSOB POS Merchant;
Úhrady transakcí (pohledávek) jsou na účet obchodníka připsány o jeden až dva dny později než úhrady z platebních karet. Úhrady jsou v plné výši, poplatky nejsou automaticky strhávány. Fakturace poplatků Mall Pay probíhá jednou za měsíc a obchodník hradí fakturu běžným bankovním převodem;
Pokud ve vaší integraci vážete „zaplacení objednávky“ na stav 7 (protože používáte automatické uzavírání karetních transakcí a transakce přeskočí ze stavu 2 přímo do stavu 7), dejte si pozor na to, že stav relevantní v případě Mall Pay je stav 4 „platba potvrzena“ (tedy stejně jako v případě manuálního uzavírání karetních transakcí).

Testování a integrace

Po dokončení integrace karetních funkcí platební brány do e-shopu a provedení integračních testů pokračujte integrací funkcí specifických pro Mall Pay:

mallpay/init pro založení žádosti o Mall Pay platbu
mallpay/logistics pro předání informace o odeslání nebo doručení nákupu
mallpay/cancel pro možnost zrušit Mall Pay platbu v jejím průběhu (před předáním informace o odeslání nebo doručení)
mallpay/refund pro vratku včetně plnění parametrů důvodu vratky

Integraci můžete testovat v integračním prostředí platební brány (iBrána). Zpracování testovacích transakcí neprobíhá přímo v systému Mall Pay, ale v testovacím simulátoru na platební bráně, kde si pro každou testovací transakci můžete vybrat, jak má transakce dopadnout (schválení žádosti, zamítnutí, návrat zákazníka do e-shopu). Otestujte, prosím, vaši integraci na všechny tyto výsledky a alespoň jednu testovací transakci založte a nechte expirovat (pro urychlení testů můžete v tomto případě nastavit minimální hodnotu ttlsec ve volání mallpay/init).

Volání rozhraní eAPI

Pro vývoj a integraci řešení je testovací platební brána pro obchodníky dostupná na adrese https://iapi.iplatebnibrana.csob.cz/.

Migraci na produkční prostředí (po odsouhlasení řešení ze strany banky) lze provést výměnou testovacích klíčů za produkční a přesměrováním api na https://api.platebnibrana.csob.cz/.

Omezení autorizace v integračním prostředí

Aby nedošlo k nechtěné záměně integračního a produkčního prostředí, je v integračním prostředí omezena úspěšná autorizace plateb pouze na testovací karty. V integračním prostředí je autorizace plateb prováděna oproti simulátoru, nelze použít opravdové "živé" platební karty. Simulace zamítnutí platby v autorizaci podle CVC kódu zůstává nezměněna.

Toto omezení minimalizuje způsobené škody v případě, kdy se na "živém e-shopu" nechtěně přepne z produkčního prostředí zpět na integraci.

eAPI vychází z principů REST API, je dostupné přes HTTPS protokol, data jsou posílána v JSON formátu. Jednotlivé operace jsou implementované pomocí následujících HTTP metod:

Metoda volání	Popis
POST	vytvoření transakce
GET	získání aktuálního stavu transakce
PUT	změna stavu transakce

V odpovědích na volání operací eAPI jsou použity následující HTTP status kódy:

Hodnota	Význam	Popis
`200`	OK	požadavek byl úspěšný; standardní odpověď
`400`	Bad Request	požadavek nemůže být vyřízen; chyba syntaxe zápisu nebo adresy
`403`	Forbidden	přístup odepřen
`404`	Not Found	zdroj nebyl nalezen
`405`	Method Not Allowed	požadovaná metoda není podporována
`429`	Too Many Requests	příliš mnoho požadavků
`503`	Service Unavailable	služba je dočasně mimo provoz

Při zpracování požadavku jsou nejprve kontrolovány základní parametry a je ověřen podpis požadavku. V případě chyby při této základní kontrole obsahuje odpověd z hlediska bezpečnosti pouze obecný HTTP status kód (např. 400 Bad Request nebo 403 Forbidden).

Číselník návratových kódů

resultCode	resultMessage
0	OK (operace proběhla korektně, transakce založena, stav aktualizován apod.)
100	Missing parameter {name} (chybějící povinný parametr)
110	Invalid parameter {name} (chybný formát parametru)
120	Merchant blocked (obchodník nemá povoleny platby)
130	Session expired (vypršela platnost požadavku)
140	Payment not found (platba nenalezena)
150	Payment not in valid state (nesprávný stav platby, operaci nelze provést)
160	Payment method disabled (operace není povolena, obchodník si o nastavení musí smluvně zažádat)
170	Payment method unavailable (nedostupost poskytovatele metody, služba není v tomto čase dosažitelná)
180	Operation not allowed (nepovolená operace)
190	Payment method error (chyba ve zpracování u poskytovatele metody)
230	Merchant not onboarded for MasterPass (obchodník není registrovaný v MasterPass)
240	MasterPass request token already initialized (MasterPass token byl již inicializován)
250	MasterPass request token does not exist (nenalezen MasterPass token, nelze dokončit platbu pomocí MasterPass)
270	MasterPass canceled by user (zákazník nedokončil výběr karty/adresy v MasterPass wallet)
500	EET Rejected (EET hlášení bylo odmítnuto FS)
600	MALL Pay payment declined in precheck (operaci `mallpay/init` nelze dokončit z důvodu zamítnutí žádosti v systému MALL Pay)
700	Oneclick template not found (šablona pro platbu na klik nebyla nalezena)
710	Oneclick template payment expired (šablona pro platbu nebyla použita více jak 12 měsíců, platba expirovala)
720	Oneclick template card expired (karta pro šablonu pro platbu na klik expirovala)
730	Oneclick template customer rejected (šablona pro platbu na klik byla zrušena na pokyn zákazníka)
740	Oneclick template payment reversed (šablona pro platbu na klik byla reverzována)
800	Customer not found (zákazník identifikovaný pomocí `customerId` nenalezen)
810	Customer found, no saved card(s) (zákazník identifikovaný pomocí `customerId` byl nalezen, ale nemá žádné dříve uložené karty na platební bráně)
820	Customer found, found saved card(s) (zákazník identifikovaný pomocí `customerId` byl nalezen a má uložené karty na platební bráně)
900	Internal error (interní chyba ve zpracování požadavku)

Podpis požadavku a ověření podpisu odpovědi

K zabezpečení a zajištění důvěryhodnosti komunikace mezi obchodníkem a bránou slouží podepisování volání (a odpovědí) pomocí klíčů, jejichž získání je popsané v části věnované postupu integrace.

Podpisy volání obchodníkem jsou povinné, ověřování podpisů odpovědí brány u obchodníka doporučujeme.

Sestavení podpisu volání

Z dat odesílaných na server sestavíme RETEZEC_ZPRAVY tak, že jednotlivé datové položky seřadíme za sebe v pořadí, v jakém jsou ve specifikaci uvedeny. Pro oddělení jednotlivých položek se použije oddělovač „|“. Do výpočtu zahrneme všechny parametry odeslané v požadavku. Pokud tedy nebude některý nepovinný parametr použit, nebude ani ve výsledném řetězci.

Pokud je položkou zprávy vnořený datový objekt, prostupuje se položkami tohoto objektu. V případě seznamu (např. položky items v inicializaci platby) se do výsledného řetězce vkládají položky ve stejném pořadí, v jakém jsou uvedeny ve zprávě.

Čísla jsou reprezentována v ASCII podobě, znaky jsou zapisované ve své binární reprezentaci (nejsou povoleny entity \uXXXX).

Pro samotný výpočet podpisu se pak použije privátní klíč obchodníka

signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

V případě ověření podpisu na platební bráně u GET operací do podpisu vstupují hodnoty parametrů, které jsou „URL dekódovány“.

Pro podepisování je potřeba použít algoritmus založený na SHA-256. (Pozor, v předchozích verzích eAPI byl použit algoritmus SHA-1). Například v Javě je potřeba použít při inicializaci třídy java.security.Signature algoritmus "SHA256withRSA", v PHP je potřeba použít "OPENSSL_ALGO_SHA256", což je defaultní algoritmus pro funkce openssl_sign() a openssl_verify().

Příklad sestavení podpisu pro požadavek posílaný pomocí metody POST:

V operaci pro založení platby podepisujeme parametry následujícím způsobem:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.8/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20140425131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "cart":[
    {
      "name": "Nákup: vasobchod.cz",
      "quantity": 1,
      "amount": 1789600,
      "description":"Lenovo ThinkPad Edge E540"
    },
    {
      "name": "Poštovné",
      "quantity": 1,
      "amount": 0,
      "description": "Doprava PPL"
    }
  ],
  "description":"Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)",
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"CZ",
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "signature":"base64-encoded-signature-of-payment-request"
}'

RETEZEC_ZPRAVY = "012345|5547|20140425131559|payment|card|1789600|CZK|true|https://vasobchod.cz/gateway-return|POST|Nákup: vasobchod.cz|1|1789600|Lenovo ThinkPad Edge E540|Poštovné|1|0|Doprava PPL|Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)|some-base64-encoded-merchant-data|CZ"

signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Jak je vidět, nepovinný parametr customerId není v požadavku vyplněn, není ani součástí hodnoty RETEZEC_ZPRAVY. Po hodnotě merchantData následuje hodnota parametru language -- bez nutnosti vkládat extra odddělovač | pro nevyplněný parametr.

Při vytváření hodnoty RETEZEC_ZPRAVY nezáleží na pořadí položek v JSON požadavku, určující je pořadí parametrů uvedených v této specifikaci -- viz. příklad umístění parametrů returnUrl a returnMethod.

Příklad sestavení podpisu pro požadavek posílaný pomocí metody PUT:

V operaci pro zařazení transakce do zúčtování podepisujeme parametry merchantId, payId a dttm následujícím způsobem:

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.8/payment/close \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature",
}'

RETEZEC_ZPRAVY = "012345|d165e3c4b624fBD|20140425131559"
signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Příklad sestavení podpisu pro požadavek posílaný pomocí metody GET:

V operaci pro zjištění informací o uloženém zákazníkovi podepisujeme parametry merchantId, customerId a dttm následujícím způsobem:

Přenášené parametry musí být „URL enkódovány“.

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.8/customer/info/012345/cust123%40mail.com/20140425131559/url-encoded-signature

RETEZEC_ZPRAVY = "012345|cust123@mail.com|20140425131559"
signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Postup ověření podpisu odpovědi

Podobně jako u vytvoření podpisu požadavku se pro ověření podpisu odpovědi z jednotlivých položek odpovědi vytvoří RETEZEC_ZPRAVY a pro ověření podpisu se použije veřejný klíč platební brány. Ten lze stáhnout zde z Gitu.

Pro následující odpověď pro založení platby pomocí payment/init

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

bude řetězec pro ověření podpisu následující:

RETEZEC_ZPRAVY = "d165e3c4b624fBD|20140425131559|0|OK|1"

U transakcí ve stavu 4 nebo 7 (odpověď u operací payment/status, payment/close apod.) se posílá i autorizační kód, který je také součástí podpisu:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 4,
  "authCode": "qwFDF32",
  "signature":"base64-encoded-response-signature"
 }

řetězec pro ověření podpisu bude následující:

RETEZEC_ZPRAVY = "d165e3c4b624fBD|20140425131559|0|OK|4|qwFDF32"

Při přesměrování z platební brány zpět na e-shop je součástí odpovědi i parametr merchantData (pokud byl předán v rámci operace payment/init) ...

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "authCode": "qwFDF32",
  "merchantData": "base64-encoded-merchant-data",
  "signature":"base64-encoded-response-signature"
 }

řetězec pro ověření podpisu bude následující:

RETEZEC_ZPRAVY = "d165e3c4b624fBD|20140425131559|0|OK|7|qwFDF32|base64-encoded-merchant-data"

Poznámka: obecně platí, že parametry paymentStatus, authCode a merchantData se přidávají do řetězce pro ověření podpisu, jen pokud jsou vyplněné (např. pro transakci ve stavu 3 nebude vyplněn authCode, ale bude vyplněn parametr merchantData, výsledný řetězec pak bude ve formátu payId|dttm|resultCode|resultMessage|paymentStatus|merchantData).

Přehled eAPI metod

Iniciální integrace na eAPI, ověření podpisu

Pro napojení e-shopu na eAPI proveďte nejprve provolání operace echo. Otestujete si tak podepsání požadavku i ověření podpisu v odpovědi od platební brány. Provolání je možné naimplementovat jak přes GET, tak přes POST HTTP method.

Metoda	Popis
echo	operace pro ověření dostupnosti platební brány, případně pro ověření podpisu zprávy pro snazší integraci

Základní integrace e-shopu na platební bránu

Pro základní integraci e-shopu na platební bránu slouží operace payment/init a payment/process:

Metoda	Popis
payment/init	založení platby na platební bráně
payment/process	přesměrování na platební bránu po předchozí inicializaci platby

Dále je nutné naimplementovat volání následujících operací, pomocí kterých je možné řídit životní cyklus platby:

Metoda	Popis
payment/status	zjištění stavu platby
payment/reverse	operace reverzuje (zruší před odesláním do uzávěrky) již autorizovanou transakci
payment/close	operace zařadí autorizovanou nezaúčtovanou transakci do zúčtování
payment/refund	operace zažádá o plný nebo částečný návrat prostředků nazpět plátci

Integrace metod pro platbu Na klik (oneclick@shop)

Pokud obchodník bude využívat Platbu Na klik, musí naimplementovat následující operace oneclick/init a oneclick/start. Pomocí operace oneclick/echo si obchodník může ověřit stav šablony platby Na klik, například v případě, kdy uživateli zobrazuje stav jeho "registrovaných karet".

Metoda	Popis
oneclick/init	založení platby Na klik na platební bráně
oneclick/start	operace nastartuje autorizaci platby Na klik
oneclick/echo	ověření stavu šablony pro platby Na klik

Integrace metod pro Apple Pay platbu (applepay@shop)

Pro platební metodu Apple Pay je potřeba, aby obchodník implementoval následující dvě operace applepay/init a applepay/start.

Metoda	Popis
applepay/init	založení Apple Pay transakce pro applepay@shop
applepay/start	spuštění autorizace Apple Pay platby

Integrace metod pro MasterPass platbu (mpass@shop)

Pro platbu pomocí MasterPass peneženky v e-shopu jsou k dispozici dva základní scénáře (basic a standard checkout). Obchodník tak naimplementuje operaci masterpass/init pro založení transakce a podle zvoleného scénáře příslušnou sadu operací:

Metoda	Popis
masterpass/init	založení MasterPass transakce pro mpass@shop
masterpass/basic/checkout	získání parametrů pro volání MasterPass wallet pro scénář `basic`
masterpass/basic/finish	dokončení checkoutu a spuštění autorizace platby pro scénář `basic`
masterpass/standard/checkout	získání parametrů pro volání MasterPass wallet pro scénář `standard`
masterpass/standard/extract	dokončení checkoutu, získání potřebných parametrů pro dopočítání ceny pro scénář `standard`
masterpass/standard/finish	spuštění autorizace platby s dopočítanou finální cenou pro scénář `standard`

Integrace platebního tlačítka ČSOB a Poštovní spořitelny (pt@shop)

Pro integraci platebního tlačítka pro platbu převodem z účtů ČSOB a Poštovní spořitelny je nutné, aby obchodník naimplementoval metodu button/init:

Metoda	Popis
button/init	založení platby pro platební tlačítko (pt@shop)

Integrace metod pro MALL Pay platbu (mallpay@shop)

Platební metoda MALL Pay se od předchozích způsobů platby poněkud liší: obchodník sice nejprve založí platbu pomocí mallpay/init a zjišťuje její stav pomocí payment/status, další průběh zpracování je ale odlišný - obchodník může transakci zrušit (mallpay/cancel). Dále poté, co doručil nebo odeslal zboží zákazníkovi, předává na platební bránu logistický stav (mallpay/logistics) a odlišně se provádí i vrácení (mallpay/refund).

Metoda	Popis
mallpay/init	založení Odložené platby na platební bráně pro mallpay@shop
mallpay/logistics	pomocí této operace obchodník předá údaje o doručení nebo odeslání zboží zákazníkovi, případně údaje o zrušených položkách objednávky
mallpay/cancel	pomocí této operace může obchodník zrušit Odloženou platbu
mallpay/refund	provedení vratky částky MALL Pay transakce

Pomocné metody

Následující operace jsou volitelné:

Metoda	Popis
echo/customer	operace pro zjištění informace o uloženém zákazníkovi

Základní metody

Stručný přehled

Metoda	Popis
payment/init	Založení platby na platební bráně.
payment/status	Zjištění stavu platby.
payment/process	Přesměrování na platební bránu po předchozí inicializaci platby.
payment/reverse	Operace reverzuje (zruší před odesláním do uzávěrky) již autorizovanou transakci.
payment/close	Operace zařadí autorizovanou nezaúčtovanou transakci do zúčtování.
payment/refund	Operace zažádá o plný nebo částečný návrat prostředků nazpět plátci.
echo	Operace pro ověření dostupnosti platební brány, případně pro ověření podpisu zprávy pro snazší integraci.
echo/customer	Operace pro zjištění informace o uloženém zákazníkovi.

Tučně uvedené parametry jsou pro volání povinné.

Metoda `payment/init`

POST https://api.platebnibrana.csob.cz/api/v1.8/payment/init

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka 10 číslic.
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
payOperation	String	Typ platební operace. Povolené hodnoty: `payment`, `oneclickPayment`, `customPayment`.
payMethod	String	Typ implicitní platební metody, která bude nabídnuta zákazníkovi. Povolené hodnoty: `card`.
totalAmount	Number	Celková cena v setinách základní měny. Tato hodnota bude zobrazena na platební bráně jako celková částka k zaplacení.
currency	String	Kód měny. Povolené hodnoty: `CZK`, `EUR`, `USD`, `GBP`, `HUF`, `PLN`, `HRK`, `RON`, `NOK`, `SEK`.
closePayment	Boolean	Indikuje, zda má být platba automaticky zahrnuta do uzávěrky a proplacena. Povolené hodnoty: `true` / `false`.
returnUrl	String	URL adresa, na kterou bude klient přesměrován zpět do e-shopu po dokončení platby. Maximální délka 300 znaků. Specifikaci návratových hodnot najdete níže.
returnMethod	String	Metoda návratu na URL adresu e-shopu. Povolené hodnoty `POST`, `GET`. Doporučená metoda je `POST`.
cart	Object	Seznam položek nákupu, který bude zobrazen na platební bráně. Obsahuje položky Item, popis položky viz níže.
merchantData	String	Libovolná pomocná data, která budou vrácena ve zpětném redirectu z platební brány na stránku obchodníka. Mohou sloužit např. pro udržení kontinuity procesu na e-shopu, musí být kódována v BASE64. Maximální délka po zakódování 255 znaků.
customerId	String	Jednoznačné ID zákazníka, který přiděluje e-shop. Maximální délka 50 znaků. Používá se při uložení karty a jejím následném použití při další návštěvě tohoto e-shopu.
language	String	Preferovaná jazyková mutace, která se zobrazí zákazníkovi na platební bráně. Od verze 1.6 povinný parametr. Povolené hodnoty: `CZ`, `EN`, `DE`, `FR`, `HU`, `IT`, `JP`, `PL`, `PT`, `RO`, `RU`, `SK`, `ES`, `TR`, `VN`, `HR`, `SI`.
ttlSec	Number	Nastavení životnosti transakce, v sekundách, min. povolená hodnota 300, max. povolená hodnota 1800 (5-30 min). Pokud je nastaven typ platby `payOperation` na hodnotu `customPayment`, tato životnost transakce `ttlSec` se ignoruje a zákazník je schopen dokončit platbu po celou dobu až 60 dní, nastavenou v parametru `customExpiry`.
logoVersion	Number	Verze schváleného loga obchodníka, které se pro danou transakci zobrazí. Pokud se bude jednat o dosud neschválené logo, použije se aktivní logo obchodníka. Pokud není, použije se defaultní logo platební brány.
colorSchemeVersion	Number	Verze schváleného barevného schématu obchodníka, které se pro danou transakci zobrazí. Pokud se bude jednat o dosud neschválené barevné schéma, zobrazí se aktivní barevné schéma obchodníka, pokud není, zobrazí se defaultní barevné schéma platební brány.
customExpiry	String	Expirace platby na míru, formát YYYYMMDDHHMMSS (volitelný parametr, který je kontrolován pouze v případě, že `payOperation` je nastaven na hodnotu `customPayment`). Zadaná hodnota nesmí být v minulosti. Maximální povolená platnost platby na míru je 60 dní.
signature	String	Podpis požadavku, kódováno v BASE64.

Upozornění: pokud je payOperation nastavena na oneclickPayment nebo na customPayment, ignoruje se předávaný parametr customerId. Při zpracování šablony pro platbu tedy lze zadat v rozhraní platební brány pouze novou kartu, nelze platit dříve uloženou kartou. Podobně u platby na míru - nelze platit dříve uloženými kartami.

item - Položka košíku (objekt cart)

Položky jsou uváděny po řádcích. Každý řádek košíku má název položky, počet ks, celkovou cenu za uvedený počet ks dané položky a nepovinný pomocný popis.

Položka	Typ	Popis
name	String	název zboží, maximální délka 20 znaků
quantity	Number	množství, musí být >=1, celé číslo
amount	Number	celková cena za uvedené množství položek v setinách měny; měna bude automaticky převzata z položky currency celého požadavku
description	String	popis položky košíku, maximální délka 40 znaků

Pozn: pokud je amount=0, zobrazení obsahu košíku na platební bráně uvádí text ZDARMA

POZOR: Od verze v1 musí být v košíku nejméně jedna (například "dobití kreditu") a nejvýše dvě položky, například "nákup na mujobchod" a "poštovné"). Omezení je dáno grafickou úpravou platební brány a v další verzi bude limit položek výrazně posunut.

Příklad požadavku:

{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20190925131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Nákup: vasobchod.cz",
      "quantity": 1,
      "amount": 1789600,
      "description":"Lenovo ThinkPad Edge E540"
    },
    {
      "name": "Poštovné",
      "quantity": 1,
      "amount": 0,
      "description": "Doprava PPL"
    }
  ],
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"CZ",
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty

eAPI vrací pro operace payment/init, payment/status, payment/close, payment/reverse a payment/refund jednotnou sadu parametrů popisujících aktuální stav platebního požadavku, výsledek operace (kód a textový popis) a případně autorizační kód pro úspěšně autorizované požadavky. U jednotlivých volání funkcí jsou již uvedeny pouze příklady návratových hodnot s odkazem na tuto společnou definici.

Položka	Typ	Popis
payId	String	Jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec).
dttm	String	Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
resultCode	Number	Výsledek operace, viz výčet.
resultMessage	String	Textový popis výsledku operace.
paymentStatus	Number	Stav platby, viz životní cyklus transakce, vyplněno v případě, že `resultCode` je `0`.
authCode	String	Autorizační kód platby. Vrací se pouze v případě, že platba je ve stavu Platba potvrzena (4) nebo ve stavu Čekání na zúčtování (7) nebo ve stavu Zúčtováno (8).
customerCode	String	Kód platby na míru pro předání zákazníkovi. Vrací se pouze v opovědi na operaci `payment/init` pro `payOperation` nastavenou na `customPayment` a pouze v případě, že platba je ve stavu Platba založena (1).
statusDetail	String	Detailní stav platby (tzv. mikrostav), obsahuje například důvod zamítnutí platby, možné hodnoty viz číselník, vyplněno v případě, že `resultCode` je `0`.
signature	String	Podpis odpovědi, kódováno v BASE64.

Příklad návratových hodnot pro payment/init -- úspěšně založená transakce:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro payment/init -- chybně založená transakce:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 100,
  "resultMessage":"Missing parameter 'totalAmount'",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro payment/init -- úspěšně založená transakce typu platba na míru:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "customerCode": "E61EC8",
  "signature":"base64-encoded-response-signature"
 }

Metoda `payment/process`

Požadavek obsahuje položky přímo v URL adrese.

GET https://api.platebnibrana.csob.cz/api/v1.8/payment/process/{merchantId}/{payId}/{dttm}/{signature}

Přesměrování na platební bránu po předchozí inicializaci platby. Na rozdíl od ostatních operací eAPI (které se mohou odesílat pomocí jakéhokoli http klienta ze systému obchodníka a vrací návratové hodnoty ve formátu JSON) se v případě této operace musí GET požadavek odeslat z prohlížeče plátce, výsledkem je stránka platební brány.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init)
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

V případě platby na míru pro přechod na platební bránu nelze použít operaci payment/process, platební brána umožní dokončit transakci pouze přes adresu https://platebnibrana.csob.cz/zaplat/{customerCode} obsahující přidělený customerCode. Pro integrační prostředí platí adresa https://iplatebnibrana.csob.cz/zaplat/{customerCode}.

Příklad volání:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.8/payment/process/012345/d165e3c4b624fBD/20190925131559/base64-encoded-request-signature

Server vrací přesměrování na stránku platební brány pro zobrazení výsledku zpracování požadavku ...

HTTP/1.1 303 See Other
Location: https://platebnibrana.csob.cz/pay/vasobchod.cz/6544-4564-sd65111-GF544DS/

V případě korektního zpracování se zobrazí stránka platební brány pro zadání potřebných údajů pro zaplacení, v případě chyby při zpracování (neplatné parametry, chybný podpis požadavku, platba neexistuje apod.) se zobrazí stránka platební brány s popisem chyby.

Return URL - návrat do e-shopu

V tomto místě je vhodné upřesnit, jaké parametry bude obsahovat přesměrování z platební brány zpět na e-shop.

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init doplněné o parametr merchantData. Jsou předány na návratovou adresu e-shopu (parametr returnUrl získaný v payment/init) a to přes prohlížeč plátce pomocí metody POST nebo GET (parametr returnMethod) .

Poznámka: e-shop musí od v1.5 podporovat zpracování návratovych hodnot pomocí metody GET i POST (platební brána provádí redirect podle parametru returnMethod, u některých akcí -- např. zrušení platby uživatelem -- nicméně provede vždy redirect pomocí GET metody).

Příklad návratových hodnot při přesměrování z platební brány na e-shop pomocí metody POST:

Http-Method: POST
Address: https://vasobchod.cz/gateway-return
Payload:
payId=d165e3c4b624fBD&dttm=20190925131559&resultCode=0&resultMessage=OK&paymentStatus=4
&authCode=F7A23E&merchantData=base64-encoded-merchant-data&signature=base64-encoded-response-signature

Poznámka: parametry jsou předávané jako Form URL Encoded data posílané v těle POST požadavku.

Příklad návratových hodnot při přesměrování z platební brány na e-shop pomocí metody GET:

Http-Method: GET
Address: https://vasobchod.cz/gateway-return?payId=d165e3c4b624fBD&dttm=20190925131559&resultCode=0&resultMessage=OK&paymentStatus=4
&authCode=F7A23E&merchantData=base64-encoded-merchant-data&signature=base64-encoded-response-signature

Poznámka: hodnoty parametrů jsou „URL enkódovány“.

Metoda `payment/status`

Požadavek obsahuje položky přímo v URL adrese.

GET https://api.platebnibrana.csob.cz/api/v1.8/payment/status/{merchantId}/{payId}/{dttm}/{signature}

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init)
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

Příklad volání:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.8/payment/status/012345/d165e3c4b624fBD/20190925131559/base64-encoded-request-signature

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/status:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 4,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

Metoda `payment/reverse`

PUT https://api.platebnibrana.csob.cz/api/v1.8/payment/reverse

Operace reverzuje (zruší před odesláním do uzávěrky) již autorizovanou transakci. Při zavolání této funkce na transakci, která již do uzávěrky odešla, se vrací chyba. V takovém případě je pro zrušení transakce potřeba zadat žádost o vrácení prostředků.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init)
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/reverse:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 5,
  "signature":"base64-encoded-response-signature"
 }

Metoda `payment/close`

PUT https://api.platebnibrana.csob.cz/api/v1.8/payment/close

Operace zařadí transakci do zúčtování.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init)
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
totalAmount	Number	celková koncová cena v setinách základní měny; hodnota musí být kladná a zároveň menší nebo rovna původní částce (viz parametr `totalAmount` v operaci `payment/init`)
signature	String	podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Příklad požadavku: (zaúčtování na menší částku)

{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "totalAmount":10000,
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/close:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

Metoda `payment/refund`

PUT https://api.platebnibrana.csob.cz/api/v1.8/payment/refund

Voláním operace je zažádáno o návrat prostředků nazpět plátci. Aplikuje se na již zaúčtované transakce.

Od eAPI v1.5 lze provést tzv. částečný refund vyplněním nepovinného parametru amount. Částečný refund lze provádět opakovaně, přičemž platí, že částka v parametru amount musí být menší než rozdíl původní autorizované částky a sumy doposud provedených (schválených) částečných refundů.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init)
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
amount	Number	požadovaná částka pro částečný refund v setinách základní měny
signature	String	podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Zpracování u této operace je asynchronní, parametr paymentStatus v návratových hodnotách proto obsahuje aktuální stav platebního požadavku (Platba zúčtována), stav platebního požadavku je možné sledovat přes payment/status.

Příklad návratových hodnot pro payment/refund:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 8,
  "signature":"base64-encoded-response-signature"
 }

Metoda `echo`

Pomocná operace, která slouží pro ověření správnosti složeného podpisu požadavku a kontrolu podpisu odpovědi při vývoji aplikace. Operaci je možné volat pomocí metody POST (parametry poslány v těle požadavku ve formátu JSON) nebo pomocí metody GET -- požadavek obsahuje položky přímo v URL adrese : https://api.platebnibrana.csob.cz/api/v1.8/echo/{merchantId}/{dttm}/{signature}

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

Příklad volání pomocí metody POST:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.8/echo \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}'

Příklad volání pomocí metody GET:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.8/echo/012345/20190925131559/base64-encoded-request-signature

Poznámka: hodnoty parametrů musí být „URL enkódovány“.

Návratové hodnoty

Položka	Typ	Popis
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, [viz výčet](Volání rozhraní eAPI#operation-return-code)
resultMessage	String	textový popis výsledku operace
signature	String	podpis požadavku, kódováno v BASE64

Příklad návratových hodnot pro echo:

{
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "signature":"base64-encoded-response-signature"
 }

Metoda `echo/customer`

POST https://api.platebnibrana.csob.cz/api/v1.8/echo/customer

Operace pro zjištění informace o uloženém zákazníkovi.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
customerId	String	ID zákazníka přidělené v e-shopu, maximální délka 50 znaků
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "customerId":"cust123@mail.com",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Položka	Typ	Popis
customerId	String	ID zákazníka přidělené v e-shopu
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, [viz výčet](Volání rozhraní eAPI#operation-return-code)
resultMessage	String	textový popis výsledku operace
signature	String	podpis požadavku, kódováno v BASE64

Příklad návratových hodnot:

{
  "customerId":"cust123@mail.com",
  "dttm":"20190925131559",
  "resultCode": 800,
  "resultMessage":"Customer not found",
  "signature":"base64-encoded-response-signature",
 }

Metody pro OneClick

Stručný přehled

Metoda	Popis
oneclick/echo	ověření stavu šablony pro platby na klik
oneclick/init	založení platby na klik na platební bráně
oneclick/start	operace nastartuje autorizaci platby na klik

Tučně uvedené parametry jsou pro volání povinné.

Metoda `oneclick/echo`

POST https://api.platebnibrana.csob.cz/api/v1.8/oneclick/echo

Operace ověří stav šablony pro platby Na klik. Zjištění stavu šablony doporučujeme použít před nabídnutím platby Na klik v košíku, případně při zobrazení uložených karet v zákaznickém účtu (více informací v obecném popisu funkce platby Na klik). Pro ověření stavu šablony použijte tuto operaci, nevolejte stav prvotní (registrační) transakce.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
origPayId	String	payID oneclick šablony
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "origPayId":"ef08b6e9f2234BC",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Položka	Typ	Popis
origPayId	String	ID oneclick šablony (obsahuje 15-znakový řetězec)
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, viz výčet
resultMessage	String	textový popis výsledku operace
signature	String	podpis odpovědi, kódováno v BASE64

Příklad návratových hodnot pro oneclick/echo - oneclick šablona je aktivní:

{
  "origPayId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/echo - oneclick šablona nenalezena:

{
  "origPayId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 700,
  "resultMessage":"Oneclick template not found",
  "signature":"base64-encoded-response-signature"
 }

Návratové hodnoty relevantní pro operaci oneclick/echo (kódy 700-740) jsou uvedeny v číselníku návratových hodnot.

Metoda `oneclick/init`

POST https://api.platebnibrana.csob.cz/api/v1.8/oneclick/init

Operace založí platbu na klik. Podmínkou je existence autorizované platby (tzv. "šablony pro platbu"), která byla provedena na platební bráně standardním způsobem.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
origPayId	String	PayID dříve vytvořené šablony pro platbu.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka je 10 číslic.
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
clientIp	String	IP adresa zákazníka (jeho prohlížeče) přistupujícího na e-shop obchodníka, formát ipv4 nebo ipv6.
totalAmount	Number	Celková cena v setinách základní měny. Pokud není vyplněno, přebírá se hodnota ze šablony pro platbu. Pokud je `totalAmount` vyplněn, musí být vyplněn také parametr `currency`.
currency	String	Kód měny. Povolené hodnoty: `CZK`, `EUR`, `USD`, `GBP`, `HUF`, `PLN`, `HRK`, `RON`, `NOK`, `SEK`. Pokud není vyplněno, přebírá se hodnota ze šablony pro platbu. Pokud je `currency` vyplněn, musí být vyplněn také parametr `totalAmount`.
merchantData	String	Libovolná pomocná data, která předává obchodník na bránu, musí být kódována v BASE64. Maximální délka po zakódování je 255 znaků.
signature	String	Podpis požadavku, kódováno v BASE64.

Poznámka: z šablony pro platbu se přebírá nastavení closePayment (příznak, zda se platba zařadí do zúčtování).

Příklad požadavku:

{
  "merchantId":"012345",
  "origPayId":"ef08b6e9f2234BC",
  "orderNo":"51966",
  "dttm":"20190925131559",
  "clientIp":"192.0.2.2",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Položka	Typ	Popis
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec)
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, viz výčet
resultMessage	String	textový popis výsledku operace
paymentStatus	Number	stav platby, viz životní cyklus transakce, vyplněno v případě, že `resultCode` je `0`
signature	String	podpis odpovědi, kódováno v BASE64

Příklad návratových hodnot pro oneclick/init -- úspěšně založená transakce:

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro oneclick/init -- zamítnutá transakce (nevalidní vstupní parametry):

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 110,
  "resultMessage":"Invalid 'totalAmount' parameter, must be positive",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Metoda `oneclick/start`

POST https://api.platebnibrana.csob.cz/api/v1.8/oneclick/start

Operace nastartuje autorizaci platby Na klik.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	payID platby Na klik vytvořené v předchozím kroku pomocí operace `oneclick/init`
dttm	String	datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	podpis požadavku, kódováno v BASE64

Poznámka: z šablony pro platbu se přebírá nastavení closePayment (příznak, zda se platba zařadí do zúčtování).

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Položka	Typ	Popis
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec)
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, viz výčet
resultMessage	String	textový popis výsledku operace
paymentStatus	Number	stav platby, viz životní cyklus transakce, vyplněno v případě, že `resultCode` je `0`
signature	String	podpis odpovědi, kódováno v BASE64

Příklad návratových hodnot pro oneclick/start

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "signature":"base64-encoded-response-signature"
 }

Pozn. Výsledek autorizace je potřeba zjistit následným voláním payment/status. Doporučená doba volání je 2-3 vteřiny po volání oneclick/start, pokud je stav platby stále 2 (platba probíhá), doporučujeme periodicky volat v intervalu 5 vteřin (celková doba autorizace závisí na zpracování požadavku v systémech VISA/MC a může být v nejhorším případě až 60 vteřin).

Metody pro Apple Pay

Stručný přehled metod pro Apple Pay (applepay@shop)

Metoda	Popis
applepay/init	založení Apple Pay transakce pro applepay@shop
applepay/start	spuštění autorizace Apple Pay platby

Tučně uvedené parametry jsou pro volání povinné.

Metoda `applepay/init`

POST https://api.platebnibrana.csob.cz/api/v1.8/applepay/init

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka je 10 číslic.
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
clientIp	String	IP adresa zákazníka (jeho browseru) přistupující na e-shop obchodníka, formát ipv4 nebo ipv6.
totalAmount	Number	Celková cena v setinách základní měny. Tato hodnota bude zobrazena na platební bráně jako celková částka k zaplacení.
currency	String	Kód měny. Povolené hodnoty: `CZK`, `EUR`, `USD`, `GBP`, `HUF`, `PLN`, `HRK`, `RON`, `NOK`, `SEK`.
closePayment	Boolean	Indikuje, zda má být platba automaticky zahrnuta do uzávěrky a proplacena. Povolené hodnoty: `true` / `false`.
merchantData	String	Libovolná pomocná data, která předává obchodník na bránu, musí být kódována v BASE64. Maximální délka po zakódování je 255 znaků.
ttlSec	Number	Nastavení životnosti transakce, v sekundách, min. povolená hodnota 300, max. povolená hodnota 1800 (5-30 min).
signature	String	Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"012345",
  "orderNo":"51966",
  "dttm":"20190925131559",
  "clientIp":"192.0.2.2",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty

Položka	Typ	Popis
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec)
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, viz výčet
resultMessage	String	textový popis výsledku operace
paymentStatus	Number	stav platby, viz životní cyklus transakce, vyplněno v případě, že `resultCode` je `0`
signature	String	podpis odpovědi, kódováno v BASE64

Příklad návratových hodnot pro applepay/init -- úspěšně založená transakce:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro applepay/init -- chybně založená transakce:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 100,
  "resultMessage":"Missing parameter 'totalAmount'",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Metoda `applepay/start`

POST https://api.platebnibrana.csob.cz/api/v1.8/applepay/start

Operace nastartuje autorizaci Apple Pay platby.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
payId	String	PayID získané při založení Apple Pay transakce pomocí operace `applepay/init`.
payload	String	Data ve formátu JSON přijatá obchodníkem z Apple Pay (atribut `paymentData` v přijatých datech od Apple Pay). Obchodník kóduje jako BASE64 a následně předává v parametru `payload`.
totalAmount	Number	Celková cena v setinách základní měny. Obchodník může nastavit celkovou cenu, tato hodnota bude poslána do autorizace na platební bráně jako finální celková částka k zaplacení. Pokud není nastavena, přebírá se totalAmount specifikovaný v rámci applepay/init.
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
signature	String	Podpis požadavku, kódováno v BASE64.

Poznámka: nastavení closePayment (příznak, zda se platba zařadí do zúčtování) se přebírá z inicializace transakce.

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"c165e8c4b624fBD",
  "payload":"eyJzaWduYXR1cmUiOiJNRVVDSUNq[…]UWRjdGhGV1hWaUNRSStzK0hkZXYz",
  "dttm":"20190925131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace applepay/init.

Příklad návratových hodnot pro /applepay/start

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190925131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "signature":"base64-encoded-response-signature"
 }

Pozn. Výsledek autorizace je potřeba zjistit následným voláním payment/status. Doporučená doba volání je 2-3 vteřiny po volání applepay/start, pokud je stav platby stále 2 (platba probíhá), doporučujeme periodicky volat každých 5 vteřin (celková doba autorizace závisí na zpracování požadavku v systémech VISA/MC a může být v nejhorším případě až 60 vteřin).

Metody pro platební tlačítko

Stručný přehled

Metoda	Popis
button/init	založení platby pro platební tlačítko (pt@shop)

Tučně uvedené parametry jsou pro volání povinné.

Metoda `button/init`

POST https://api.platebnibrana.csob.cz/api/v1.8/button/init

Založí platbu platebním tlačítkem (pt@shop) a připraví parametry pro přesměrování uživatele z e-shopu na elektronické bankovnictví. Z elektronického bankovnictví je uživatel přesměrován zpět do e-shopu obchodníka přes platební bránu, která zobrazuje výsledek autorizace.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka je 10 číslic.
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
clientIp	String	IP adresa zákazníka (jeho prohlížeče) přistupujícího na e-shop obchodníka, formát ipv4 nebo ipv6.
totalAmount	Number	Celková cena v setinách základní měny. Tato hodnota bude zobrazena na platební bráně jako celková částka k zaplacení.
currency	String	Kód měny. Povolené hodnoty: `CZK`.
returnUrl	String	URL adresa, na kterou bude klient přesměrován zpět do e-shopu. Maximální délka je 300 znaků.
returnMethod	String	Metoda návratu na URL adresu e-shopu. Povolené hodnoty `POST`, `GET`. Doporučená metoda je `POST`.
brand	String	Platební tlačítko, které zákazník zvolil, povolené hodnoty `csob`, `era`.
merchantData	String	Libovolná pomocná data, která budou vrácena ve zpětném redirectu z platební brány na stránku obchodníka. Mohou sloužit např. pro udržení kontinuity procesu na e-shopu, musí být kódována v BASE64. Maximální délka po zakódování je 255 znaků.
language	String	Preferovaná jazyková mutace, která se zobrazí zákazníkovi na platební bráně (platební brána je zobrazena při přechodu z elektronického bankovnictví zpět na e-shop, zobrazuje výsledek autorizace). Povolené hodnoty: `CZ`, `EN`, `DE`, `FR`, `HU`, `IT`, `JP`, `PL`, `PT`, `RO`, `RU`, `SK`, `ES`, `TR`, `VN`, `HR`, `SI`.
signature	String	Podpis požadavku, kódováno v BASE64.

Příklad požadavku

{
  "merchantId":"012345",
  "orderNo":"11345325",
  "dttm":"20140425131559",
  "clientIp":"193.1.2.3",
  "totalAmount":1789600,
  "currency":"CZK",
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "brand":"csob",
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"CZ",
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty

Položka	Typ	Popis
payId	String	jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec)
dttm	String	datum a čas odpovědi ve formátu YYYYMMDDHHMMSS
resultCode	Number	výsledek operace, viz výčet
resultMessage	String	textový popis výsledku operace
paymentStatus	Number	stav platby, viz životní cyklus transakce, vyplněno v případě, že `resultCode` je `0`
redirect	Object	struktura obsahující potřebné parametry pro přesměrování na elektronické bankovnictví
signature	String	podpis odpovědi, kódováno v BASE64

redirect - parametry pro přesměrování

Položka	Typ	Popis
method	String	Typ HTTP metody, povolené hodnoty jsou `GET`, `POST`.
url	String	URL pro přesměrování.
params	Map	Vyplněno pouze v případě přesměrování pomocí `POST`, mapa obsahující key-value hodnoty, do řetězce pro ověření podpisu odpovědi se vkládají pouze "value" hodnoty (bez klíčů) v pořadí, v jakém přijdou v odpovědi.

Příklad návratových hodnot

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus":1,
  "redirect": {
    "method":"GET",
    "url":"https://platebnibrana.csob.cz/pay/vasobchod.cz/2c72d818-9788-45a1-878a-9db2a706edc5/pt-detect/csob"
  },
  "signature":"base64-encoded-response-signature"
 }

Příklad řetězce pro ověření podpisu odpovědi:

d165e3c4b624fBD|20140425131559|0|OK|1|GET|https://platebnibrana.csob.cz/pay/vasobchod.cz/2c72d818-9788-45a1-878a-9db2a706edc5/pt-detect/csob

Metody pro Mall Pay

Stručný přehled

Platební metoda Mall Pay používá API metody mallpay/init pro založení transakce na bráně a mallpay/logistics pro předání stavu doručování zásilky na platební bránu. Zrušení transakce lze provést pomocí metody mallpay/cancel, částečnou nebo úplnou vratku částky transakce lze provést pomocí metody mallpay/refund. Pro zjištění stavu platby slouží obecná API funkce payment/status.

Zpracování Mall Pay platby probíhá na platební bráně Mall Pay, tj. zákazník je z e-shopu přesměrován na Mall Pay. Parametry pro přesměrování jsou výsledkem volání mallpay/init. Pokud Mall Pay zákazníka již zná a ví, že pro konkrétní nákup není platba Mall Pay možná, bude volání mallpay/init zamítnuto, zákazník není obtěžován přesměrováním na Mall Pay bránu a obchodník může nabídnout alternativní způsoby platby.

Metoda	Popis
mallpay/init	Založení Odložené platby na platební bráně pro mallpay@shop
mallpay/logistics	Pomocí této operace obchodník předá údaje o doručení nebo odeslání zboží zákazníkovi, případně údaje o zrušených položkách objednávky
mallpay/cancel	Pomocí této operace může obchodník zrušit Odloženou platbu
mallpay/refund	Provedení vratky částky MALL Pay transakce

⚠️ Věnujte, prosím, pozornost zejména tomu, že metoda MALL Pay (na rozdíl od ostatních metod na platební bráně) používá téměř ve všech voláních identifikaci položek nákupu.

Při zakládání transakce (mallpay/init) je nutné identifikovat položky a zákazníka.
Při odesílání/doručování zboží (mallpay/logistics) je nutné identifikovat položky, kterých se odeslání, resp. doručení týká.
Stejně tak při vratce (mallpay/refund) je nutné na bránu odeslat seznam položek, ke kterým se finanční vratka váže.
Pouze funkce mallpay/cancel nevyžaduje identifikaci položek, protože tato funkce ruší celou objednávku.

Změny dokumentu od vydání

[24.2.2020] upraveny délky položek u Mall Pay datových struktur
[4.3.2020] upraven popis totalPrice u položky objednávky a příklady - cena včetně DPH

Datové struktury

V rámci volání mallpay metod se používají následující základní datové struktury:

address (Adresa)
price (Částka)
vat (Daňová sazba a částka)
order item (Položka objednávky)

Z těchto částí se pro operaci mallpay/init seskládají složitější datové struktury:

customer (Údaje o zákazníkovi)
order (Údaje o objednávce)

Kromě toho se v rámci operací mallpay/logistics a mallpay/refund odkazuje na položky objednávky pomocí datových struktur:

item reference (Reference na položku objednávky)
order reference (Reference objednávky)

V následující části je uveden přehled výše zmíněných základních datových struktur a jejich parametrů včetně příkladu plnění:

Tučně uvedené parametry jsou pro volání povinné.

Datová struktura address (Adresa)

Položka	Typ	Popis
name	String	Jméno, max. délka 40 znaků
country	String	Stát, délka 2 znaky (kód ISO alpha-2)
city	String	Město, max. délka 50 znaků
streetAddress	String	Ulice (část města), max. délka 100 znaků
streetNumber	String	Číslo popisné, max. délka 25 znaků
zip	String	Poštovní směrovací číslo, max. délka 10 znaků
addressType	String	Typ adresy; adresy se vyplňují u objednávky, povolené hodnoty: `DELIVERY` (adresa pro doručení) `BILLING` (fakturační adresa)

Příklad vyplnění fakturační adresy

{
  "addressType":"BILLING",
  "streetAddress":"Radlická 333",
  "city":"Praha 5",
  "zip":"15000",
  "country":"CZ"
}

Datová struktura price (Částka)

Položka	Typ	Popis
amount	Number	Částka v setinách základní měny (např. `12590` odpovídá 125,90 Kč)
currency	String	Měna dle formátu ISO 4217; pro Mall Pay platební metodu povolena pouze `CZK`

Příklad vyplnění částky 125,90 Kč

{
  "amount":12590,
  "currency":"CZK"
}

Datová struktura vat (Daňová sazba)

Položka	Typ	Popis
amount	Number	Částka daně v setinách základní měny (např. `5000` odpovídá 50,00 Kč)
currency	String	Měna dle formátu ISO 4217; pro Mall Pay platební metodu povolena pouze `CZK`
vatRate	Number	Daňová sazba jako celé číslo (hodnota `15` odpovídá 15% sazbě)

Příklad vyplnění 15% daňové sazby 50,- Kč

{
  "amount":5000,
  "currency":"CZK",
  "vatRate":15
}

Datová struktura order item (Položka objednávky)

Položka	Typ	Popis
code	String	Kód položky (interní pro e-shop). Slouží pro lepší identifikaci položky v případě provádění následných operací (`mallpay/logistics`, `mallpay/refund`). Platební brána ani Mall Pay tento kód nevaliduje, max. délka 50 znaků
ean	String	Kód EAN, max. délka 15 znaků
name	String	Název položky, max. délka 200 znaků
type	String	Typ položky. Povolené hodnoty: `PHYSICAL` pro fyzické zboží, které zákazníkovi obchodník doručuje nebo si jej zákazník vyzvedává; `DISCOUNT` použijte, pokud uvádíte slevu jako samostatnou položku na faktuře; `DIGITAL` použijte pro digitální položky, například elektronické licence nebo média; `GIFT_CARD` použijte při prodeji dárkových karet; `STORE_CREDIT` použijte, pokud zákazníkovi prodáváte nebo dáváte dárkovou kartu použitelnou pouze ve vašem obchodě; `SALES_TAX` použijte, pokud uvádíte daně (např. DPH) jako samostatnou položku na faktuře (v českém prostředí se typicky nepoužije); `SHIPPING_FEE` použijte pro dopravné; `INSURANCE` použijte, pokud uvádíte pojištění jako samostatnou položku na faktuře; `FEE` použijte pro ostatní poplatky.
quantity	Number	Množství. Pokud je prázdné, odpovídá hodnotě 1.
variant	String	Varianta produktu (například barva, velikost balení, velikost paměti apod.) - pro iPhone 7 se jedná o "64 GB Space gray" (zákazníkovi se v systému Mall Pay nikde nezobrazuje), max. délka 50 znaků
description	String	Krátký popisek produktu, max. délka 100 znaků
producer	String	Výrobce, max. délka 50 znaků
categories	Array	Seznam kategorií, do kterých lze položku zařadit (může odpovídat kategoriím v e-shopu, zákazníkovi se v systému Mall Pay nikde nezobrazuje).
unitPrice	Object	Jednotková cena jednoho kusu položky, viz datová struktura price, uvedená jako cena včetně daně (DPH). Daň se vyčísluje v samostatném parametru `unitVat`.
unitVat	Object	Jednotková daň za jeden kus položky, viz datová struktura vat
totalPrice	Object	Celková cena položky, viz datová struktura Částka, uvedená jako celková cena za nakupovaný počet kusů položky včetně daně (DPH). Daň se vyčísluje v samostatném parametru `totalVat`.
totalVat	Object	Celková daň za nakupovaný počet kusů položky, viz datová struktura vat.
productUrl	String	URL odpovídající popisu položky v e-shopu, max. délka 250 znaků

Příklad položky objednávky

{
  "code":"X123",
  "name":"iPhone XS",
  "totalPrice": {
    "amount":1452000,
    "currency":"CZK"
  },
  "totalVat": {
    "amount":252000,
    "currency":"CZK",
    "vatRate":21
  }
}

V následující části je uveden přehled výše zmíněných složitějších datových struktur a jejich parametrů včetně příkladu plnění:

Datová struktura customer (Údaje o zákazníkovi)

Položka	Typ	Popis
firstName	String	Křestní jméno zákazníka. Povinné v případě, že `fullName` je prázdné, max. délka 40 znaků
lastName	String	Příjmení zákazníka. Povinné v případě, že `fullName` je prázdné, max. délka 40 znaků
fullName	String	Celé jméno zákazníka (zadávané na rozdíl od `firstName` a `lastName` jako jedna položka) včetně akademických titulů. Povinné pouze v případě, že `firstName` a `lastName` jsou prázdné, max. délka 100 znaků
titleBefore	String	Akademický titul před jménem, max. délka 20 znaků
titleAfter	String	Akademický titul za jménem, max. délka 20 znaků
email	String	E-mailová adresa zákazníka, max. délka 50 znaků
phone	String	Telefonní číslo včetně mezinárodní předvolby (včetně úvodního znaku +), max. délka 16 znaků
tin	String	IČO zákazníka, max. délka 10 znaků
vatin	String	DIČ zákazníka, max. délka 10 znaků

Příklad plnění customer dat (vyplnění oddělených položek pro jméno a příjmení):

{
  "firstName":"Adam",
  "lastName":"Beran",
  "email": "adam.beran@example.com",
  "phone": "+420800300300"
}

Příklad plnění customer dat (vyplnění položky fullName pro jméno a příjmení):

{
  "fullName":"Adam Beran",
  "email": "adam.beran@example.com",
  "phone": "+420800300300"
}

Datová struktura order (Údaje o objednávce)

Položka	Typ	Popis
totalPrice	Object	Celková cena včetně DPH, tuto částku obdrží obchodník na účet, popis viz datová struktura Price.
totalVat	Array	Rozpad celkové ceny na jednu nebo více daňových sazeb, popis viz datová struktura vat.
addresses	Array	Seznam adres. U objednávky je povinná fakturační adresa (typ `BILLING`), nepovinná je doručovací adresa (typ `DELIVERY`). Doporučujeme zasílat navíc doručovací adresu (pokud je odlišná od fakturační).
deliveryType	String	Typ doručení. V případě hodnoty `DELIVERY_CARRIER` je možné doručení upřesnit v parametru `carrierId` nebo `carrierCustom`. Povolené hodnoty: `DELIVERY_CARRIER` (zaslání dopravcem na adresu specifikovanou zákazníkem) `PERSONAL_BRANCH` (osobní vyzvednutí na provozovně e-shopu) `PERSONAL_PARTNER` (osobní vyzvednutí na provozovně distribučního partnera e-shopu) `ONLINE` (elektronické doručení - např. pro elektronické licence, dárkové karty apod.)
carrierId	String	Identifikace dopravce, povolené hodnoty: `CZ_POST_HAND` `CZ_POST_OFFICE` `CZ_POST_OTHER` `PPL` `DPD` `GEIS` `IN_TIME` `TOP_TRANS` `GEBRUDER_WEISS` `LOCAL_COURIER` `TNT` `GLS` `HDS_COMFORT` `HDS_STANDARD` `MALL_DEPOSIT`.
carrierCustom	String	Upřesnění dopravce v případě, že jej nelze specifikovat pomocí `carrierId`.
items	Array	Položky objednávky, popis viz datová struktura order item.

Příklad vyplnění objednávky (jedna položka, uvedena povinná fakturační adresa):

{
  "totalPrice": {
    "amount":1452000,
    "currency":"CZK"
  },
  "totalVat": [{
    "amount":252000,
    "currency":"CZK",
    "vatRate":21
  }],
  "addresses": [{
    "addressType":"BILLING",
    "streetAddress":"Radlická 333",
    "city":"Praha 5",
    "zip":"15000",
    "country":"CZ"
  }],
  "items": [{
    "code":"X123",
    "name":"iPhone XS",
    "totalPrice": {
      "amount":1452000,
      "currency":"CZK"
    },
    "totalVat": {
      "amount":252000,
      "currency":"CZK",
      "vatRate":21
    }
  }]
}

Příklad vyplnění objednávky (dvě položky, každá v jiné daňové sazbě, uvedena povinná fakturační adresa):

{
  "totalPrice": {
    "amount":3047400,
    "currency":"CZK"
  },
  "totalVat": [{
    "amount":522900,
    "currency":"CZK",
    "vatRate":21
  },
  {
    "amount":4500,
    "currency":"CZK",
    "vatRate":15
  }],
  "addresses": [{
    "addressType":"BILLING",
    "streetAddress":"Radlická 333",
    "city":"Praha 5",
    "zip":"15000",
    "country":"CZ"
  }],
  "items": [{
    "code":"A456",
    "name":"Canon EOS 80D",
    "totalPrice": {
      "amount":3012900,
      "currency":"CZK"
    },
    "totalVat": {
      "amount":522900,
      "currency":"CZK",
      "vatRate":21
    }
  },
  {
    "code":"Y987",
    "name":"Fotografická příručka",
    "totalPrice": {
      "amount":34500,
      "currency":"CZK"
    },
    "totalVat": {
      "amount":4500,
      "currency":"CZK",
      "vatRate":15
    }
  }]
}

V následující části je uveden přehled výše zmíněných datových struktur pro mallpay/logistics a mallpay/refund a jejich parametrů včetně příkladu plnění:

Datová struktura item referece (Reference na položku objednávky)

Tato datová struktura se použije pro předání reference na doručené, odeslané nebo zrušené položky objednávky v rámci volání mallpay/logistics anebo pro předání reference na vrácené položky objednávky v rámci volání mallpay/refund. Pozor! Do datové struktury reference na položku objednávky je nutné uvádět stejné parametry položky (code, ean, name, type) jako při zakládání objednávky v datové struktuře OrderItem ve volání mallpay/init. Pokud nebudou stejné, neprojdou v systému Mall Pay validace.

Položka	Typ	Popis
code	String	Kód položky (interní pro e-shop). Slouží pro identifikaci položky objednávky, max. délka 50 znaků
ean	String	Kód EAN, max. délka 15 znaků
name	String	Název položky, max. délka 200 znaků
type	String	Typ položky, povolené hodnoty: `PHYSICAL` `DISCOUNT` `SHIPPING_FEE` `SALES_TAX` `DIGITAL` `GIFT_CARD` `STORE_CREDIT` `FEE` `INSURANCE`.
quantity	Number	Množství. Pokud je prázdné, odpovídá hodnotě 1.

Příklad vyplnění reference na položku objednávky:

{
  "code":"X123",
  "name":"iPhone XS"
}

Datová struktura order reference (Reference objednávky)

Tato datová struktura se použije v rámci volání mallpay/logistics pro předání údajů o celkové ceně doručeného nebo odeslaného zboží včetně rozpadu na daňové sazby a doručených nebo odeslaných položek objednávky. Pomocí této struktury může obchodník dále předat v rámci mallpay/logistics také údaje o zrušené části objednávky.

Položka	Typ	Popis
totalPrice	Object	Celková cena včetně DPH, popis viz datová struktura price
totalVat	Array	Daňová sazba, popis viz datová struktura vat
items	Array	Pole objektů typu "reference na položku objednávky", kterými obchodník odkazuje na položky objednávky, popis viz datová struktura item reference

Příklad vyplnění reference objednávky:

{
  "totalPrice": {
    "amount":1452000,
    "currency":"CZK"
  },
  "totalVat": [{
    "amount":252000,
    "currency":"CZK",
    "vatRate":21
  }],
  "items": [{
    "code":"X123",
    "name":"iPhone XS"
  }]
}

Metoda `mallpay/init`

POST https://api.platebnibrana.csob.cz/api/v1.8/mallpay/init

Operace založí Odloženou platbu (mallpay@shop). Do systému Mall Pay předá platební brána údaje o zákazníkovi a objednávce. Mall Pay provede prvotní ověření zákazníka (tzv. pre-check), a pokud je platba pro daného zákazníka možná, je výsledkem této operace zejména URL pro přesměrování do Mall Pay.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou.
orderNo	String	Referenční číslo objednávky využívané pro párování plateb, které bude uvedeno také na výpisu z banky. Numerická hodnota, maximální délka 10 číslic.
customer	Object	Údaje o zákazníkovi, které budou použity pro vyřízení Odložené platby u Mall Pay. Popis parametrů viz datová struktura customer.
order	Object	Údaje o objednávce, které budou použity pro vyřízení Odložené platby u Mall Pay. Popis parametrů viz datová struktura order.
agreeTC	Boolean	Souhlas zákazníka s obchodními podmínkami Mall Pay. Povolené hodnoty: `true`, `false`. Podmínky není nutné na e-shopu zobrazovat - v takovém případě pošlete prosím `false` a odsouhlasení podmínek si zajistí systém Mall Pay. Pokud budete podmínky zobrazovat, není nutný souhlas ve smyslu zaškrtnutí checkboxu. Jedná se o informovaný souhlas, který stačí zobrazit.
dttm	String	Datum a čas odeslání požadavku ve formátu `YYYYMMDDHHMMSS`.
clientIp	String	IP adresa zákazníka (jeho prohlížeče) přistupujícího na e-shop obchodníka, formát ipv4 nebo ipv6.
returnUrl	String	URL adresa, na kterou bude klient přesměrován zpět do e-shopu v případě zrušení platby zákazníkem. Maximální délka 300 znaků.
returnMethod	String	Metoda návratu na URL adresu e-shopu. Povolené hodnoty `POST`, `GET`. Doporučená metoda je `POST`.
merchantData	String	Libovolná pomocná data, která budou vrácena ve zpětném redirectu z platební brány na stránku obchodníka. Mohou sloužit např. pro udržení kontinuity procesu na e-shopu, musí být kódována v BASE64. Maximální délka po zakódování 255 znaků.
ttlSec	Number	Nastavení životnosti transakce, v sekundách, min. povolená hodnota 600, max. povolená hodnota 43200 (10 min - 12 hodin).
signature	String	Podpis požadavku, kódováno v BASE64.

Příklad požadavku:

{
  "merchantId":"012345",
  "orderNo":"51966",
  "customer": {
    "firstName": "Adam",
    "lastName": "Malý",
    "email": "adam.maly@example.com",
    "phone": "+420800300300"
  },
  "order": {
    "totalPrice": {
    	"amount":1210000,
    	"currency":"CZK"
    },
    "totalVat": [{
    	"amount":210000,
    	"currency":"CZK",
    	"vatRate":21
    }],
    "addresses": [
    	{
    	"addressType":"BILLING",
    	"streetAddress":"Radlická 333",
    	"city":"Praha 5",
    	"zip":"15000",
    	"country":"CZ"
    	}
    ],
    "items": [
    	{
    	"code":"ABC123",
    	"name":"iPhone 8S",
	    "totalPrice": {
	    	"amount":1210000,
	    	"currency":"CZK"
	    },
	    "totalVat": {
	    	"amount":210000,
	    	"currency":"CZK",
	    	"vatRate":21
	    }
      }
    ]
  },
  "agreeTC":true,
  "dttm":"20190901131559",
  "clientIp":"192.0.2.2",
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "merchantData":"some-base64-encoded-merchant-data",
  "signature":"base64-encoded-signature-of-payment-request"
}

Návratové hodnoty

Položka	Typ	Popis
payId	String	Jednoznačné ID platby (přidělené platební bránou v operaci init, obsahuje 15-znakový řetězec)
dttm	String	Datum a čas odpovědi ve formátu `YYYYMMDDHHMMSS`
resultCode	Number	Výsledek operace, viz výčet
resultMessage	String	Textový popis výsledku operace
paymentStatus	Number	Stav platby, viz životní cyklus transakce
mallpayUrl	String	URL pro přesměrování zákazníka na Mall Pay, vyplněno v případě, že `resultCode` je `0`
signature	String	Podpis odpovědi, kódováno v BASE64

Příklad návratových hodnot pro mallpay/init -- úspěšně založená transakce:

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190901131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "mallpayUrl": "https://www.mallpay.cz/...",
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro mallpay/init - zamítnutá transakce (nevalidní vstupní parametry):

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190901131559",
  "resultCode": 110,
  "resultMessage":"Missing 'customer' parameter",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Metoda `mallpay/logistics`

PUT https://api.platebnibrana.csob.cz/api/v1.8/mallpay/logistics

Pomocí této operace obchodník předá údaje o doručení nebo odeslání (dle smluvního nastavení s Mall Pay) jednotlivých položek objednávky zákazníkovi. Pokud obchodník neodeslal / nedodal všechny původní položky objednávky (předané na platební bránu v operaci mallpay/init), je nutné tyto položky uvést ve zrušených položkách.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	PayID transakce
event	String	Způsob předání zboží, povolené hodnoty: `delivered`, `sent`
date	String	Datum doručení nebo odeslání zboží, formát `YYYYMMDD`
fulfilled	Object	Údaje o doručených/odeslaných položkách objednávky včetně celkové částky a rozpadu daňových sazeb, popis viz datová struktura order reference
cancelled	Object	Údaje o zrušených položkách objednávky včetně celkové částky a rozpadu daňových sazeb, popis viz datová struktura order reference, vyplněno v případě zrušených položek objednávky u Mall Pay
deliveryTrackingNumber	String	Sledovací číslo u dopravce
dttm	String	Datum a čas odeslání požadavku ve formátu `YYYYMMDDHHMMSS`
signature	String	Podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"c165e8c4b624fBD",
  "event":"delivered",
  "date":"20191020",
  "fulfilled": {
    "totalPrice": { "amount":24200, "currency":"CZK" },
    "totalVat": [ { "amount":4200, "currency":"CZK", "vatRate":21 } ],
    "items":[
      { 
        "code":"AX1255c",
        "name":"Obal na iPhone XS",
        "type":"PHYSICAL",
        "quantity":1
      }
    ]
  },
  "dttm":"20190901131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro mallpay/logistics:

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190901131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "signature":"base64-encoded-response-signature"
 }

Metoda `mallpay/cancel`

PUT https://api.platebnibrana.csob.cz/api/v1.8/mallpay/cancel

Pomocí této operace provede obchodník zrušení Odložené platby, ve vstupních parametrech uvádí důvod zrušení. Ruší se celá objednávka, proto nejsou v tomto volání předávány reference na položky objednávky.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	PayID transakce
reason	String	Důvod zrušení platby obchodníkem, povolené hodnoty: `aborted` pro zrušenou objednávku zákazníkem; `other_payment` pro situaci, kdy se zákazník rozhodl změnit způsob platby; `undeliverable` pro případ, že objednávka byla zrušena z důvodu nedoručitelnosti (např. nevyzvednutý balík); `unavailable` pro případ zrušení objednávky z důvodu nedostupnosti zboží; `abandoned` pro případ nedokončení objednávky zákazníkem (pouze pokud e-shop vyžaduje další kroky k dokončení objednávky po potvrzení Mall Pay platby); `changed` pro případ, že zákazník změnil objednávku a ta z toho důvodu zanikla; `unprocessed` pro ostatní důvody na straně e-shopu, které vedly k nemožnosti dokončit/naplnit objednávku
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
signature	String	Podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"c165e8c4b624fBD",
  "reason":"aborted",
  "dttm":"20190901131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro mallpay/cancel:

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20190901131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 3,
  "signature":"base64-encoded-response-signature"
 }

Metoda `mallpay/refund`

PUT https://api.platebnibrana.csob.cz/api/v1.8/mallpay/refund

Voláním operace je zažádáno o návrat prostředků nazpět plátci. Aplikuje se na již zaúčtované transakce. Lze provést i tzv. částečnou vratku vyplněním nepovinného parametru amount. Částečnou vratku lze provádět opakovaně, přičemž platí, že částka v parametru amount musí být menší než rozdíl původní autorizované částky a sumy doposud provedených (schválených) částečných vratek.

Položka	Typ	Popis
merchantId	String	ID obchodníka přiřazené platební bránou
payId	String	Jednoznačné ID platby (přidělené platební bránou v operaci init)
dttm	String	Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS
amount	Number	Požadovaná částka pro částečnou vratku v setinách základní měny; pro úplnou vratku nepovinné
refundedItems	Array	Údaje o vrácených položkách objednávky, popis viz datová struktura item reference; povinné pro částečnou i úplnou vratku. Suma cen vracených položek musí odpovídat parametru `amount`
signature	String	Podpis požadavku, kódováno v BASE64

Příklad požadavku:

{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBE",
  "refundedItems":[
    { 
      "code":"AX1255c",
      "name":"Obal na iPhone XS"
    }],
  "dttm":"20190901131559",
  "signature":"base64-encoded-request-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Zpracování u této operace je asynchronní, parametr paymentStatus v návratových hodnotách proto obsahuje aktuální stav platebního požadavku (Platba zúčtována), stav platebního požadavku je možné sledovat přes payment/status.

Příklad návratových hodnot pro mallpay/refund:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20190901131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 8,
  "signature":"base64-encoded-response-signature"
 }

Změna barevného schématu brány <a name="PAGE_Změna-barevného-schématu-brány"

Na platební bráně můžete změnit barevnost levého sloupce, který obsahuje údaje o vás jako o obchodníkovi (zejména logo a kontakty), košík a celkovou částku. Pro změnu barevnosti budete potřebovat nadefinovat celkem šest barev a dávat pozor na jejich vzájemné souvislosti.

Barva #1 = barva textu kontaktních údajů, košíku a textu tlačítka zrušení transakce

Barva #2 = barva pozadí sloupce / barva košíku a kontaktních údajů obchodníka na mobilu

Barva #3 = barva linky oddělující položky košíku

Barva #4 = barva pozadí celkové částky

Barva #5 = barva šipky rozbalující košík v mobilní verzi

Barva #6 = barva pozadí tlačítka zrušení transakce

Dejte si prosím pozor na tyto souvislosti:

Barevné schéma vždy testujte jak na počítači, tak na smartphonu. Řešení responsivity přebarvuje prvky v obou rozhraních jinak (viz např. následující bod 2).
Barvy #4 a #5 nesmí být stejné. V opačném případě nebude vidět tlačítko rozbalení košíku na mobilu. Barvu #5 doporučujeme nastavit stejnou jako barvu #6 (protože pozadí částky je vždy tmavé a barva #6 by měla být ze všech použitých barev nejsvětlejší).
Text celkové částky je vždy bílý. Volbou barvy pozadí (barva #4) zajistěte čitelnost textu.
Barva #6 vyplňuje tlačítko zrušení transakce, jehož text je barvou #1. Kombinací barev zajistěte čitelnost textu.
Barva textu #1 nastavuje i barvu písma v košíku, jehož pozadí je na desktopu vždy bílé. Současně na mobilu odpovídá barva pozadí košíku barvě #2.
Kombinací barvy textu (#1) a pozadí (#2) zajistěte čitelnost textu. Současně nevolte barvu textu #1 příliš světlou a barvu pozadí #2 příliš tmavou tak, aby byl text v košíku čitelný jak na neměnném bílém pozadí na desktopu, tak na barevném pozadí (#2) na mobilu.
Kombinací barvy pozadí (#2) a tlačítka zrušení transakce (#6) zajistěte zřetelnou viditelnost tlačítka pro zrušení transakce.

Postup nahrání a aktivace barevného schématu v testovacím prostředí

Doporučujeme vyzkoušet kombinaci barev v testovacím prostředí (volaném na https://iapi.iplatebnibrana.csob.cz) a odladit si jeho vzhled před nasazením do produkčního systému. Schémata na testovacím prostředí nepodléhají schválení bankou, můžete si proto rychle otestovat různé varianty a odladit kombinaci. Znovu připomínáme nutnost otestovat schéma jak na desktopu, tak na smartphonu.

Přihlaste se do systému ČSOB POS Merchant - Testovací prostředí - sekce platební brány, z ikon akcí platební brány (vpravo) vyberte "barevná schémata".
Nastavte všech šest barev schématu a uložte schéma. Systém automaticky schémata pojmenovává verzemi.
V seznamu schémat se zobrazí nově nadefinované schéma včetně náhledu barev.
Aktivujte zobrazení schématu.
Schéma se začne na platební bráně zobrazovat nejpozději do 5 minut od aktivace v kroku 4.

Postup nahrání a aktivace barevného schématu v produkčním prostředí

Přihlaste se do systému ČSOB POS Merchant - sekce platební brány, z ikon akcí platební brány (vpravo) vyberte "barevná schémata".
Nastavte všech šest barev schématu a uložte schéma. Doporučujeme kopírovat kódy barev s nastaveným testovacím prostředím. Systém automaticky schémata pojmenovává verzemi.
V seznamu schémat se zobrazí nově nadefinované schéma včetně náhledu barev.
Vyčkejte na schválení barevného schématu bankou.
Aktivujte zobrazení schématu.
Schéma se začne na platební bráně zobrazovat nejpozději do 5 minut od aktivace v kroku 5.

Schválení barevného schématu

Barevné schéma podléhá schválení banky. Zamítnuta budou zejména ta schémata, která nezajišťují dostatečnou čitelnost textů celkové částky, tlačítka zrušení transakce a kontaktních údajů obchodníka.

Multibranding - podpora více barevných schémat pro jednoho obchodníka

Prodáváte-li pod více značkami (např. jedna pro český a druhá pro evropský e-shop) a současně prodejcem je stále jedna firma (jedno IČO), můžete použít multibrandovou funkci brány. Od verze API 1.6 je možné ve volání payment/init specifikovat, jaké se má použít barevné schéma (parametr colorSchemeVersion). Stejně tak můžete řídit i zobrazované logo (parametr logoVersion). Obchodník tak může mít schválených několik log a barevných schémat, přičemž standardně (při volání bez udání požadované verze loga nebo barevného schématu) se použije vždy to, které je v systému POS Merchant označeno jako "aktivní". Je-li ve volání transakce požadováno logo nebo barevné schéma, které je ve stavu "schváleno", bude zobrazeno na bráně klientovi. Je-li voláno logo nebo barevné schéma, které není schváleno, bude klientovi na bráně zobrazeno logo nebo barevné schéma, které je "aktivní".

Logo obchodníka <a name="PAGE_Logo-obchodníka

Platební bránu lze personalizovat logem obchodníka, které se na platební bráně zobrazuje klientům. Celá platba tak pro ně bude důvěryhodnější a budou si jisti, že po přesměrování na platební bránu "jsou stále s vámi". Logo je třeba nahrát do systému ČSOB POS Merchant.

Požadavky na logo

Formát: PNG

Podporované rozměry: šířka 240px a výška 100px, nebo šířka 480px a výška 200px

Doporučená barva pozadí: průhledná nebo bílá

Maximální velikost: 500kB

Pokud je Vaše logo čtvercové nebo kruhové, umístěte jej horizontálně i vertikálně do středu. Dbejte na volbu vhodné velikosti s ohledem na odstup od horní a spodní hrany obdélníkového prostoru pro logo, případně definovaných ochranných zón vašeho loga.

Postup nahrání a aktivace loga v testovacím prostředí

Doporučujeme vyzkoušet logo v testovacím prostředí (volaném na https://iapi.iplatebnibrana.csob.cz) a odladit si jeho vzhled před nasazením do produkčního systému. Loga v testovacím systému nepodléhají schvalování v bance, můžete si tedy rychle vyzkoušet i několik vzhledů loga.

Logo nahrajte do systému ČSOB POS Merchant - Testovací prostředí - sekce platební brány, z ikon akcí platební brány (vpravo) vyberte "logo".
Vyberte soubor loga (splňující požadavky) a pojmenujte jej ("verze"), potvrďte nahrání.
V seznamu log se zobrazí nově nahrané logo.
Aktivujte zobrazení loga.
Logo se začne na platební bráně zobrazovat nejpozději do 5 minut od aktivace v kroku 4.

Postup nahrání, schválení a aktivace loga v produkčním prostředí

V produkčním prostředí banka schvaluje loga obchodníků. Nahrávejte prosím pouze loga, která jste vzhledově odladili v testovacím prostředí.

Logo nahrajte do systému ČSOB POS Merchant - sekce platební brány. Z ikon akcí platební brány (vpravo) vyberte "logo".
Vyberte soubor loga (splňující požadavky) a pojmenujte jej ("verze"), potvrďte nahrání.
V seznamu log se zobrazí nově nahrané logo se stavem "čeká na schválení".
Po schválení loga bankou je nutné aktivovat zobrazení loga na bráně.
Logo se začne na platební bráně zobrazovat nejpozději do 5 minut od aktivace v kroku 4.

Dočasná (např. sezónní nebo výroční) výměna loga

Chcete-li na platební bráně zobrazit jiné logo než vaše standardní (např. na Vánoce nebo u příležitosti výročí založení firmy), nemažte původní logo, které již máte schválené. V systému může být zavedeno a schváleno více než jedno logo a v systému POS Merchant lze pomocí aktivace a deaktivace loga vybírat konkrétní logo k zobrazení na bráně. Následně se můžete kdykoli vrátit k původnímu logu - jedním klikem v systému POS Merchant bez schvalování.

Multibranding - podpora více logotypů pro jednoho obchodníka

Prodáváte-li pod více značkami (např. jedna pro český a druhá pro evropský e-shop) a současně prodejcem je stále jedna firma (jedno IČO), můžete použít multibrandovou funkci brány. Od verze API 1.6 je možné ve volání payment/init specifikovat, jaké se má použít logo (parametr logoVersion). Stejně tak můžete řídit i zobrazované barevné schéma (parametr colorSchemeVersion). Obchodník tak může mít schválených několik log a barevných schémat, přičemž standardně (při volání bez udání požadované verze loga nebo barevného schématu) se použije vždy to, které je v systému POS Merchant označeno jako "aktivní". Je-li ve volání transakce požadováno logo nebo barevné schéma, které je ve stavu "schváleno", bude zobrazeno na bráně klientovi. Je-li voláno logo nebo barevné schéma, které není schváleno, bude klientovi na bráně zobrazeno logo nebo barevné schéma, které je "aktivní".

Přechod do produkčního prostředí

Pro přechod z integračního do produkčního prostředí musí obchodník provést následující testovací scénáře.

⚠️ Hledáte-li jak testovat během vývoje v rámci integračního prostředí, podívejte se na speciální testovací karty i způsob řízení výsledku transakce pomocí CVC kódu. Tyto karty nejsou na produkčním prostředí použitelné.

Následující testy se provádějí na integračním prostředí (https://iapi.iplatebnibrana.csob.cz/). Od běžných testů, které jste prováděli během vývoje, se liší pouze použitím specifických čísel karet.

Test komunikace - echo (GET)

zavolat operaci echo pomocí metody GET
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (0)

Test komunikace - echo (POST)

zavolat operaci echo pomocí metody POST
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (0)

Úspěšně autorizovaná platba

provést inicializaci platby (payment/init) a následné přesměrování na platební bránu (payment/process)
na platební bráně zadat testovací kartu 4154610001000209, libovolnou platnou expiraci a CVC 100, po odeslání se provede úspěšná autorizace platby, nakonec se provede přesměrování zpět do e-shopu obchodníka
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (0), dále paymentStatus (4 anebo 7 podle nastavení closePayment předaného v rámci inicializace platby)

Uživatelem zrušená platba

provést inicializaci platby (payment/init) a následné přesměrování na platební bránu (payment/process)
na platební bráně zrušit platbu kliknutím na odkaz "Zrušit platbu a návrat zpět do e-shopu"
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (0), dále paymentStatus (3)

Expirovaná (zrušená) platba

provést inicializaci platby (payment/init) a následné přesměrování na platební bránu (payment/process)
nezadávat údaje pro autorizaci, po 30 minutách se provede přesměrování zpět do e-shopu obchodníka (pokud se okno prohlížeče zavře, transakce na serveru platební brány expiruje, stav transakce lze zjistit pomocí volání payment/status)
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (130), dále paymentStatus (6)

Reverzovaná platba

Pro otestování reversalu je potřeba vytvořit novou transakci dle postupu uvedeného níže, nelze reverzovat dříve vytvořenou autorizovanou transakci, viz sekce "Úspěšně autorizovaná platba".

provést inicializaci platby (payment/init) a následné přesměrování na platební bránu (payment/process)
na platební bráně zadat testovací kartu 5542860001000224, libovolnou platnou expiraci a CVC 100, po odeslání se provede úspěšná autorizace platby, nakonec se provede přesměrování zpět do e-shopu obchodníka
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (0), dále paymentStatus (4 anebo 7 podle nastavení closePayment předaného v rámci inicializace platby)
provést reverzování této platby pomocí operace payment/reverse
zkontrolovat response code (200 OK)
ověřit podpis odpovědi (pomocí public klíče platební brány pro integrační prostředí)
ve vráceném JSON response zkontrolovat resultCode (0), dále paymentStatus (5)

Upozornění: Pokud obchodník NEintegruje reversal, je potřeba, aby kontaktoval akceptacekaret@csob.cz a zažádal o přechod do produkčního prostředí s tím, že reverzované transakce nebude používat.

Ukončení práce v integračním prostředí

Po dokončení všech testovacích scénářů je nutné potvrdit dokončení těchto testů v systému ČSOB POS Merchant.

Aktivace produkčního přístupu

Po kontrole úspěšného provedení testů vás budeme informovat o aktivaci produkčního přístupu. Od tohoto momentu můžete provádět "ostré" platby. Nezapomeňte si překonfigurovat volání platební brány z integračního prostředí (https://iapi.iplatebnibrana.csob.cz/) na produkční platební bránu (https://api.platebnibrana.csob.cz/).

Test v produkci

Před zpřístupněním plateb klientům doporučujeme i provedení ostrého produkčního testu. Použít můžete jakoukoli platební kartu, kterou běžně používáte a víte, že je funkční. Tuto zkušební transakci můžete samozřejmě následně vrátit.

Přechod z již používané platební brány GP Webpay <a name="PAGE_Přechod-z-již-používané-platební-brány-GP-Webpay

Využíváte-li již nyní platební bránu ČSOB GP Webpay, můžete si vybrat ze dvou způsobů přechodu na novou bránu. Zde popsaný migrační scénář je jednodušší - pro většinu obchodníků neznamená žádný vývoj, ale jen parametrizaci existující integrace platební brány v e-shopu. Mějte však na paměti, že nové funkce již nebudou na tomto rozhraní platební brány podporovány. Pokud by ve vašem e-shopu i zde popsaný scénář znamenal větší vývoj, doporučujeme přejít rovnou na nové eAPI platební brány.

Oba migrační přístupy můžete samozřejmě kombinovat. Přejít na novou platební bránu změnou parametrů můžete ihned dle tohoto návodu. Následně můžete vyvinout integraci nového eAPI a po otestování přejít na nové rozhraní, které i pro vás bude základem pro nové, pohodlnější způsoby placení pro vaše klienty.

Pokud ve vašem e-shopu používáte SOAP rozhraní původní platební brány GP Webpay pro zjišťování stavů objednávek, implementujte prosím rovnou nové eAPI, protože Legacy API tuto funkci nemá.

Přechod z brány GP Webpay je velice jednoduchý. Stačí následovat tyto tři kroky:

1. Vygenerujte si nové klíče a zaveďte je do vašeho systému

Nejdříve vyměňte veřejný klíč platební brány. Nový si stáhněte zde z Gitu.

Svou vlastní dvojici klíčů si vygenerujte na https://platebnibrana.csob.cz/keygen/. Jako e-mail zadejte technický kontakt, který jste uvedli při podpisu dodatku ke smlouvě. Jako Merchant ID uveďte ID, které vidíte v přehledu platebních bran systému ČSOB POS Merchant v prvním sloupci zleva (začíná vždy M1E3CB a následují 4 číslice). Privátní klíč se uloží do souboru na vašem počítači, veřejný klíč se odešle zabezpečeným kanálem na platební bránu. Privátní klíč zaveďte do svého systému, nový veřejný klíč potvrďte v systému ČSOB POS Merchant pomocí jednorázového kódu, který vám přijde na kontaktní e-mail.

2. Změňte nastavení volání platební brány (endpoint) a ID obchodníka

Platební bránu nově volejte na https://platebnibrana.csob.cz/pay/entry/merchant.

Poznámka: platební brána podporuje zpracování požadavků jak pomocí metody GET, tak pomocí POST. V případě, že je použita metoda GET, do výsledné URL se doplní parametry, např.

https://platebnibrana.csob.cz/pay/entry/merchant?AMOUNT=12300&MERCHANTNUMBER=...

V případě, že je použita metoda POST, posílají se parametry v těle požadavku jako "form-url-encoded" hodnoty. Zvolená metoda závisí na zvoleném řešení/pluginu použitém pro napojení e-shopu na GP Webpay.

ID obchodníka (Merchant ID) nahraďte za ID, které jste používali již při generování klíčů (začíná vždy M1E3CB a následují 4 číslice). Pozor! Se starým číslem obchodníka nebudou platby fungovat!

Pokud jsou tato nastavení ve vašem systému parametrizovatelná, nebudete muset nic programovat.

3. Nahrajte do nové platební brány logo vašeho e-shopu nebo aplikace

Do systému ČSOB POS Merchant nahrajte logo, které se bude na nové platební bráně zobrazovat klientům. Celá platba tak pro ně bude důvěryhodnější a budou si jisti, že po přesměrování na platební bránu "jsou stále s vámi".

Pokud vlastní logo nenahrajete, bude brána při transakcích zobrazovat výchozí logo stylizující nákupní košík.

Požadavky na soubor loga naleznete v kapitole Logo obchodníka. Logo podléhá schválení bankou, které zpravidla proběhne do následujícího pracovního dne. Doporučujeme proto logo vložit do systému co nejdříve.

A to je vše. Teď si ještě vyzkoušejte platbu, a pokud vše funguje, nic vám nebrání v používání naší nové platební brány. Pokud se náhodou něco nezdařilo, podívejte se prosím do technických FAQ.

4. Testovací prostředí - vyzkoušejte si vše nanečisto

Generátor klíčů https://iplatebnibrana.csob.cz/keygen/.

ČSOB POS Merchant - vygenerovaný veřejný klíč je po odeslání do banky automaticky schválen. Nemusíte tedy nic potvrzovat.

Adresa platební brány: https://iplatebnibrana.csob.cz/pay/entry/merchant.

Koncept API rozšíření

Koncept rozšíření (API extensions)

Platební brána nově podporuje možnost rozšíření (extensions). Pomocí této funkcionality lze rozšiřovat parametry jednotlivých operací "na míru" vybraným obchodníkům tak, aby bylo možné platební bráně poslat nebo od ní naopak obdržet potřebné parametry nezávisle na aktuální verzi veřejného API. Jednotlivá extensions jsou na sobě nezávislá, obchodník může mít povolené jedno nebo více rozšíření. O povolení jednotlivých rozšíření musí obchodník požádat banku.

Zabezpečení přenášených parametrů u daného rozšíření je řešeno podobně jako u stávajícího API, předává se signature přenášených údajů, tzn. povinností protistrany je ověření podpisu.

URL eAPI pro komunikaci s platební bránou je stále stejné, jednotlivá rozšíření jsou zaintegrována do stávajících operací. Díky samostatnému podpisu a "viditelnosti" na úrovni obchodníka je tento koncept transparentní pro ostatní obchodníky používající danou verzi eAPI.

Dostupná rozšíření

Detailní datum/čas zpracování a vypořádání transakce

Maskované číslo karty + expirace pro prvotní trx platby na klik

Hlášení tržeb z platební brány - EET

API Extension datum transakce <a name="PAGE_API-Extension-datum-transakce>

Datum vytvoření, autorizace a zúčtování transakce

Toto rozšíření (extension) předává v operaci payment/status údaje o datu a času vytvoření transakce, její autorizaci a zúčtování.

Obchodník musí mít tuto funkcionalitu na platební bráně povolenou.

Datum a čas vytvoření transakce

Jde o datum a čas založení transakce na platební bráně v rámci operace payment/init. Formát YYYY-MM-DD'T'HH:MM:SS.SSS'Z' (přesnost na ms).

Datum a čas autorizace

Úplně přesně se jedná o okamžik začátku zpracování v autorizační části platební brány (po validaci parametrů, těsně před odesláním požadavku na autorizaci). Formát YYMMDDHHMMSS (přesnost na sekundy).

Datum zúčtování

Datum zúčtování určuje, ve kterém výpisu transakce skončí. Formát YYYYMMDD (přesnost na dny).

Funkčnost extension v eAPI 1.6 a vyšším

Rozšíření parametrů odpovědi operace payment/status

Nově přidaný parametr je extensions, obsahuje seznam všech předávaných rozšíření pro danou operaci. Rozšíření trxDates bude vyplněno pouze v odpovědi operace payment/status.

Popis parametrů rozšíření trxDates

Tučně uvedené parametry budou vždy vráceny (jsou povinné).

Položka	Typ	Popis
extension	String	ID rozšíření (přidělené na základě konfigurace platební bránou). Pro toto rošíření bude vždy nastaveno na konstantu `trxDates`.
dttm	String	Datum a čas odpovědi ve formátu `YYYYMMDDHHMMSS`.
createdDate	String	Datum a čas vytvoření transakce na platební bráně. Formát `YYYY-MM-DD'T'HH:MM:SS.SSS'Z'`.
authDate	String	Datum a čas autorizace. Formát `YYMMDDHHMMSS`. Vyplněno pouze pokud je transakce autorizovaná.
settlementDate	String	Datum zúčtování transakce. Formát `YYYYMMDD`. Vyplněno pouze pokud je transakce zařazena do zúčtování nebo je již zúčtována.
signature	String	Podpis rozšíření, kódováno v BASE64.

Příklad response pro payment/status doplněného o rozšíření trxDates

{
  "dttm": "20151119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "e80cfaedc3a85BD",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 7,
  "authCode": "453708",
  "extensions": [
    {
      "dttm": "20151119113916",
      "signature": "base64-encoded-extension-signature",
      "extension": "trxDates",
      "createdDate": "2016-04-12T12:06:20.848Z",
      "authDate": "160412100635",
      "settlementDate": "20160412"
    }
  ]
}

Řetězec pro výpočet nebo pro ověření podpisu je pro toto rozšíření seskládaný v pořadí, v jakém jsou položky uvedeny ve specifikaci (viz výše).

trxDates|20151119113916|2016-04-12T12:06:20.848Z|160412100635|20160412

Poznámka: Podpis původních parametrů je nezměněn. Položka extensions obsahující seznam jednotlivých posílaných rozšíření nijak nezasahuje do výpočtu původního podpisu zprávy. Každé rozšíření má svůj vlastní podpis.

Pro podepisování / ověření podpisu rozšíření je použit stejný algoritmus (SHA1withRSA pro eAPI 1.7 a nižší, nově pak SHA256withRSA pro eAPI 1.8 a vyšší).

API extension detail karty pro platbu na klik

Maskované číslo karty + expirace pro prvotní transakce platby Na klik

Toto rozšíření (extension) předává v operaci payment/status nové údaje o prvotní transakci u platby Na klik (u tzv. šablony pro platby Na klik). Pokud je prvotní platba autorizována, předává se obchodníkovi maskované číslo použité platební karty a její expirace.

Obchodník musí mít tuto funkcionalitu na platební bráně povolenou.

Funkčnost extension v eAPI 1.6 a vyšším

Rozšíření parametrů odpovědi operace payment/status

Nově přidaný parametr je extensions, obsahuje seznam všech předávaných rozšíření pro danou operaci. Rozšíření maskClnRP bude vyplněno pouze v odpovědi operace payment/status v případě, že prvotní platba je úspěšně autorizována.

Popis parametrů rozšíření maskClnRP

Tučně uvedené parametry budou vždy vráceny (jsou povinné).

Položka	Typ	Popis
extension	String	ID rozšíření (přidělené na základě konfigurace platební bránou). Pro maskované číslo karty a expiraci u prvotní platby bude vždy nastaveno na konstantu `maskClnRP`.
dttm	String	Datum a čas odpovědi ve formátu YYYYMMDDHHMMSS.
maskedCln	String	Maskované číslo platební karty ve formátu `****XXXX`, kde `XXXX` jsou poslední 4 číslice z čísla platební karty.
expiration	String	Expirace platební karty ve formátu `MM/YY`.
longMaskedCln	String	Plné maskované číslo platební karty ve formátu `PPPPPP****XXXX`, kde `PPPPPP` je prvních 6 číslic, `XXXX` jsou poslední 4 číslice z čísla platební karty.
signature	String	Podpis rozšíření, kódováno v BASE64.

Příklad doplněného response pro payment/status o rozšíření maskClnRP

{
  "dttm": "20151119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "3090adf87eda7AK",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 7,
  "authCode": "453708",
  "extensions": [
    {
      "dttm": "20151119113916",
      "signature": "base64-encoded-extension-signature",
      "extension": "maskClnRP",
      "longMaskedCln": "415461****0209",
      "maskedCln": "****0209",
      "expiration": "11/16"
    }
  ]
}

Řetězec pro výpočet nebo pro ověření podpisu je pro toto rozšíření seskládaný v pořadí, v jakém jsou položky uvedeny ve specifikaci (viz výše).

maskClnRP|20151119113916|****0209|11/16|415461****0209

Poznámka: Podpis původních parametrů je nezměněn, položka extensions obsahující seznam jednotlivých posílaných rozšíření nijak nezasahuje do výpočtu původního podpisu zprávy, každé rozšíření má svůj vlastní podpis.

Pro podepisování / ověření podpisu rozšíření je použit stejný algoritmus (SHA1withRSA pro eAPI 1.7 a nižší, nově pak SHA256withRSA pro eAPI 1.8 a vyšší).

Hlášení tržeb z platební brány <a name="PAGE_Hlášení-tržeb-z-platební-brány

Základní funkcí elektronické evidence tržeb (dále EET) na platební bráně je hlášení tržby ke každé autorizované transakci kartou (resp. všemi platebními metodami, u kterých si obchodník nastaví, že je chce hlásit). Tato základní funkce je doplněna o poměrně složité řešení, jehož úkolem je postihnout v kontextu EET všechny situace, které mohou na platební bráně při zpracování transakcí nastat. Jsou to zejména:

zrušení autorizace a odvolání platební transakce pokud Finanční správa odmítne hlášení tržby
podpora EET při uzavírání transakcí na nižší částku
podpora odhlašování tržeb při odvolání transakcí a částečných i úplných vratkách plateb
řešení pro dodatečné hlášení tržby v případě, že dojde k překročení mezní doby odezvy

Vzhledem k přetrvávajícím nejistotám ve výkladu zákona je navíc důležitou vlastností hlášení tržeb přes platební bránu načasování hlášení tržby. To probíhá bezprostředně po úspěšné autorizaci transakce, kód FIK je platební bránou získán a následně sdělen obchodníkovi v momentě, kdy banka předává obchodníkovi informaci o úspěšné trasakci kartou a obchodníkovi vzniká tržba.

Platební brána odstiňuje obchodníka od komunikace s Finanční správou. Obchodník tak nemusí implementovat rozhraní, podepisování a generování kódů BKP a PKP - vše je zajištěno platební bránou. EET údaje obchodník do platební brány předává pomocí rozšíření rozhraní eAPI. Nové EET rozšíření je funkční pro eAPI ve verzích 1.6 a 1.7 (rozšíření nejsou ve verzi 1.0 a 1.5 podporována). Máte-li nyní implementováno eAPI 1.0 nebo 1.5 a chcete používat rozšíření pro EET, přejděte na aktuální verzi eAPI v1.8. Všechny základní funkce jsou zpětně kompatibilní.

Při každém hlášení tržby (nebo odhlašování vratky) musí obchodník poskytnout platební bráně veškeré parametry pro nahlášení tržby (s výjimkou několika statických parametrů, kterými již banka disponuje v profilu obchodníka). Obchodník si proto musí být vědom toho, jaké jeho tržby podléhají EET a jaké údaje pro různé typy transakcí vyplňovat. Tento moment bohužel platební brána zjednodušit nedokáže.

Výsledky hlášení tržby předává platební brána obchodníkovi společně s potvrzením transakce. (V případě zamítnutí hlášení tržby Finanční správou obdrží obchodník informaci o důvodu zamítnutí). Údaje předané do e-shopu (obsahující zejména kódy BKP, FIK, resp. PKP) použije obchodník pro tvorbu účtenky. Způsob tvorby a doručení účtenky platební brána nijak neovlivňuje a tento krok si obchodník může zorganizovat dle svého uvážení.

Platební brána je pro obchodníka poskytovatelem technické služby (podobně jako dodavatel EET pokladny). Hlášení tržeb přes platební bránu není žádnou formou pověření nebo zastoupení.

Životní cyklus tržby

Tržba, zpracovávaná platební bránou, prochází stejně jako platba svým životním cyklem. Životní cyklus platby a tržby je odlišný, nicméně oba životní cykly jsou provázané. Ve většině případů platí, že změny v životním cyklu platby dávají impulzy ke změnám v životním cyklu tržby. Pouze v jednom případě (když se nepodaří nahlásit tržbu z důvodu chyby v hlášení) ovlivňuje událost v životním cyklu tržby samotnou platbu (je provedena okamžitá vratka transakce a platba zamítnuta).

Stavy životního cyklu tržby evidované prostřednictvím platební brány

Tržba ve svém životním cyklu nabývá následujících stavů, které jsou také komunikovány obchodníkovi spolu s výsledkem platby a při volání payment/status:

ID	Stav v životním cyklu	Význam
E1	Tržba založena	Na platební bráně byla založena platební transakce (voláním `payment/init`) a z údajů v EET extension k ní vznikla i tržba.
E2	Odeslán první pokus o nahlášení	Po autorizaci transakce se platební brána pokusila nahlásit tržbu do systému Finanční správy.
E3	Tržba nahlášena online	Kýžený výsledek – tržba byla nahlášena online bez problémů.
E4	Tržba evidována offline	Do timeoutu nepřišla na bránu odpověď. Platební brána předala obchodníkovi BKP, PKP a bude se snažit tržbu nahlásit během následujících 48 hodin.
E5	Finanční správa odmítla hlášení tržby	Obchodník odeslal špatné EET parametry.
E6	Tržba evidována offline a odeslána online během 48 hodin	Opakované hlášení se podařilo a tržba byla přijata serverem Finanční správy.
E7	Tržba evidována offline a NEodeslána online během 48 hodin	EET je dlouhodobě nedostupná.
E8	Odeslán pokus o odhlášení	Obchodník nebo platební brána inicioval(a) částečné nebo úplné odhlášení tržby z EET.
E9	Tržba odhlášena online	Kýžený výsledek odhlášení – vše proběhlo bez problémů a online.
E10	Finanční správa odmítla odhlášení tržby	Obchodník odeslal špatné EET parametry.
E11	Odhlášení evidováno offline	Do timeoutu nepřišla na bránu odpověď. Platební brána předala obchodníkovi BKP, PKP a bude se snažit tržbu odhlásit během následujících 48 hodin.
E12	Odhlášení evidováno offline a odesláno online během 48 hodin	Opakovaný(é) pokus(y) o odhlášení se podařil(y) a odhláška byla přijata serverem Finanční správy.
E13	Odhlášení evidováno offline a NEodesláno online během 48 hodin	EET je dlouhodobě nedostupná.
E14	Tržba nevznikla	Platební transakce skončila před zařazením do zúčtování, např. z důvodu opuštění platby zákazníkem, návratem do e-shopu nebo vypršením sedmidenní lhůty pro zařazení transakce do zúčtování.

Průchod tržby životním cyklem

Průchod životním cyklem tržby lze znázornit na následujícím schématu. Červeně jsou označeny změny v životním cyklu platební transakce, které iniciují přechody mezi stavy v životním cyklu stavů EET tržby.

Konkrétní dopady životního cyklu tržby a stavů tržby na implementaci v e-shopu

Pro vaši implementaci jsou důležité zejména následující souvislosti:

Nedokončí-li zákazník platbu, platba není z jakéhokoli důvodu autorizována nebo platbu nezařadíte do zúčtování. Pak platební brána nekontaktuje Finanční správu (v těchto případech nedojde k podání příkazu plátcem prostřednictvím příjemce).
Odmítne-li Finanční správa hlášení tržby, platební transakci okamžitě zrušíme (odvoláme, se stejným výsledkem jako kdyby obchodník volal payment/reverse - tj. zákazníkovi se uvolní blokace na kartě a transakci nikdy neuvidí na výpisu). Z odpovědi platební brány se obchodník dozví důvod zamítnutí hlášení tržby. Protože nedošlo k zařazení platby do zúčtování (tj. nedošlo k podání příkazu plátcem prostřednictvím příjemce), obchodník se nevystavuje rizikům plynoucím z nenahlášení tržby řádně a včas.
Nevrátí-li se zákazník během doby životnosti transakce z brány do e-shopu, zavolejte si payment/status, kterým zjistíte stav platby. Pokud došlo u zákazníka např. k problémům s připojením a nepodařilo se mu po úspěšné transakci vrátit do e-shopu, platební brána i přesto nahlásila tržbu a vytvořila účtenku ve formě datové věty. Voláním výše uvedeného statusu si účtenku stáhnete, spustíte aktivity související s dokončením objednávky v e-shopu a předáte u vás obvyklým způsobem účtenku zákazníkovi.
Nepodaří-li se tržbu nahlásit z důvodu nemožnosti komunikovat s Finanční správou, předá brána obchodníkovi kódy BKP a PKP, které jsou určeny na účtenku. Následně se brána snaží tržbu nahlásit online. Doporučujeme volat jednou za dvě hodiny payment/status, ze kterého se dozvíte nejen stav hlášení tržby, ale i FIK (jakmile se tržbu podaří nahlásit online).
Chcete-li vrátit platbu (ať již úplně, nebo částečně - např. z důvodu vrácení zboží), je nutné k volání payment/refund připojit EET rozšíření a vyplnit všechny povinné parametry pro hlášení tržby. Jediným rozdílem je záporná celková částka. Nebude-li celková částka u volání EET rozšíření u payment/refund záporná, brána takové volání odmítne.
FIK, BKP a případně PKP nedostanete při volání payment/refund okamžitě, ale se zpožděním. Toto zpoždění může být až několik dnů, v závislosti na prověřování žádosti o vratku v bance. I v tomto případě je tak třeba volat payment/status a zjišťovat si stav zpracování vratky. Z pohledu EET není toto chování problém, protože voláním payment/refund obchodník podává žádost o provedení vratky, která je bankou potvrzena teprve po zařazení vratky do zúčtování. V okamžiku potvrzení bankou, tj. při přechodu platební transakce ze stavu 9 (zpracování vrácení) je provedeno odhlášení tržby a je získán FIK. Teprve následně je vratka zařazena do zúčtování (přechází do stavu 10 - platba vrácena). Dojde-li k odmítnutí hlášení Finanční správou, platební brána vratku nezpracuje.
Nepoužíváte-li automatické zařazení transakcí do zúčtování (pomocí parametru "closePayment": false, např. proto, že autorizujete na předpokládanou částku nákupu, ve kterém je zboží na váhu, a finální částka může být nižší), musíte při zakládání transakce na bráně (operace payment/init) poskytnout bráně údaje pro hlášení tržby ve stejné podobě jako při automatickém zařazování do zúčtování. Následně při uzavření transakce na nižší částku operací payment/close platební bráně předat údaje pro nahlášení tržby, které odpovídají konečné ceně nákupu. Budete-li zařazovat do zúčtování transakci na stejnou částku jako je částka autorizace v payment/init, pak nemusíte data EET rozšíření posílat. Brána použije data z volání payment/init. Pokud přesto EET data pošlete, použije brána pro hlášení tržby data z volání payment/close a na původní EET data z volání payment/init nebude brát ohled.
Nepoužíváte-li automatické zařazování transakcí do zúčtování a transakce zůstane nepotvrzená déle než 7 dní, platební brána zruší platební transakci. K hlášení tržby nedojde.
Nepodaří-li se bráně nahlásit tržbu ani během 48 hodin od vygenerování offline kódů BKP a PKP, musí situaci řešit obchodník sám. Tato situace může nastat z důvodu extrémního výpadku systému Finanční správy, síťové infrastruktury apod.

Specifikace API rozšíření pro EET

eAPI extension - EET v3

Pomocí tohoto rozšíření (extension) předává obchodník platební bráně parametry pro nahlášení nebo odhlášení platby v rámci EET a zjišťuje stav EET hlášení.

Obchodník musí mít tuto funkcionalitu na platební bráně aktivovanou. Pro aktivaci kontaktujte svého bankéře nebo obchodního zástupce.

Změny dokumentu od vydání (bez funkčního dopadu):

[1.2.2017] položky receiptNumber, receiptTime, evidenceMode, uuid, sendTime v EET rozšíření v payment/status změněny na nepovinné
[20.2.2017] doplněny příklady a podrobnější popis použití EET rozšíření pro operaci payment/oneclick/init
[27.2.2017] doplněna poznámka k podepisování EET rozšíření (formátování částky)

Toto rozšíření se váže ke specifikaci Popis datového rozhraní pro příjem datových zpráv evidovaných tržeb v3. Pojmenování EET parametrů pro potřeby tohoto rozšíření je popsáno v následujícím přehledu:

XML jméno (dokumentace EET)	Popis	Parametr v EET rozšíření
overeni	příznak ověřovacího módu	verificationMode
dic_popl	DIČ poplatníka	vatId
dic_poverujiciho	DIČ pověřujícího poplatníka	delegatedVatId
id_provoz	ID provozovny	premiseId
id_pokl	ID pokladny	cashRegisterId
porad_cis	číslo účtenky	receiptNumber
dat_trzby	datum uskutečnění tržby	receiptTime
celk_trzba	celková částka tržby	totalPrice
zakl_nepodl_dph	celková částka plnění osvobozených od DPH, ostatních plnění	priceZeroVat
zakl_dan1	základ daně se základní sazbou DPH	priceStandardVat
dan1	DPH se základní sazbou	vatStandard
zakl_dan2	základ daně s první sníženou sazbou	priceFirstReducedVat
dan2	DPH s první sníženou sazbou	vatFirstReduced
zakl_dan3	základ daně s druhou sníženou sazbou	priceSecondReducedVat
dan3	DPH s druhou sníženou sazbou	vatSecondReduced
cest_sluz	celková částka v režimu DPH pro cestovní službu	priceTravelService
pouzit_zboz1	celková částka v režimu DPH pro prodej použitého zboží se základní sazbou	priceUsedGoodsStandardVat
pouzit_zboz2	celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou	priceUsedGoodsFirstReduced
pouzit_zboz3	celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou sazbou	priceUsedGoodsSecondReduced
urceno_cerp_zuct	částka plateb určená k následnému čerpání nebo zúčtování	priceSubsequentSettlement
cerp_zuct	částka plateb, které jsou následným čerpáním nebo zúčtováním	priceUsedSubsequentSettlement
rezim	režim tržby	evidenceMode
uuid_zpravy	UUID zprávy	uuid
dat_odesl	datum odeslání z platební brány na Finanční správu (dále jen FS)	sendTime
dat_prij	datum a čas přijetí zprávy na FS	acceptTime
dat_odmit	datum a čas přijetí zprávy na FS	rejectTime

EET rozšíření doplňuje API metody:

payment/init a payment/oneclick/init pro nahlášení tržby (zpravidla se jedná o automatické zařazení transakce do zúčtování)
payment/status pro zjištění výsledku hlášení tržby
payment/close pro nahlášení tržby při zařazení transakce do zúčtování na nižší než autorizovanou částku
payment/refund pro odhlášení (části) tržby

Pro operace payment/init, payment/oneclick/init, payment/close a payment/refund vkládá obchodník EET rozšíření do požadavku posílaného na platební bránu, u operace payment/status načítá EET rozšíření z odpovědi poslané z platební brány.

V případě, že je transakce ve stavu 7 (zařazeno do zúčtování), bylo provedeno EET nahlášení na Finanční správu (dále FS) a obchodník provede reversal pomocí operace payment/reverse, platební brána provede automatické EET odhlášení transakce (použije se stejná částka jako při nahlášení, tato částka bude ale záporná).

API pro EET rozšíření (extension)

Parametry EET rozšíření pro operace `payment/init`, `payment/oneclick/init`, `payment/close` a `payment/refund`

Tučně uvedené parametry jsou povinné.

Položka	Typ	Popis
extension	String	ID rozšíření (přidělené na základě konfigurace platební bránou). Pro EET rozšíření vyplní obchodník hodnotu `eetV3`.
dttm	String	Datum a čas požadavku/odpovědi ve formátu YYYYMMDDHHMMSS.
data	Object	Parametry potřebné pro nahlášení nebo odhlášení platby.
verificationMode	Boolean	Příznak ověřovacího módu odesílání, povolené hodnoty jsou `true` / `false`. Pokud není vyplněno, je ve zprávě do FS nastavena hodnota `false`.
signature	String	Podpis rozšíření, kódováno v BASE64.

Struktura objektu data

Položka	Typ	Popis
premiseId	Number	označení provozovny
cashRegisterId	String	označení pokladního zařízení poplatníka
totalPrice	Number	celková částka tržby, v případě nahlášení platby (volání v rámci `payment/init`, `payment/oneclick/init` a `payment/close`) musí být kladné číslo; v případě odhlášení platby (volání v rámci `payment/refund`) musí být naopak záporné číslo
delegatedVatId	String	DIČ pověřujícího poplatníka
priceZeroVat	Number	celková částka plnění osvobozených od DPH, ostatních plnění
priceStandardVat	Number	celkový základ daně se základní sazbou DPH
vatStandard	Number	celková DPH se základní sazbou
priceFirstReducedVat	Number	celkový základ daně s první sníženou sazbou DPH
vatFirstReduced	Number	celková DPH s první sníženou sazbou
priceSecondReducedVat	Number	celkový základ daně s druhou sníženou sazbou DPH
vatSecondReduced	Number	celková DPH s druhou sníženou sazbou
priceTravelService	Number	celková částka v režimu DPH pro cestovní službu
priceUsedGoodsStandardVat	Number	celková částka v režimu DPH pro prodej použitého zboží se základní sazbou
priceUsedGoodsFirstReduced	Number	celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou
priceUsedGoodsSecondReduced	Number	celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou sazbou
priceSubsequentSettlement	Number	celková částka plateb určená k následnému čerpání nebo zúčtování
priceUsedSubsequentSettlement	Number	celková částka plateb, které jsou následným čerpáním nebo zúčtováním platby

Poznámka: všechny předávané částky musí být v řetězci pro podpis EET rozšíření formátované vždy na dvě desetinná místa.

Příklad volání `payment/init` s EET rozšířením na eAPI v1.8

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.8/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20170125131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Nákup: vasobchod.cz",
      "quantity": 1,
      "amount": 1789600,
      "description":"Lenovo ThinkPad Edge E540"
    },
    {
      "name": "Poštovné",
      "quantity": 1,
      "amount": 0,
      "description": "Doprava PPL"
    }
  ],
  "description":"Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)",
  "language":"CZ",
  "signature":"base64-encoded-signature-of-payment-request",
  "extensions":[
    {
      "extension": "eetV3",
      "dttm": "20170125131559",
      "data": {
        "premiseId": 181,
        "cashRegisterId": "00/2535/CN58",
        "totalPrice": 17896.00
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}'

Příklad řetězce pro podpis EET rozšíření:

eetV3|20170125131559|181|00/2535/CN58|17896.00

Poznámka: všechny předávané částky musí být v řetězci pro podpis EET rozšíření formátované vždy na dvě desetinná místa.

Příklad volání `payment/init` s EET rozšířením - ověřovací mód

V následujícím příkladu je zapnut ověřovací mód a je vyplněn nepovinný parametr delegatedVatId.

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.8/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20170125131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Nákup: vasobchod.cz",
      "quantity": 1,
      "amount": 1789600,
      "description":"Lenovo ThinkPad Edge E540"
    },
    {
      "name": "Poštovné",
      "quantity": 1,
      "amount": 0,
      "description": "Doprava PPL"
    }
  ],
  "description":"Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)",
  "language":"CZ",
  "signature":"base64-encoded-signature-of-payment-request",
  "extensions":[
    {
      "extension": "eetV3",
      "dttm": "20170125131559",
      "data": {
        "premiseId": 181,
        "cashRegisterId": "00/2535/CN58",
        "totalPrice": 17896.00,
        "delegatedVatId": "CZ00006947"
      },
      "verificationMode": true,
      "signature": "base64-encoded-extension-signature"
    }
  ]
}'

Příklad řetězce pro podpis EET rozšíření:

eetV3|20170125131559|181|00/2535/CN58|17896.00|CZ00006947|true

Poznámka: všechny předávané částky musí být v řetězci pro podpis EET rozšíření formátované vždy na dvě desetinná místa.

Upozornění:

V případě nevalidních parametrů EET rozšíření předávaných v rámci operace payment/init platební brána danou transakci zamítne (transakce skončí ve stavu 6, Platba zamítnuta).

Příklad volání `payment/oneclick/init` s EET rozšířením

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.8/payment/oneclick/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "origPayId":"ef08b6e9f2234BC",
  "orderNo":"5547123",
  "dttm":"20170125131559",
  "signature":"base64-encoded-signature-of-payment-request",
  "extensions":[
    {
      "extension": "eetV3",
      "dttm": "20170125131559",
      "data": {
        "premiseId": 181,
        "cashRegisterId": "00/2535/CN58",
        "totalPrice": 17896.00
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}'

Upozornění:

V případě nevalidních parametrů EET rozšíření předávaných v rámci operace payment/oneclick/init platební brána danou transakci zamítne (transakce skončí ve stavu 6, Platba zamítnuta).

Příklad volání `payment/close` s EET rozšířením

V případě zařazení transakce do zúčtování na nižší částku je obchodník povinen poslat v rámci volání operace payment/close nové parametry pro nahlášení platby. Původní data z payment/init nebo payment/oneclick/init se nepoužijí.

Pokud obchodník manuálně uzavírá transakci na stejnou částku (parametr amount není vyplněn anebo je stejný jako totalAmount v payment/init nebo payment/oneclick/init), nemusí EET data posílat. Použijí se údaje přijaté v rámci operace payment/init nebo payment/oneclick/init. Pokud přesto v payment/close při zařazení transakce do zúčtování na stejnou částku pošle obchodník vyplněné EET rozšíření, použijí se tyto nově poslané údaje pro nahlášení platby na FS.

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.8/payment/close \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fCA",
  "dttm":"20170125131605",
  "signature":"base64-encoded-request-signature",
  "extensions":[
    {
      "extension": "eetV3",
      "dttm": "20170125131605",
      "data": {
        "premiseId": 181,
        "cashRegisterId": "00/2535/CN58",
        "totalPrice": 9896.00
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}'

Upozornění:

V případě nevalidních parametrů EET rozšíření předávaných v rámci operace payment/close platební brána danou operaci neprovede (návratový parametr resultCode je nastaven na 110, Invalid parametr {name}).
V případě, že FS odmítne daný požadavek na nahlášení (viz stav E5 v životním cyklu), platební brána operaci payment/close neprovede. Transakce je automaticky reverzována, operace vrátí resultCode nastavený na 500, Rejected by EET. Detailní informace o důvodech odmítnutí lze zjistit provoláním operace payment/status.

Příklad volání `payment/refund` s EET rozšířením

Pro operaci payment/refund nastavuje obchodník v EET rozšíření zápornou částku, kterou chce odhlásit na FS.

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.8/payment/refund \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fCA",
  "dttm":"20170125131605",
  "amount": 532000,
  "signature":"base64-encoded-request-signature",
  "extensions":[
    {
      "extension": "eetV3",
      "dttm": "20170125131605",
      "data": {
        "premiseId": 181,
        "cashRegisterId": "00/2535/CN58",
        "totalPrice": -2896.00
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}'

Upozornění:

V případě nevalidních parametrů EET rozšíření předávaných v rámci operace payment/refund platební brána danou operaci neprovede (návratový parametr resultCode je nastaven na 110, Invalid parametr {name}).
V případě, že FS odmítne daný požadavek na odhlášení (viz stav E10 v životním cyklu), platební brána operaci payment/refund neprovede, vrátí resultCode nastavený na 500, Rejected by EET. Detailní informace o důvodech odmítnutí lze zjistit provoláním operace payment/status.

Pokud je parametr verificationMode explicitně vyplněn v operaci payment/init nebo payment/oneclick/init na hodnotu 'true', musí jej obchodník vyplnit stejně i u případných volání payment/close nebo payment/refund s EET rozšířením v rámci dané platební transakce. Jinými slovy nelze nahlásit platbu v ověřovacím módu a následně ji odhlásit v neověřovacím módu.

Parametry EET rozšíření pro operaci `payment/status`

Nově přidaný parametr je extensions, obsahuje seznam všech předávaných rozšíření pro danou operaci (společně s EET rozšířením můžete použít i další nyní i v budoucnu dostupná rozšíření). Rozšíření eetV3 bude vyplněno pouze v odpovědi operace payment/status v případě, že u dané platební transakce bylo požadováno nahlášení platby pomocí payment/init nebo payment/oneclick/init.

Tučně uvedené parametry budou vždy vráceny (jsou povinné).

Položka	Typ	Popis
extension	String	ID rozšíření (přidělené na základě konfigurace platební bránou). Pro EET rozšíření bude nastaveno na hodnotu `eetV3`.
dttm	String	Datum a čas požadavku/odpovědi ve formátu YYYYMMDDHHMMSS.
report	Object	Struktura obsahující výsledek nahlášení platby.
cancel	List	Seznam objektů obsahujících výsledek jednoho nebo více odhlášení platby.
signature	String	Podpis rozšíření, kódováno v BASE64.

Struktura objektu report

Položka	Typ	Popis
eetStatus	Number	stav nahlášení platby, viz životní cyklus tržby
data	Object	parametry pro nahlášení platby zadané obchodníkem, viz výše popis struktury `data`
verificationMode	Boolean	příznak ověřovacího módu odesílání
vatId	String	DIČ poplatníka
receiptNumber	String	pořadové číslo účtenky, formát `YYYYMMRXXXXXXXXXX`, kde `YYYY` je rok, `MM` měsíc, `R` znak identifikující nahlášení platby, `XXXXXXXXXX` pořadové číslo účtenky, např. `201701R0000000004`
receiptTime	String	datum a čas přijetí tržby
evidenceMode	Number	režim platby, platební brána podporuje pouze běžný režim, bude vrácena hodnota `0`
uuid	String	UUID datové zprávy evidované tržby
sendTime	String	datum a čas odeslání zprávy z platební brány
acceptTime	String	datum a čas přijetí zprávy na FS
bkp	String	bezpečnostní kód poplatníka
pkp	String	podpisový kód poplatníka
fik	String	fiskální identifikační kód
rejectTime	String	datum a čas odmítnutí zprávy na FS
error	Object	error zpracování na FS, viz popis objektu `error`
warning	List	seznam případných varování z FS, viz popis objektu `warning`

Struktura položky v seznamu cancel

Položka	Typ	Popis
eetStatus	Number	stav odhlášení platby, viz životní cyklus
data	Object	parametry pro odhlášení platby zadané obchodníkem, viz výše popis struktury `data`
verificationMode	Boolean	příznak ověřovacího módu odesílání
vatId	String	DIČ poplatníka
receiptNumber	String	pořadové číslo účtenky, formát `YYYYMMCXXXXXXXXXX`, kde `YYYY` je rok, `MM` měsíc, `C` znak identifikující odhlášení platby, `XXXXXXXXXX` pořadové číslo účtenky, např. `201701C0000000005`
receiptTime	String	datum a čas přijetí tržby
evidenceMode	Number	režim platby, platební brána podporuje pouze běžný režim, bude vrácena hodnota `0`
uuid	String	UUID datové zprávy evidované tržby
sendTime	String	datum a čas odeslání zprávy z platební brány
acceptTime	String	datum a čas přijetí zprávy na FS
bkp	String	bezpečnostní kód poplatníka
pkp	String	podpisový kód poplatníka
fik	String	fiskální identifikační kód
rejectTime	String	datum a čas odmítnutí zprávy na FS
error	Object	error zpracování na FS, viz popis objektu `error`
warning	List	seznam případných varování z FS, viz popis objektu `warning`

Struktura objektu error

Položka	Typ	Popis
code	Number	kód chyby
desc	String	textový popis chyby

Struktura položky v seznamu warning

Položka	Typ	Popis
code	Number	kód varování
desc	String	textový popis varování

Příklad response pro `payment/status` s rozšířením `eetV3` - příklad nahlášení

{
  "dttm": "20170119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "3090adf87eda7CA",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 7,
  "authCode": "453708",
  "extensions": [
    {
      "extension": "eetV3",
      "dttm": "20170119113916",
      "report": {
        "eetStatus": 3,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": 17896.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000004",
        "receiptTime": "2017-01-19T11:38:44+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d29",
        "sendTime": "2017-01-19T11:38:45+01:00",
        "acceptTime": "2017-01-19T11:38:46+01:00",
        "bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
        "fik": "ab0fabcc-fa83-4de1-a3d3-fb055ebf5b70"
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}

Řetězec pro výpočet nebo pro ověření podpisu je pro toto rozšíření seskládaný v pořadí, v jakém jsou položky uvedeny ve specifikaci (viz výše).

eetV3|20170119113916|3|181|00/2535/CN58|17896.00|false|CZ72080043|201701R0000000004|2017-01-19T11:38:44+01:00|0|4eba2649-1f5e-48bd-a8f8-046c0b1a5d29|2017-01-19T11:38:45+01:00|2017-01-19T11:38:46+01:00|03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3|ab0fabcc-fa83-4de1-a3d3-fb055ebf5b70

Příklad response pro `payment/status` s rozšířením `eetV3` - příklad neúspěšného nahlášení, transakce je automaticky okamžitě reverzována

{
  "dttm": "20170119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "3090adf87eda7CA",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 5,
  "extensions": [
    {
      "extension": "eetV3",
      "dttm": "20170119113916",
      "report": {
        "eetStatus": 5,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": 17896.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000004",
        "receiptTime": "2017-01-19T11:38:44+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d29",
        "sendTime": "2017-01-19T11:38:45+01:00",
        "rejectTime": "2017-01-19T11:38:46+01:00",
        "bkp": ""01234567-89abcdef-01234567-89abcdef-01234567",
        "error": {
          "code": 5
          "desc":"Neplatny kontrolni bezpecnostni code poplatnika (BKP)"
         }
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}

Řetězec pro výpočet nebo pro ověření podpisu je pro toto rozšíření seskládaný v pořadí, v jakém jsou položky uvedeny ve specifikaci (viz výše).

eetV3|20170119113916|5|181|00/2535/CN58|17896.00|false|CZ72080043|201701R0000000004|2017-01-19T11:38:44+01:00|0|4eba2649-1f5e-48bd-a8f8-046c0b1a5d29|2017-01-19T11:38:45+01:00|2017-01-19T11:38:46+01:00|01234567-89abcdef-01234567-89abcdef-01234567|5|Neplatny kontrolni bezpecnostni code poplatnika (BKP)

Příklad response pro `payment/status` s rozšířením `eetV3` - příklad nahlášení s varováním

{
  "dttm": "20170119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "3090adf87eda7CA",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 7,
  "authCode": "453708",
  "extensions": [
    {
      "extension": "eetV3",
      "dttm": "20170119113916",
      "report": {
        "eetStatus": 3,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": 17896.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000004",
        "receiptTime": "2017-01-19T11:38:44+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d29",
        "sendTime": "2017-01-19T11:38:45+01:00",
        "acceptTime": "2017-01-19T11:38:46+01:00",
        "bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
        "fik": "ab0fabcc-fa83-4de1-a3d3-fb055ebf5b70",
        "warning": [
         {
            "code": 1,
            "desc":"DIC poplatnika v datove zprave se neshoduje s DIC v certifikatu"
          },
          {
            "code": 2,
            "desc":"Chybny format DIC poverujiciho poplatnika"
          }
        ]
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}

Řetězec pro výpočet nebo pro ověření podpisu je pro toto rozšíření seskládaný v pořadí, v jakém jsou položky uvedeny ve specifikaci (viz výše).

eetV3|20170119113916|3|181|00/2535/CN58|17896.00|false|CZ72080043|201701R0000000004|2017-01-19T11:38:44+01:00|0|4eba2649-1f5e-48bd-a8f8-046c0b1a5d29|2017-01-19T11:38:45+01:00|2017-01-19T11:38:46+01:00|03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3|ab0fabcc-fa83-4de1-a3d3-fb055ebf5b70|1|DIC poplatnika v datove zprave se neshoduje s DIC v certifikatu|2|Chybny format DIC poverujiciho poplatnika

Příklad response pro `payment/status` s rozšířením `eetV3` - příklad nahlášení - transakce zařazená do zúčtování na nižší částku

{
  "dttm": "20170119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "3090adf87eda7CA",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 7,
  "authCode": "453708",
  "extensions": [
    {
      "extension": "eetV3",
      "dttm": "20170119113916",
      "report": {
        "eetStatus": 3,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": 12896.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000004",
        "receiptTime": "2017-01-19T11:38:44+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d29",
        "sendTime": "2017-01-19T11:38:45+01:00",
        "acceptTime": "2017-01-19T11:38:46+01:00",
        "bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
        "fik": "ab0fabcc-fa83-4de1-a3d3-fb055ebf5b70"
      },
      "signature": "base64-encoded-extension-signature"
    }
  ]
}

Příklad response pro `payment/status` s rozšířením `eetV3` - příklad nahlášení i odhlášení - autorizovaná transakce s několikerým částečným vrácením

{
  "dttm": "20170119113916",
  "signature": "base64-encoded-response-signature",
  "payId": "3090adf87eda7CA",
  "resultCode": 0,
  "resultMessage": "OK",
  "paymentStatus": 10,
  "extensions": [
    {
      "extension": "eetV3",
      "dttm": "20170119113916",
      "report": {
        "eetStatus": 3,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": 17896.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000010",
        "receiptTime": "2017-01-18T09:38:44+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d29",
        "sendTime": "2017-01-18T09:38:44+01:00",
        "acceptTime": "2017-01-18T09:38:45+01:00",
        "bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
        "fik": "ab0fabcc-fa83-4de1-a3d3-fb055ebf5b70"
      },
      "cancel": [{
        "eetStatus": 9,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": -1896.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000015",
        "receiptTime": "2017-01-19T11:35:44+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d01",
        "sendTime": "2017-01-19T11:35:45+01:00",
        "acceptTime": "2017-01-19T11:35:46+01:00",
        "bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
        "fik": "987a6be5-6af5-44f3-b4fc-987654321000-03"
      },
      {
        "eetStatus": 12,
        "data": {
          "premiseId": 181,
          "cashRegisterId": "00/2535/CN58",
          "totalPrice": -521.00
        },
        "verificationMode": false,
        "vatId": "CZ72080043",
        "receiptNumber": "201701R0000000017",
        "receiptTime": "2017-01-19T11:39:14+01:00",
        "evidenceMode": 0,
        "uuid": "4eba2649-1f5e-48bd-a8f8-046c0b1a5d01",
        "sendTime": "2017-01-19T11:39:15+01:00",
        "acceptTime": "2017-01-19T11:39:16+01:00",
        "bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
        "fik": "112a6be5-6af5-44f3-b4fc-987654321000-03"
      }
      ],
      "signature": "base64-encoded-extension-signature"
    }
  ]
}

Poznámka: Podpis původních parametrů operace payment/status je nezměněn. Položka extensions obsahující seznam jednotlivých posílaných rozšíření nijak nezasahuje do výpočtu původního podpisu zprávy. Každé rozšíření má svůj vlastní podpis. Pro podepisování / ověření podpisu rozšíření je použit stejný algoritmus (SHA1withRSA).

Testování EET a přechod do produkce

Testování implementace EET rozšíření eAPI do e-shopu

Změny

[24.2.2017] upřesněno nastavení EET v POSMerchant aplikaci
[7.3.2017] upřesněn popis simulace stavů E4-E7

Rozšíření pro EET je od 3.2.2017 dostupné v testovacím prostředí platební brány ("iBrána"). Podobně jako u základní integrace eAPI si můžete vyzkoušet volání brány a zpracování návratových informací do e-shopu. iBrána vrací smyšlená EET data, formátově odpovídající skutečným datům, která se na produkčním prostředí vrací od Finanční správy (dále FS).

Testování životního cyklu tržby

Platební brána umožňuje na integračním prostředí iBrána otestovat jednotlivé stavy v životním cyklu tržby pomocí vhodně nastaveného parametru cashRegisterId. Obchodník v EET rozšíření nastaví tento parametr v rámci volání operace payment/init, případně payment/close. Výsledek nahlášení nebo odhlášení tržby získá obchodník voláním operace payment/status.

cashRegisterId	Simulovaný stav	Poznámka
E4	E4 - Tržba evidována offline	Simulace offline zpracování. Platební brána se pokouší o EET nahlášení v hodinových intervalech následujících 48 hodin. V případě simulátoru druhý pokus projde a EET stav se změní na E6.
E5	E5 - FS odmítla hlášení tržby	Simulace stavu, kdy nahlášení neproběhlo. U autorizované transakce se provádí okamžitý reversal.
E6	E6 - Tržba evidována offline a odeslána online během 48 hodin	Simulace dodatečného odeslání hlášení a přijetí serverem FS, viz popis u stavu E4. (Pro simulaci tohoto stavu je potřeba nastavit cashRegisterId na hodnotu E4 a vyčkat na provedení opakovaného nahlášení, pak se stav změní na E6.)
E7	E7 - Tržba evidována offline a NEodeslána online během 48 hodin	Simulace dodatečného odeslání hlášení a NEpřijetí serverem FS (podobné chování jako u E5, transakce je zamítnuta).
xxx	E3 - Tržba nahlášena online	Jakákoli hodnota mimo výše uvedené simuluje úspěšné online nahlášení.

Simulace odhlášení je na platební bráně na integračním prostředí zjednodušena na stav E9 - Tržba odhlášena online.

Potřebné kroky pro zprovoznění EET na iBráně

požádat ČSOB o povolení EET rozšíření pro daného obchodníka
v aplikaci POSMerchant na integračním prostředí provést v části "Nastavení obchodníka" nahrání EET certifikátu, dále v části "Platební brány" aktivaci certifikátu pro zadané provozovny a nakonec v "Nastavení platební brány" provést konfiguraci povolených platebních metod
pomocí eAPI 1.6 nebo vyšší provést operaci payment/init s vyplněným EET rozšířením, provést autorizaci transakce a případné zařazení do zúčtování (pokud není nastaveno automatické zařazení do zúčtování)
ověřit pomocí operace payment/status výsledek EET nahlášení
provést reversal transakce pomocí operace payment/reverse (EET odhlášení se v tomto případě provede automaticky)
ověřit pomocí operace payment/status výsledek EET odhlášení

Poznámka: EET rozšíření bude automaticky povolené na obou prostředích - integračním i produkčním.

Přechod do produkčního prostředí po otestování na iBráně

v aplikaci POSMerchant na produkčním prostředí provést v části "Nastavení obchodníka" nahrání EET certifikátu, dále v části "Platební brány" aktivaci certifikátu pro zadané provozovny a nakonec v "Nastavení platební brány" provést konfiguraci povolených platebních metod
pomocí eAPI 1.6 nebo vyšší provést operaci payment/init s vyplněným EET rozšířením s parametrem verificationMode nastaveným na hodnotu true, provést autorizaci transakce a případné zařazení do zučtování (pokud není nastaveno automatické zařazení do zúčtování)
ověřit pomocí operace payment/status výsledek EET nahlášení
provést reversal transakce pomocí operace payment/reverse (EET odhlášení se v tomto případě provede automaticky)
ověřit pomocí operace payment/status výsledek EET odhlášení

Poznámka: po ověření funkčnosti je potřeba v ostrém provozu nastavit parametr verificationMode na hodnotu false.

Časté otázky k EET <a name="PAGE_Časté-otázky-k-EET>

Tematické bloky

Obecně k EET v e-shopech

Které platební metody podléhají EET?

EET se původně netýkalo jen hotovostních tržeb, ale i bezhotovostních plateb, které splňují definici “bezhotovostního převodu peněžních prostředků, k němuž dává příkaz plátce prostřednictvím příjemce”. Jednalo se tak zejména o platby kartou (jakéhokoli typu - debetní, kreditní, předplacenou). Po rozhodnutí Ústavního soudu se povinnost evidovat tržby od 1. března 2018 nevztahuje na platby kartou, a to jak prostřednictvím platebních terminálů, tak online platby přes internet.

Které platby online musí být hlášeny do EET?

V současné době není povinné hlášení tržby uhrazené žádnou platební metodou, kterou poskytuje platební brána ČSOB. Hlášení tržeb z platební brány je tedy dobrovolné.

Kdy platební brána hlásí tržbu Finanční správě?

K hlášení tržby dochází bezprostředně před zařazením transakce do zúčtování. Podmínkou pro nahlášení tržby je úspěšná autorizace transakce a žádost obchodníka o zařazení transakce do zúčtování podaná během 7 dnů od autorizace. Pokud obchodník nepodá žádost o zařazení transakce do zúčtování během 7 dnů, platební transakce zaniká a nelze ji zúčtovat (toto pravidlo platí na bráně obecně a je dáno lhůtami karetních asociací, EET na něj nemá vliv).

Při zakládání transakce na platební bráně (operace payment/init) si může obchodník zvolit mezi automatickým a "manuálním" zařazením do zúčtování. Při automatickém zařazení transakce do zúčtování proběhe autorizace, nahlášení tržby do EET a zařazení transakce do zúčtování jako 3 akce bezprostředně za sebou v rámci volání operace payment/process. Pokud obchodník zvolí "manuální" zařazení transakce do zúčtování, může během 7 dnů ovlivnit jak okamžik podání žádosti o zařazení transakce do zúčtování, tak její částku (tyto možnosti vystihují princip "převodu peněžních prostředků, k němuž dává příkaz plátce prostřednictvím příjemce"). Při expedici zboží nebo po dopočtení konečné ceny nákupu může obchodník zažádat o zařazení transakce do zúčtování na autorizovanou nebo nižší částku (technická realizace voláním operace payment/close). V ten moment provede platební brána hlášení tržby, a je-li toto hlášení úspěšné, zařadí transakci do zúčtování.

Tento postup zajistí hlášení tržby vždy dříve, než je limit stanovený Stanoviskem Generálního finančního ředitelství jako "nejpozději v okamžiku, kdy se (poplatník) dozví o tom, že došlo k odepsání platby z účtu plátce (zákazníka) a jejímu odeslání poplatníkovi".

Co se stane, když EET vypadne, nebo se nepodaří komunikovat s EET?

V takovém případě za vás brána vygeneruje kódy BKP a FIK, které vám vrátí. Zákazníkovi pak předáte účtenku s těmito kódy. Následně se brána bude pokoušet po dobu dalších 48 hodin tržbu nahlásit. O tyto opakované pokusy se váš e-shop nemusí nijak starat. Jakmile se hlášení povede, brána získá a uloží FIK. Aktuální stav můžete kdykoli zjistit voláním payment/status. Zavoláte-li status po úspěšném nahlášení online, vrátí se vám i FIK. Další účtenku již vystavovat podle metodiky nemusíte, FIK v této situaci slouží pouze pro vaši evidenci.

Jen pozor na to, že výpadek komunikace nebo EET je něco jiného než zamítnuté hlášení tržby. Zamítne-li Finanční správa hlášení tržby, pak vám platbu zamítneme.

Obecně k řešení na platební bráně ČSOB

Jaké jsou hlavní výhody řešení EET přes platební bránu ČSOB?

EET nijak neomezuje existující platební funkce brány
není nutné z e-shopu komunikovat přímo s Finanční správou
jde o flexibilní řešení, které umožní předávat do systému Finanční správy všechny aktuálně platné parametry v EET hlášení
je připraveno na postupné zavedení EET do různých segmentů maloobchodu a velkoobchodu - částka hlášené tržby není vázána na částku transakce, tj. je možné provádět platby, ze kterých pouze část podléhá hlášení do EET
platební brána vyřeší všechny situace, které mohou v EET nastat, včetně generování kódů na účtenky při výpadku komunikace nebo systému EET, následného nahlášení během lhůty 48 hodin atd.
při vracení plateb přes platební bránu (např. z důvodu neodebrání nebo vratky zboží) zajistí brána i odhlášení celé tržby nebo její části
v obchodnickém portálu má obchodník přehled o hlášeních EET včetně možnosti vyexportovat si přehled v několika běžných datových formátech

Jak probíhá hlášení tržby skrze platební bránu?

Při žádosti o zpracování platby obchodník připojí data pro hlášení tržby. Jde zejména o rozpad tržby do daňových sazeb, protože touto informací brána dnes standardně nedisponuje. Platební brána ohlásí tržbu ihned po schválení platby například vydavatelem karty. Obchodník tedy od banky dostane FIK jako součást potvrzení o schválení platby.

Kdo doručí klientovi účtenku při platbě v e-shopu?

Účtenku vytvoří a klientovi “předá” obchodník. Platební brána mu pro to poskytne všechny potřebné údaje. Účtenka může být jak papírová, tak elektronická a zákon způsob jejího předání neupravuje. Pokud tedy klient platí např. film v online videopůjčovně, obchodník mu účtenku zašle nejspíše e-mailem (nebo jiným způsobem v závislosti na tom, jak obchodník a klient komunikují). Je-li placena klasická objednávka zboží v e-shopu, obchodník může účtenku zaslat klasicky jako fakturu v krabici se zbožím.

Prodávám v cízí měně a na bráně používám službu multicurrency. Jak nahlásím tržbu?

Do EET se musí vše hlásit v korunách. Bez ohledu na měnu platební transakce tedy vyplňte do eAPI rozšíření pro EET částku tržby v Kč. Volba kurzu je v tomto případě zcela na vás, brána do konverze nijak nevstupuje. V praxi bude obchodník typicky volit svůj účetní kurz daného dne.

Co EET na platební bráně neumí?

EET na platební bráně není univerzální EET kanál, ale slouží pouze pro hlášení tržeb souvisejících s platebními transakcemi procesovanými platební bránou. Hotovostní tržbu na prodejně tedy přes bránu nenahlásíte. Platební brána také hlásí všechny platby v bežném režimu, nepodporuje hlášení ve zjednodušeném režimu.

Mohu si EET na platební bráně nějak vyzkoušet?

Ano, eAPI rozšíření pro EET je dostupné i na iBráně. V odpovědi dostanete smyšlená data, protože naše iBrána není propojena s Finanční správou a stejně jako u testování plateb na iBráně vše končí na simulátoru. Jakmile budeme mít na straně e-shopu technicky funkční implementaci, můžete si EET vyzkoušet v produkčním prostředí (tj. již s použitím vašich autentizačních údajů pro EET, označení provozovny, pokladny atd.). V ověřovacích transakcích na produkčním prostředí nezapomeňte vyplnit "Příznak ověřovacího módu odesílání".

EET extension není zpřístupněna pro anonymní merchant ID. Pro otestování extension je potřeba mít uzavřenou smlouvu s bankou a přidělené Merchant ID ve tvaru M1xxxxxxxx.

Co musí obchodník udělat pro používání služby EET na platební bráně?

V první řadě se musí obchodník registrovat na Finanční správě a získat tzv. autentizační údaje. Pokud již obchodník používá služby platební brány ČSOB, pak stačí jen naimplementovat do e-shopu rozšíření komunikačního rozhraní pro EET.

Transakční scénáře

Co za mě s ohledem na EET vyřeší platební brána?

Platební brána řeší technickou integraci s Finanční správou, nahlášení všech autorizovaných platebních transakcí do EET a odhlašování tržeb v případě vratek plateb. V případě výpadku spojení zajistí generování kódů BKP, PKP a dodatečné nahlášení tržby online. Klíčovou vlastností systému je, že při standardním online hlášení tržby obdrží obchodník kód FIK společně s informací o autorizaci platební transakce.

Co naopak musím udělat sám?

Prvotně se musíte zaregistrovat k EET, získat autentizační údaje. U Finanční správy si musíte v nastavení EET vytvořit provozovnu(y) a pokladnu(y). V běžném provozu musíte zejména vědět, co všechno ve vašem podnikání podléhá EET a jak vyplnit hlášení. Platební brána poskytuje na svém API všechna pole, která je možné odeslat do systému Finanční správy, ale validuje jen vyplnění povinných polí. Platební brána nevidí do rozdělení DPH a dalších dat, k jejichž vyplnění je nutná znalost přesného kontextu transakce. Musíte tedy vědět, jak a co do hlášení tržby vyplnit. Totéž samozřejmě platí i pro odhlašování transakcí zejména při vracení plateb.

Jak probíhá hlášení tržby skrze platební bránu?

Při žádosti o zpracování platby obchodník připojí data pro hlášení tržby. Je to zejména rozpad tržby do daňových sazeb, protože touto informací brána dnes standardně nedisponuje. Platební brána ohlásí tržbu ihned po schválení platby například vydavatelem karty. Obchodník tedy od banky dostane FIK jako součást potvrzení o schválení platby.

Kdo doručí klientovi účtenku při platbě v e-shopu?

Účtenku vytvoří a klientovi “předá” obchodník. Platební brána mu pro to poskytne všechny potřebné údaje. Účtenka může být jak papírová, tak elektronická a zákon způsob jejího předání neupravuje. Pokud tedy klient platí např. film v online videopůjčovně, obchodník mu účtenku zašle nejspíše e-mailem (nebo jiným způsobem, v závislosti na tom, jak obchodník a klient komunikují). Je-li placena klasická objednávka zboží v e-shopu, obchodník může účtenku zaslat klasicky jako fakturu v krabici se zbožím.

Co když zákazník zboží neodebere nebo vrátí?

V takovém případě platební brána pro obchodníka zpracuje jak vratku samotné finanční transakce, tak odhlášení tržby z EET. Brána i při vratkách samozřejmě řeší i situaci, ve které se různě kombinují částky podléhající a nepodléhající EET. Více informací najdete v popisu životního cyklu tržby.

Přijal jsem platbu kartou, zákazník vrátil zboží a dostal vratku hotově nebo na účet. Jak platbu odhlásím?

V takovém případě musíte platbu odhlásit jinak. Platební brána vám umožní odhlásit tržbu pouze při použití API funkce payment/reverse nebo payment/refund, případně ručně v aplikaci POS Merchant. Vratkou jinak než na kartu jste porušili obchodní podmínky akceptace platebních karet, které vyžadují vratku výhradně na kartu, ze které bylo placeno. Zbytečně se vystavujete reklamačním rizikům karetních transakcí a příště použijte pro vracení funkci payment/refund nebo zadejte vratku ručně v systému POS Merchant.

Co se děje, když obchodník nahlásí tržbu špatně?

Pokud Finanční správa odmítne hlášení tržby (například proto, že obchodník uvede špatné identifikační údaje provozovny), platební brána okamžitě platbu stornuje a obchodník se dozví o důvodech zamítnutí hlášení tržby. Protože platba byla až do tohoto momentu zpracovávána v mezibankovních systémech a obchodníkovi nebyla bankou platba garantována, z pohledu obchodníka tržba neexistuje a obchodník není vystaven rizikům spojeným s realizací tržby bez nahlášení.

Nastavení služby a specifické situace v EET

Co znamená provozovna a pokladna v EET? Jak nastavit provozovnu a pokladnu při použití platební brány?

Pro EET je principiálně nutné mít alespoň jednu provozovnu a jednu pokladnu. Číslo provozovny přiděluje Finanční správa, označení pokladny je na obchodníkovi. Řešení na platební bráně je z tohoto pohledu flexibilní. V každé transakci obchodník říká, pro jakou provozovnu a pokladnu chce tržbu nahlásit. Není tedy nutné bance žádné z těchto údajů sdělovat a nechat nastavovat předem. Provozovnou ve významu pro Zákon o evidenci tržeb je URL e-shopu. Provozujete-li s jedním bankovním Merchant ID platební bránu pro více e-shopů (např. cz, sk a eu domény pro stejnou firmu, stejné IČO a stejné Merchant ID), můžete posílat s každou transakcí na platební bránu jiné ID provozovny.

Jak nastavím provozovnu a pokladnu?

Provozovnu a pokladnu můžete nastavovat pro každou transakci přes eAPI. Transakce na platební bráně tak nemusí být přiřazovány jen jedné provozovně nebo jedné pokladně. Tuto funkci využijete např. v situaci, kdy jeden centrální systém inicializuje transakce, které jsou ve skutečnosti realizovány např. mobilními pokladnami. Jen si dejte pozor, že všechny provozovny mají platné ID přidělené Finanční správou.

Jaké brána používá číslo účtenky? Nevidím možnost jej nastavit přes API.

Pořadové číslo účtenky přiděluje platební brána. Jedná se o sekvenční ID, které je jedinečné pro konkrétní ID obchodníka (Merchant ID) bez rozlišení číselných řad pro provozovny a pokladny. Pro přehlednost a následnou lidskou srozumitelnost číslo účtenky sestává z roku, měsíce, příznaku, zda jde o hlášení nebo odhlášení, a samotného sekvenčního ID.

Co je při platbě kartou datum a čas přijetí tržby?

Datum a čas přijetí tržby vstupuje do výpočtu PKP, tedy kódu, který se uvádí na účtenku v případě, že se bráně nepodaří tržbu nahlásit v online režimu. V případě platby kartou je datum a čas přijetí tržby čas autorizace transakce, tedy datum a čas, ve kterém ČSOB obdržela od karetní asociace informaci o schválení transakce vydavatelem karty.

Podporuje platební brána režimy zastoupení?

Ano, velice flexibilně a na úrovni transakce. Přímo v transakčním volání na API specifikujete DIČ pro vámi zvolený režim zastoupení, není tedy problém realizovat platby na bráně v zastoupení více subjektů. Stejně jako u provozoven a pokladen platí, že není třeba nic nastavovat v bance, vše se dynamicky nastavuje přes API na úrovni volání transakce.

Časté funkční a komerční dotazy

Můžeme přijímat platby v eurech?

Ano, příchozí platby budou připisovány na váš eurový účet nebo konvertovány do korun a připisovány na běžný korunový účet. Vše dle vašeho rozhodnutí.

V jakých měnách je možné přijímat platby?

Na platební bráně můžete momentálně přijímat platby v českých korunách (CZK), eurech (EUR), amerických dolarech (USD), britských librách (GBP), forintech (HUF), polských zlotých (PLN), chorvatských kunách (HRK), rumunských nových lei (RON), norských korunách (NOK) a švédských korunách (SEK).

Jak jsou online platby zabezpečeny?

Komunikace platební brány s klienty je zabezpečena protokolem https. Komunikace s obchodníky je podepisována pomocí elektronických klíčů, které zabezpečují důvěryhodnost komunikace. Platební brána si tak je jista, že komunikuje s obchodníkem, a současně obchodník dostává potvrzení transakcí podepsané bankou. Samotné transakce kartou online jsou zabezpečeny technologií 3D-Secure.

Co je 3D-Secure?

3D-Secure je systém zabezpečení karetních transakcí online. Citlivá platební data zpracovává pouze banka a současně klient musí potvrdit transakci např. pomocí SMS kódu. Technologie je známa také pod komerčními názvy MasterCard SecureCode a Verified by Visa.

Jak můžeme prohlížet transakce uskutečněné na našem e-shopu?

Transakce uskutečněné na platební bráně i na platebních terminálech najdete po přihlášení do systému ČSOB POS Merchant (přístupové údaje najdete ve vaší smlouvě s bankou).

Klient neodebral celou objednávku, jak mu můžeme část platby vrátit?

Přihlaste se do systému POS Merchant, vyhledejte původní transakci a zadejte částečnou vratku.

Musím mít veden účet v ČSOB, aby bylo možné přijímat platby online?

Ano, podmínkou poskytování služeb akceptace karet online je vedení běžného účtu u ČSOB. V našich balíčkách služeb pro internetové obchodníky vám rádi tento účet nabídneme za zvýhodněných podmínek.

Funguje platební brána na tabletech a smartphonech?

Samozřejmě. Jako obchodník nemusíte technicky nic řešit, brána se automaticky přizpůsobí zařízení klienta, ať se jedná o telefon, tablet či počítač.

Kdy budou na můj účet připsány karetní platby?

Platby českými kartami jsou ve většině případů připsány na účet obchodníka následující pracovní den po provedení platby na platební bráně.

Je třeba měnit technickou implementaci, když banka zprovozní vylepšenou verzi brány s novými službami?

Rozhraní platební brány je verzované, a proto není nutné okamžitě přecházet na novou verzi. V dlouhodobém horizontu mohou nicméně zastaralé služby a funkce být odstavovány. V takovém případě budete včas informováni o nutnosti přejít na novější verzi rozhraní platební brány.

Je možné výpisy karetních transakcí propojit do účetnictví?

Ano, většina účetních programů podporuje import výpisů.

Je možné strhnout klientovi peníze z karty až při odeslání zboží a současně mít garanci platby již v okamžiku objednávky?

Jistě. U každé transakce můžete nastavit, zda se má transakce poslat do zúčtování automaticky na konci dne, nebo manuálně. V případě manuální uzávěrky jsou prostředky garantovány (blokovány) po dobu sedmi dní, během kterých je nutné platbu uzavřít buď v systému POS Merchant, nebo pomocí API platební brány.

Transakce platebním tlačítkem ČSOB / Poštovní spořitelny je klientem z účtu zaplacena, v POS Merchantu ji vidím jako autorizovanou, ale v mém e-shopu je transakce zamítnutá.

Transakce platebním tlačítkem má jedno specifikum v životním cyklu - autorizovaná transakce se okamžitě dostane do stavu 8. Je možné, že váš e-shop vyhodnocuje jako "zaplaceno" pouze stavy 4 a 7. Je tedy nutné provést drobný zásah do integrace v e-shopu.

Klient si stěžuje, že nemůže zaplatit kartou - jak můžeme zjistit, kde je problém?

Ve většině případů je problémem nepovolení internetových transakcí na kartě klienta. V takovém případě se musí klient obrátit na svoji banku a nechat online platby povolit.

Je možné přijímat karty i na výdejně zboží?

Samozřejmě. Výdejnu zboží je možné vybavit platebním terminálem, který vám v balíčku s akceptací karet online rádi nabídneme za zvýhodněných podmínek. Transakce online i z terminálů pak můžete jednoduše spravovat v jednom administrátorském systému ČSOB POS Merchant (přístupové údaje najdete ve vaší smlouvě s bankou).

Časté technické dotazy

Při odeslání požadavku na native API se vrací http status 400, bad request

Pravděpodobně se jedná o špatný podpis požadavku. Nejčastější chyby a opomenutí jsou následující:

řetězec pro výpočet podpisu je chybný nebo je použit špatný algoritmus pro podpis požadavku, více viz specifikace v rámci eAPI
používá se špatný privátní klíč obchodníka pro podpis požadavku (jedná se např. o záměnu privátního klíče pro integrační a produkční prostředí)
v případě parametru closePayment u operace payment/init se do řetězce pro podpis nevkládá povolená hodnota true nebo false, ale (v případě použití php) hodnota 1 nebo 0

Jaký algoritmus nastavit při vytváření a ověřování podpisu?

Pro podepisování je potřeba použít algoritmus založený na SHA-1 (pro eAPI v1.7 a nižší), nebo SHA-256 (pro eAPI v1.8 a vyšší). Například v Javě je potřeba použít při inicializaci třídy java.security.Signature algoritmus "SHA256withRSA", v PHP je potřeba použít pro volání funkcí openssl_sign() a openssl_verify() algoritmus "OPENSSL_ALGO_SHA256".

Kolik může košík obsahovat položek?

Ve verzi v1.0, v1.5, v1.6, v1.7 a v1.8 musí být v košíku nejméně jedna (například "dobití kreditu"), nejvýše dvě položky (například "nákup na mujobchod" a "poštovné").

Při odesílání payment/init se vrací chybový kód 900

Pozor na správné zformátování položek košíku, platební brána očekává pro parametr cart seznam prvků, tzn. položky musí být uzavřeny v [ a ], a to i v případě, že košík obsahuje jen jednu položku.

správně:

"cart":[ { "name":"Rezervace", "quantity":1, "amount":10000 } ]

špatně:

"cart": { "name":"Rezervace", "quantity":1, "amount":10000 }

Pozor na formátování parametru extensions pro EET, je třeba jej formátovat také jako pole, ne jako objekt.

"extensions":[ { "extension": "eetV3", "dttm": "20170125131559", "data": { "premiseId": 181, "cashRegisterId": "00/2535/CN58", "totalPrice": 17896.00 }, "signature": "base64-encoded-extension-signature" } ]

Jak načíst veřejný klíč ve formátu PEM?

Veřejný klíč platební brány potřebný na straně obchodníka k ověření podpisu odpovědi je distribuován v textovém PEM formátu. Níže jsou uvedeny příklady jeho inicializace před vlastním použitím v programovacích jazycích Java, PHP a pro platformu .NET.

JAVA

String publicKeyFileName = "test.pub";
String content = FileUtils.readFileToString(new File(publicKeyFileName));
content = StringUtils.remove(content, "-----BEGIN PUBLIC KEY-----");
content = StringUtils.remove(content, "-----END PUBLIC KEY-----");
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64.decodeBase64(content));
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PublicKey publicKey = keyFactory.generatePublic(keySpec);

PHP

$publicKeyFileName = "test.pub";
$fp = fopen ($publicKeyFileName, "r" );
if (! $fp) {
    throw new Exception ( "Public key " . $publicKeyFileName . " not found" );
}
$content = fread ($fp, filesize ( $publicKeyFileName ) );
fclose ( $fp );
$publicKey = openssl_get_publickey ( $content );

.NET

Ukázka načítání klíče pro podepisování a ověřování podpisu je v samostatném snippetu, který najdete v repu.

Při odeslání payment/process se vrací http status 404, not found

Operace payment/process se volá pomocí http metody GET. Zkontrolujte, zda je poslední část url - parametr signature - "URL encoded". Vzhledem k tomu, že podpis požadavku je přenášen v kódování Base64, obsahuje pravděpodobně i znak /. Platební brána takto nesprávně formátovaný požadavek nepřijme (nemůže načíst správně parametr signature).

Legacy API (migrace z GP Webpay) a ověření stavu platby

Legacy API neumožňuje ověření stavu platby. Operace payment/status je podporovaná v eAPI.

Jaké časové pásmo použít pro vyplnění hodnoty parametru dttm?

Pro parametr dttm posílaný v požadavcích na platební bránu doporučujeme vyplnit hodnotu pro časové pásmo Europe/Prague. Stejné časové pásmo je použito pro vyplnění parametru dttm v odpovědích z platební brány. Přínosem pro obchodníka bude snazší orientace při dohledávání případných problémů v odesílaných požadavcích, platební brána nicméně nijak nekontroluje nastavené časové pásmo. Tento parametr je primárně použit pro výpočet podpisu.

Jaké kódování použít pro české znaky v JSON datech?

Texty předávané v JSON požadavcích je potřeba kódovat v UTF-8.

Založení platby proběhne neúspěšně z důvodu chybové SSL hlášky?

Je možné, že používáte nepodporovanou/starou verzi openssl, případně kryptografické protokoly SSL v2/v3/tls1.0 nebo tls1.1. Doporučujeme tedy aktualizovat verzi OpenSSL s podporou nejméně TLS v1.2 v případě výskytu níže uvedené hlášky.

reason: error:14077410:SSL routines:SSL23 _GET_SERVER_HELLO:sslv3 alert handshake failure

Integrace - TLS v1.2 vyžadováno od 12/2017

Produkce - TLS v1.2 vyžadováno od 07/2018

Založení platby proběhne neúspěšně z důvodu nedůvěryhodného certifikátu při komunikaci s eAPI

Server obchodníka, na kterém běží jeho e-shop, komunikuje s eAPI pomocí adresy https://api.platebnibrana.csob.cz zabezpečené pomocí https protokolu. Obchodník na straně e-shopu v rámci integrace nastavuje nejenom adresu serveru platební brány, ale podle typu použité technologie (např. Java) musí/může provést i dodatečnou konfiguraci spočívající v přidání jednoho nebo více certifikátů, které jsou vystaveny pro https://api.platebnibrana.csob.cz do tzv. truststore souboru. Tímto způsobem je na straně e-shopu nastaveno, že při navazování bezpečného spojení s https://api.platebnibrana.csob.cz má e-shop tomuto serveru důvěřovat. Implementace důvěry certifikátů je na rozhodnutí programátora třetí aplikace. Doporučujeme tuto integraci z bezpečnostních důvodů používat.

Certifikát pro https://api.platebnibrana.csob.cz je vydáván na omezenou dobu. Aktuální platnost a výměna je popsána v sekci Výměna certifikátu.

V případě problémů s navázáním spojení s https://api.platebnibrana.csob.cz je potřeba stáhnout nový certifikát z https://api.platebnibrana.csob.cz včetně všech CA certifikátů, kterými je tento nový certifikát podepsán. Tento nový certifikát včetně souvisejících CA certifikátů je pak potřeba přidat do truststore souboru (např. Java).

To, zda je nutné provést výše popsané přidání jednoho nebo více certifikátů do truststore souboru, závisí na konkrétním nastavení daného systému, na němž běží e-shop obchodníka. Je možné, že systém obchodníka, na kterém běží e-shop, používá v případě Java technologie defaultní cacerts soubor, ve kterém jsou uloženy kořenové certifikáty dodávané v rámci instalačního balíku Javy. V takovém případě s největší pravděpodobností nebude nutné provádět žádné úpravy (nový certifikát pro https://api.platebnibrana.csob.cz je podepsán pomocí certifikátu certifikační autority, který je podepsán kořenovým certifikátem uloženým v tomto cacerts souboru, kořenový certifikát je pro původní i nový certifikát pro https://api.platebnibrana.csob.cz stejný). Je potřeba mít také updatovaný JAVA balíček, ve kterém jsou aktuální CA certifikáty.

Výměna certifikátu https://api.platebnibrana.csob.cz

Týká se to zákazníků, kteří mají implementováno ověření důvěry certifikátů na https://api.platebnibrana.csob.cz.

Konec platnosti serverového certifikátu je v pondělí 4. září 2022. Měsíc předem bude zde zveřejněn termín výměny serverového certifikátu za nový. Pozor s novým certifikátem se mění i všechny nadřazené CA certifikáty.

Aktuální certifikát je možné nalézt na https://api.platebnibrana.csob.cz.

Transakce platebním tlačítkem ČSOB / Poštovní spořitelny je klientem z účtu zaplacena, v POS Merchantu ji vidím jako autorizovanou, ale v mém e-shopu je transakce zamítnuta

Transakce platebním tlačítkem má jedno specifikum v životním cyklu - autorizovaná transakce se okamžitě dostane do stavu 8. Je možné, že váš e-shop vyhodnocuje jako "zaplaceno" pouze stavy 4 a 7. Je tedy nutné provést drobný zásah do integrace v e-shopu.

Vygenerovaný klíč nelze automaticky stáhnout v Safari prohlížeči

Místo stažení se vygenerovaný klíč v keygen aplikaci ve starších verzích prohlížeče Safari pouze zobrazí na stránce. Pokud nemůžete aktualizovat na novější verzi Safari, doporučujeme manuálně uložit pomocí ⌘+S.

Stavy platební brány a komunikace s klientem <a name="PAGE_Stavy-platební-brány-a-komunikace-s-klientem>

Platební brána

Základní stav platební brány, ve kterém se nachází po přesměrování klienta od obchodníka. V levé části jsou údaje o obchodníkovi a nákupu, vpravo může klient zadat číslo karty nebo vybrat platbu MasterCard Mobile.

Zapamatované karty

Přijde-li klient s identifikací od obchodníka a již dříve si na bráně nechal zapamatovat kartu(y) pro platby u tohoto obchodníka, nezobrazí se mu základní formulář pro zadání karty, ale dostane na výběr ze zapamatovaných karet. Karty jsou seřazeny sestupně podle frekvence užívání u tohoto obchodníka. Karty, kterým vyprší platnost, se z brány automaticky nemažou, ale budou klientovi zobrazeny šedě s informací, že karta již není platná. Klient má možnost jakoukoli kartu (tj. i prošlou) nahradit nebo smazat (volby vlevo od karty). V případě náhrady si karta zachovává prioritu danou frekvencí používání.

Rozpoznání vydavatele a značky karty

Jakmile klient zadá prvních šest číslic z karty, brána zobrazí značku karty (např. MasterCard), a pokud je bráně znám vydavatel karty, pak i jeho logo. Zadá-li klient kartu obchodníkem neakceptovanou (např. když obchodník neakceptuje DinersClub), je klient v tomto kroku upozorněn.

Chyby před autorizací transakce

Brána upozorní klienta na jakoukoli detekovatelnou chybu ještě před odesláním transakce do autorizace. Typicky se jedná o překlepy v číslu karty. Brána nedovolí zadání historického data. CVC kód v tomto kroku bohužel validovatelný není, a udělá-li klient chybu, bude transakce odeslána ke zpracování (kde bude odmítnuta).

Druhý pokus

Odmítnutí platby z důvodu špatného CVC, blokované karty, nedostatku prostředků či bez udání důvodu vydavatelem karty nevede ke konci transakce a návratu do obchodu. Protože klient mohl opravdu jen udělat chybu v CVC nebo má v ruce další kartu, kterou může použít, brána mu nabídne "druhý pokus". V případě blokované karty nebo nedostatku prostředků brána konkrétně informuje o problému, který nastal (ostatní stavy nejsou z bezpečnostních důvodů konkrétněji indikovány). Obrázek níže ukazuje situaci po pokusu zaplatit blokovanou kartou.

Info o platbě mimo bezprostřední transakční kontext

Občas se stane, že klient otevře platební stránku znovu - z historie nebo na mobilu, když se mobilní prohlížeč automaticky refreshuje (bez vědomé akce klienta). Pokud transakce právě probíhá (tj. unitř časového rámce životnosti transakce na bráně), je zobrazen aktuální krok ve zpracování. Pokud však byla transakce již jakýmkoli způsobem na bráně zpracována (zaplaceno, odmítnuto nebo zrušeno klientem), pak je brána ještě běhěm několika následujících dní schopna zobrazit klientovi informaci o výsledku transakce. Obrázek ukazuje situaci po otevření již jednou úspěšně zaplacené platby.

❗Právě v těchto situacích brána používá kontaktní údaje podpory obchodníka. Věnujte proto prosím pozornost jejich přesnosti při předání bance.

Barvy obchodníka

Brána se pro vás umí přebarvit. Barvy se společně s logem definují v systému ČSOB POS Merchant a více informací o barvách, jejich umístění a kombinacích najdete ve wiki - Nastavení vlastního barevného schématu.

Všechny tyto stavy si můžete vyzkoušet na platební bráně naživo. Ihned a bez jakýchkoli závazků vůči bance. Pomocí testovacích karet v kombinaci s CVC kódem můžete z vašeho testovacího prostředí řídit výsledky transakcí na bráně (tj. např. platbu odmítnout, nechat projít apod.). V dokumentaci najdete návod, jak si vygenerovat testovací bezpečnostní klíče a jak volat testovací bránu.