Skip to content

eAPI 1.7

Jump to bottom
Ondřej Zaoral edited this page Jun 17, 2022 · 1 revision

Tato verze eAPI je stále podporována, doporučujeme ale používat nejnovější verzi

⚠️ Verzi eAPI 1.7 platební brána stále podporuje, nicméně doporučujeme používat nejnovější verzi 1.9. Přehled funkcí v jednotlivých verzích eAPI platební brány najdete v přehledové tabulce.

Platební brána ČSOB zpracovává transakce z e-shopů pomocí API, které má dvě klíčové funkce. Slouží k provedení platby klienta na vašem e-shopu (případně v mobilní aplikaci) a současně umožňuje i následně řídit životní cyklus platby, realizovat vratky v případě reklamace zboží apod. Komunikace mezi vaším e-shopem a platební bránou je zabezpečena pomocí elektronických podpisů všech požadavků i odpovědí.

Tato dokumentace popisuje způsob integrace platební brány do prostředí e-shopu jak pro platby klientů, tak jejich následnou správu. Součástí integrace je implementace API do prostředí vašeho e-shopu a zprovoznění zabezpečené komunikace, tedy vygenerování certifikátů a jejich výměna s bankou.

Funkční změny vůči eAPI v1.6

V eAPI v1.7 je nově dostupná platba MasterPass a platebními tlačítky ČSOB / Poštovní spořitelny přímo z e-shopu, bez přesměrování na bránu. Více informací o platbě peněženkami MasterPass a platebními tlačítky ČSOB / Poštovní spořitelny najdete v samostatných sekcích pro MasterPass a platební tlačítka. Volání platby MasterPass bez přesměrování na bránu vyžaduje implementaci nových API funkcí. Podobným způsobem jsou řešeny i nové API funkce pro platební tlačítko.

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

  • [27.1.2017] doplněn nový návratový kód 500, EET rejected, viz seznam
  • [4.4.2017] doplněn chybějící paymentStatus v návratových parametrech operace payment/button
  • [1.8.2017] doplněna podpora pro akceptaci nové měny HRK a nové lokalizace HR a SI
  • [12.9.2017] upraven popis integrace MasterPass.client.checkout pro mpass@shop
  • [30.11.2017] doplněn popis integrace MasterPass.client.checkout pro mpass@shop pro js callback
  • [24.9.2017] doplněna podpora pro akceptaci nové měny RON, NOK a SEK

Slovníček nejdůležitějších pojmů

3D Secure - standard asociací Visa a MasterCard vystupující pod komerčními názvy MasterCard SecureCode a Verified by Visa. Zajišťuje vyšší bezpečnost online plateb kartami.

3D Secure na straně vydavatele karty - ověření platby u vydavatele karty, které probíhá po přesměrování z platební brány na webové stránky vydavatele karty. Samotné ověření probíhá v prostředí České republiky nejčastěji formou zadání SMS kódu, zaslaného na kontaktní telefon držitele karty. Může nicméně probíhat i jinými způsoby. Ne všechny karty podporují 3D Secure na straně vydavatele. Nicméně rozdíly obchodníkovi plně řeší platební brána a zpracování platby je z pohledu obchodníka shodné.

3D Secure na straně platební brány - zabezpečení platby v podobě zadávání citlivých platebních údajů držitelem karty nikoli obchodníkovi, ale přímo do webové stránky banky obchodníka. Tímto způsobem zadávání údajů zabraňuje 3D Secure standard zneužití citlivých platebních údajů obchodníkem.

API - rozhraní mezi platební bránou a e-shopem, specifikované touto dokumentací

Banka - Československá obchodní banka, a.s., provozovatel služeb platební brány na https://platebnibrana.csob.cz

Banka obchodníka - viz banka

Banka plátce - viz vydavatel karty

Držitel karty - viz plátce

e-shop - elektronický obchod provozovaný prostřednictvím WWW stránek nebo mobilní aplikace

Karta - platební nástroj používaný plátcem, souhrnné označení pro kreditní, debetní, předplacené a charge karty

Košík - všechny položky nákupu, kde součet cen položek včetně aplikovatelné DPH odpovídá hodnotě transakce

MasterPass - peněženkové řešení asociace MasterCard umožňující platby kartou (resp. více kartami) zaregistrovanou do peněženky MasterPass, a to bez zadávání údajů o kartě

Obchodník - provozovatel e-shopu, příjemce plateb od plátců

Objednávka - objednávka a její interní označení v e-shopu skládající se z položek košíku. Objednávka vzniká potvrzením košíku ze strany plátce. Jednou z možností, jak může být objednávka plátcem uhrazena, je transakce na platební bráně. Objednávka je plně řízena e-shopem stejně jako přiřazení transakce k objednávce. Řízením objednávky na straně e-shopu se rozumí i změny stavu objednávky dle stavů transakce na platební bráně.

PCI DSS - Payment Card Industry Data Security Standard (více na www.pcistandard.cz)

Platba - viz transakce

Plátce - uživatel, který provedl nákup na e-shopu, uzavřel objednávku a chce ji zaplatit kartou

POS Merchant - systém banky pro správu transakcí personálem obchodníka

Stav transakce - jednoznačný status transakce v rámci jejího životního cyklu definovaný platební bránou a kdykoli zjistitelný pro obchodníka pomocí API

Transakce - při výběru zaplacení objednávky kartou vzniká přesměrováním plátce na platební bránu. Transakce je jednoznačně identifikována a řízena platební bránou v rámci definovaných stavů.

Transakce platební brány - viz transakce.

Vydavatel karty - banka nebo jiná finanční instituce, která vede účet držitele karty, zajištuje zúčtování transakcí a během transakce provádí ověření držitele karty v rámci 3D Secure na straně vydavatele

Zákazník e-shopu - viz plátce

Postup platebního procesu

Z pohledu plátce e-shopu se platba odehrává standardním způsobem, na který je 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, kterou banka zašle plátci na jeho mobilní telefon a plátce tento kód přepisuje 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, kdy se transakce přepne do stavu probíhající platby. Na pozadí probíhající platby se odehrává mnoho kroků od ověření parametrů přes zjištění, zda karta patří do 3D ověření, samotný průběh 3D ověření 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 jiného důvodu 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 opět 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 7 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) až do chvíle, 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á povolenu 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íží počet 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 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í, toto provedeno a peníze budou na cestě. Tento stav je sice koncový, nicméně pokud se obchodník rozhodne transakci zrušit (např. zákazník objednávku zruší nebo zboží vrátí v zákonné lhůtě), může nad touto transakcí vyvolat operaci 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 zpracování transakce 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ánu.

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 volat znovu operaci založení platby se stejným číslem objednávky -- vznikla by nová platba s duplicitním číslem objednávky.

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 dostane informaci, 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  

Jak bylo uvedeno výše, stav transakce může e-shop ověřit po jejím skončení. Transakce je držena v aktivní části brány následujících 48 hodin po jejím provedení. Pokud plátce, kupříkladu 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í o tom, jak tato platba dopadla.

Jak vyplývá z výše popsaného životního cyklu transakce, po úspěšném dokončení transakce 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 potřeba vrátit prostředky zpět plátci. Příkladem je např. 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 menší než původní autorizovaná částka.

Pomocné funkce rozhraní

Kontrola brány echo Metoda pouze profoukne bránu a ověří vzájemnou funkčnost a korektnost podpisů obou stran. V odpovědi vrací čas systému na bráně.

Kontrola zákazníka customer/info Pokud je plátce na e-shopu přihlášen a jeho identita je známá, může si při platbě na bráně uložit své karty pro příští návštěvu e-shopu. Tato metoda umožní obchodníkovi zjistit, zda je pro bránu tento plátce známý a má uloženou nějakou kartu. Žádné další detaily však z důvodu bezpečnosti brána neposkytuje. Funkci lze využít např. pro propagaci platby uloženou kartou.

Postup integrace; klíče a kde je vzít

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 potřeba vygenerovat tento pár privátní klíč + veřejný klíč, privátní část si 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 pracuje tak, ž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:

  1. Vyžádá od plátce jeho MerchantID a registrovanou eMailovou adresu.
  2. Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází.
  3. Nabídne pouze možnost generování testovacích klíčů.
  4. Lokálně vygeneruje testovací pár klíčů private key/public key.
  5. Privátní část private key uloží do souboru v počítači obchodníka.
  6. 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) fungují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ý bude pracovat následovně:

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

Platba na klik  

Platbou na klik rozumíme možnost automatizovaně provést platbu bez přesměrování držitele karty na platební bránu a bez zadávání platebních údajů, přičemž potřebné údaje jsou převzaty z dříve provedené autorizované platby. Tato funkce je určena pro pohodlnou platbu při následných nákupech klienta v e-shopu nebo v aplikaci. Klient musí být v e-shopu registrován, aby byl e-shop schopen předat při následujících transakcích potřebné údaje. Veškerá volání mezi e-shopem a bránou probíhají backendově, tj. z pohledu klienta se opravdu jedná o platbu "na jedno kliknutí".

Funkce Platby na klik není přístupná univerzálně, musí být ze strany ČSOB pro konkrétního obchodníka povolena.

Celý proces obsahuje nejprve zpracování klasické platby:

  • 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.

Platbu na klik provede obchodník následovně:

  • obchodník volá na eAPI nejprve operaci payment/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 payment/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 payment/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

Přečtěte si prosím také obecný článek, ve kterém se dočtete o pravidlech (banky a karetních asociací), které je nutné dodržet. Připravili jsme pro vás i několik doporučení, jak platbu na klik nejlépe implementovat.

Upozornění: vzhledem k charakteru platby na klik se vlastní zpracování následných plateb provádí bez interakce s plátcem / držitelem karty, tzn. probíhá bez zadávání CVC kódu a bez 3DS ověření.

Poznámka: platební brána rozlišuje mezi platbou dříve uloženou kartou a platbou na klik. Platba dříve uloženou kartou zjednodušuje plátci zadávání platebních údajů v rozhraní platební brány, přičemž je vyžadováno a zadávání CVC kódu a 3DS ověření, zatímco platba na klik umožňuje automatizovaný způsob provádění plateb pro obchodníka bez nutnosti interakce s držitelem karty.

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 na menší částku. Ať už z důvodu, že obchodník nemůže část zboží dodat, nebo že konečná cena nákupu vzniká až poté, co zákazník opustil e-shop. Nicméně obchodník tento okamžik umí předvídat - nezavře při inicializaci transakce automaticky pomocí "closePayment": true, je ale schopen uzavřít transakci později na jeden pokus.

Platba pomocí MasterPass  

Volání platby MasterPass bez přesměrování na bránu označujeme dále jako mpass@shop. Obchodník může použít pro integraci dva scénáře - basic a standard.

Pomocí scénáře basic lze realizovat jednoduchou platbu. Po kliknutí na platební tlačítko je zákazníkovi zobrazena MasterPass peněženka. Zákazník provede přihlášení a výběr karty.

Potřebné údaje pro autorizaci se po zavření MasterPass peněženky předají na platební bránu a spustí se vlastní autorizace. Pro autorizaci se použije částka nastavená obchodníkem při založení transakce v rámci volání payment/init.

img/cz/masterpass/mpass-shop-basic-cz.png

Pomocí scénáře standard lze realizovat z pohledu obchodníka o něco málo složitější průběh transakce, a to předání údajů klienta, dopočítání finální ceny a následnou platbu.
Po kliknutí na platební tlačítko je zákazníkovi zobrazena nejprve MasterPass peněženka. Zákazník provede přihlášení a kromě karty vybírá doručovací adresu, případně věrnostní program pro uplatnění slevy u obchodníka.

Potřebné údaje pro autorizaci, adresa a údaje o věrnostním programu se po zavření MasterPass peněženky předají na platební bránu, obchodník dostává maskované číslo karty a expiraci, vybranou doručovací adresu a věrnostní program. Na základě těchto údajů přepočítá finální cenu objednávky a zobrazí v e-shopu tuto informaci zákazníkovi. Po odsouhlasení zákazníkem předá obchodník platební bráně finální cenu a dává pokyn ke spuštění autorizace.

img/cz/masterpass/mpass-shop-standard-cz.png

Obecnější informace o MasterPass platbě jsou popsány v samostatném článku.

Pro obsloužení scénářů basic a standard pro mpass@shop jsou doplněny do eAPI v1.7 následující operace:

Operace Popis
/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 javascript volání do e-shopu

jednotlivé kroky potřebné pro integraci MasterPass platby do e-shopu:

Vložení odkazu na externí MasterPass.client.js

Pro zprovoznění mpass@shop je nutné nejprve na stránku e-shopu, která bude obsahovat platební tlačítko, vložit odkaz na javascript hostovaný na serverech MasterPass. Skript vložte do hlavičky html stránky (element <header>).

<script type="text/javascript" src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>

Výše uvedený odkaz je určen pro produkční prostředí, pro testy na integračním prostředí použijte následující kód:

<script type="text/javascript" src="https://impass.iplatebnibrana.csob.cz/MasterPass.client.js"></script>

Vložení js funkce pro obsloužení MasterPass tlačítka

Dále je potřeba vložit do hlavičky html stránky javascript funkci obsluhující událost kliknutí na MasterPass tlačítko. V této funkci se pomocí AJAX volání na server e-shopu (v příkladu /my-eshop/mpass-checkout-handler) získají parametry pro vlastní obsloužení MasterPass tlačítka pomocí funkce MasterPass.client.checkout. Po návratu z MasterPass se volá buď callbackUrl (v případě, že je wallet otevřený ve fullscreen módu), nebo je řízení předáno pomocí volání callback funkce (podle výsledku zpracování se volá successCallback, cancelCallback nebo failureCallback, v příkladu níže obsluha navázána na jednotný mpassCallback, který pomocí AJAX volání na server e-shopu (v příkladu /my-eshop/mpass-finish-handler) předá parametry pro dokončení .

<script>
function handleBuyWithMasterPass() {
    console.log("handleBuyWithMasterPass started ...");
    Ajax.get("/my-eshop/mpass-checkout-handler").then(function (data) {

	var mpassCallback = function(response) {
	     console.log(response);
	     // merchant's implementation of AJAX call to /my-eshop/mpass-finish-handler
             // and processing result
	};

        MasterPass.client.checkout({
             "requestToken": data.requestToken,
             "callbackUrl": data.callbackUrl,
             "failureCallback": mpassCallback,
             "cancelCallback": mpassCallback,
             "successCallback": mpassCallback,
             "merchantCheckoutId":data.merchantCheckoutId,
             "allowedCardTypes":data.allowedCardTypes,
             "suppressShippingAddressEnable": data.suppressShippingAddressEnable,
             "loyaltyEnabled" : data.loyaltyEnabled,
             "version":data.version,
             "shippingLocationProfile":data.shippingLocationProfile
        });
    });
}
</script>

Vložení MasterPass tlačítka

Dále je potřeba vložit do příslušné části html stránky vlastní MasterPass tlačítko. Níže uvedený příklad odkazuje na verzi tlačítka o rozměrech 147 x 34 px. Podrobnější popis je uveden na samostatné stránce.

<a href="#" onClick="handleBuyWithMasterPass()">
  <img src="https://www.mastercard.com/mc_us/wallet/img/en/CZ/mcpp_wllt_btn_chk_147x034px.gif" alt="Buy with MasterPass">
</a>

Endpoint pro AJAX volání pro inicializaci MasterPass transakce

Jako další krok je potřeba v e-shopu implementovat obsloužení AJAX volání, ve výše uvedeném příkladu je to endpoint pro GET /my-eshop/mpass-checkout-handler.

Handler podle zvoleného scénáře zavolá operaci masterpass/basic/checkout anebo masterpass/standard/checkout, je odpovědný za seskládání potřebných parametrů, podpis požadavku a poslání požadavku na platební bránu, následné přijetí odpovědi, ověření podpisu a vrácení návratových parametrů ve formátu JSON.

Endpoint pro callbackUrl

Jako další krok je potřeba v e-shopu implementovat non-js obsloužení návratu z MasterPass peněženky, jedná se o GET endpoint definovaný pomocí parametru callbackUrl, který obchodník nastavuje v rámci masterpass/*/checkout operace. Obchodník na tomto endpointu přijme GET parametry mpstatus a nepovinné oauth_token, checkout_resource_url a oauth_verifier a předá je platební bráně podle zvoleného scénáře pomocí masterpass/basic/finish anebo masterpass/standard/extract.

Výsledkem je e-shopem vygenerovaná html stránka s aktuálním stavem objednávky, přičemž obchodník pomocí následných AJAX volání na server e-shopu pokračuje ve zjišťování stavu (v případě basic provolá payment/status na platební bráně a zjišťuje stav autorizace požadavku, v případě standard dopočítá finální cenu objednávky), po potvrzení zákazníkem volá na platební bráně masterpass/standard/finish a následně volá payment/status pro zjištění stavu autorizace.

Endpoint pro AJAX volání pro dokončení MasterPass transakce

Poslední krok spočívá v implementaci obsloužení AJAX volání pro dokončení MasterPass transakce. Ve výše uvedeném příkladu je to endpoint pro /my-eshop/mpass-finish-handler. Vstupem jsou JSON data obsahující parametry mpstatus a nepovinné oauth_token, checkout_resource_url a oauth_verifier.

Podobně jako u obsluhy endpointu pro callbackURL i zde obchodník předá přijaté vstupní parametry platební bráně podle zvoleného scénáře pomocí masterpass/basic/finish anebo masterpass/standard/extract.

Další proces je podobný - obchodník pomocí následných AJAX volání na server e-shopu pokračuje ve zjišťování stavu (v případě basic volá na platební bráně payment/status a zjišťuje stav autorizace požadavku, v případě standard dopočítá finální cenu objednávky, po potvrzení zákazníkem volá masterpass/standard/finish a následně volá na platební bráně payment/status).

Platba pomocí platebního tlačítka ČSOB / Poštovní spořitelny  

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. Obecnější informace o platbě platebním tlačítkem jsou popsány [v samostatném článku](Platební tlačítko ČSOB a Poštovní spořitelny).

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.

img/cz/paymentbutton/pt-shop-cz.png

Pro mobilní zařízení je výše popsané chování trochu 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, nebo zda se má otevřít Smartbanking mobilní aplikace dané banky.

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

Operace Popis
/payment/button 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](Loga platebních metod, karetních asociací a 3D Secure).

<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 payment/button - 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.

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ílaná 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 byl 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 ověřen podpis požadavku. V případě chyby při této základní kontrole obsahuje odpověď z hlediska bezpečnosti pouze obecný HTTP status kód (např. 400 Bad Request nebo 403 Forbidden).

Popis parametrů jednotlivých metod

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

POST https://api.platebnibrana.csob.cz/api/v1.7/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.
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ů. Níže je uveden obsah předávaných parametrů v přesměrování.
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.
description String Stručný popis nákupu pro 3DS stránku: V případě ověření klienta na straně vydavatelské banky nelze zobrazit detail košíku jako na platební bráně. Do banky se proto posílá tento stručný popis nákupu. Maximální délka 255 znaků.
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. Stejnou jazykovou sadu lze použít i v eAPI v1, v1.5 a V1.6.
ttlSec Number Nastavení životnosti transakce v sekundách, min. povolená hodnota 300, max. povolená hodnota 1800 (5-30 min).
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.
signature String Podpis požadavku, kódováno v BASE64.

Upozornění: pokud je payOperation nastavena na oneclickPayment, 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.

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 položky a nepovinný pomocný popis.

Položka Typ Popis
name String Název zboží, maximální délka je 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"), 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 volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20140425131559",
  "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)",
  "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) anebo ve stavu Čekání na zúčtování (7) anebo ve stavu Zúčtováno (8).
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":"20140425131559",
  "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":"20140425131559",
  "resultCode": 100,
  "resultMessage":"Missing parameter 'totalAmount'",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

GET https://api.platebnibrana.csob.cz/api/v1.7/payment/process  

Požadavek obsahuje položky přímo v URL adrese https://api.platebnibrana.csob.cz/api/v1.7/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

Příklad volání:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.7/payment/process/012345/d165e3c4b624fBD/20140425131559/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: eShop 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 -- ale vždy provede 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=20140425131559&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=20140425131559&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“.

GET https://api.platebnibrana.csob.cz/api/v1.7/payment/status  

Požadavek obsahuje položky přímo v URL adrese https://api.platebnibrana.csob.cz/api/v1.7/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.7/payment/status/012345/d165e3c4b624fBD/20140425131559/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":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 4,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

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

Operace reversuje (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 volání:

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.7/payment/reverse \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "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":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 5,
  "signature":"base64-encoded-response-signature"
 }

PUThttps://api.platebnibrana.csob.cz/api/v1.7/payment/close  

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

Update 14.11.2015: V operaci payment/close byl přidán nový nepovinný parametr totalAmount (uzavření transakce a zaúčtování na menší částku)

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 volání:

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

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

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.7/payment/close \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "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":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

PUThttps://api.platebnibrana.csob.cz/api/v1.7/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. Nově 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 volání:

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.7/payment/refund \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "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":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 8,
  "signature":"base64-encoded-response-signature"
 }

GET/POST https://api.platebnibrana.csob.cz/api/v1.7/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.7/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.7/echo \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

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

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.7/echo/012345/20140425131559/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
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":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "signature":"base64-encoded-response-signature"
 }

GEThttps://api.platebnibrana.csob.cz/api/v1.7/customer/info  

Operace pro zjištění informace o uloženém zákazníkovi. Požadavek obsahuje položky přímo v URL adrese : https://api.platebnibrana.csob.cz/api/v1.7/customer/info/{merchantId}/{customerId}/{dttm}/{signature}

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 volání:

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

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

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
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":"20140425131559",
  "resultCode": 800,
  "resultMessage":"Customer not found",
  "signature":"base64-encoded-response-signature",
 }

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

Operace provede platbu na klik. Podmínkou je, že existuje autorizovaná platba (tzv. "šablona 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 10 číslic.
dttm String Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS.
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 parametr currency vyplněn, musí být vyplněn také parametr totalAmount.
description String Stručný popis nákupu. Maximální délka 255 znaků. Pokud není vyplněno, přebírá se hodnota ze šablony pro platbu.
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í) a dále parametr merchantData.

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/payment/oneclick/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "origPayId":"ef08b6e9f2234BC",
  "orderNo":"5547123",
  "dttm":"20140425131559",
  "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/oneclick/init -- úspěšně založená transakce:

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

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

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

POST https://api.platebnibrana.csob.cz/api/v1.7/payment/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 v předchozím kroku pomocí operace payment/oneclick/init vytvořené platby na klik
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í) a dále parametr merchantData.

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/payment/oneclick/start \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "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/oneclick/start

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "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í payment/oneclick/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 v nejhorším možném případě může být až 60 vteřin).

Příklad návratových hodnot pro payment/oneclick/start -- neautorizovaná transakce (expirovaná karta):

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"Card for payment/oneclick expired",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

POSThttps://api.platebnibrana.csob.cz/api/v1.7/masterpass/basic/checkout  

Voláním operace je provedena inicializace masterpass session (získání request tokenu a inicializace masterpass košíku). Výsledkem jsou parametry pro javascriptové volání pro otevření lighboxu v e-shopu obchodníka.

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
callbackUrl String Callback URL, kterou masterpass wallet použije pro předání parametrů po zavření masterpass wallet, musí obsahovat platnou adresu e-shopu obchodníka včetně protokolu http:// nebo https://.
signature String Podpis požadavku, kódováno v BASE64

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/basic/checkout \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "callbackUrl":"https://www.vasobchod.cz/masterpass/callback",
  "dttm":"20140425131559",
  "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.
lightboxParams Object Potřebné parametry pro volání lightboxu pro následné zobrazení MasterPass wallet v e-shopu obchodníka, vyplněno v případě, že resultCode je 0.
signature String Podpis odpovědi, kódováno v BASE64.

Popis parametrů objektu lightboxParams, datový typ všech parametrů je záměrně String (obchodník dané hodnoty pouze vezme a v nezměněné podobě je vyplní do js volání MasterPass.client.checkout, viz dále)

Položka Typ Popis
requestToken String Session ID pro MasterPass wallet.
callbackUrl String Callback URL obchodníka předaná v parametrech požadavku.
merchantCheckoutId String Identifikace obchodníka, registrovaného v MasterPass.
allowedCardTypes String Povolené typy karet, které se zákazníkovi zobrazí v MasterPass wallet, vyplněno platební bránou v souladu s nastavením obchodníka.
suppressShippingAddressEnable String Povolení/zakázání výběru adresy v MasterPass wallet. Pro scénář basic (pouze platba) bude vždy vyplněno na hodnotu true (= výběr adresy je zakázán).
loyaltyEnabled String Povolení/zakázání výběru věrnostního programu. wallet. Pro scénář basic (pouze platba) bude vždy vyplněno na hodnotu false (= výběr věrnostního programu je zakázán).
version String Verze použitého MasterPass wallet.
shippingLocationProfile String Nastavení restrikce při výběru dodací adresy.

Příklad návratových hodnot pro masterpass/basic/checkout -- úspěšně provedená inicializace MasterPass wallet:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "lightboxParams": {
    "requestToken": "6a79bf9e320a0460d08aee7ad154f7dab4e19503",
    "callbackUrl": "https://www.vasobchod.cz/masterpass/callback",
    "merchantCheckoutId": "a4a6w4vzajswviqy5oeu11irc2e3yb51ws",
    "allowedCardTypes": "master,visa",
    "suppressShippingAddressEnable": "true",
    "loyaltyEnabled": "false",
    "version": "v6",
    "shippingLocationProfile": "SP-0001"
  },
  "signature":"base64-encoded-response-signature"
 }

Ukázka volání MasterPass.client.checkout

Parametry získané ve volání masterpass/basic/checkout vyplní obchodník do javascriptového volání.

MasterPass.client.checkout({
  "requestToken":"6a79bf9e320a0460d08aee7ad154f7dab4e19503",
  "callbackUrl":"https://www.vasobchod.cz/masterpass/callback",
  "failureCallback": mpassCallback,
  "cancelCallback": mpassCallback,
  "successCallback": mpassCallback,
  "merchantCheckoutId":"a4a6w4vzajswviqy5oeu11irc2e3yb51ws",
  "allowedCardTypes":"master,visa",
  "suppressShippingAddressEnable": "true",
  "loyaltyEnabled" : "false",
  "version":"v6",
  "shippingLocationProfile":"SP-0001"
});

POSThttps://api.platebnibrana.csob.cz/api/v1.7/masterpass/basic/finish  

Voláním operace předává obchodník callback parametry z MasterPass na platební bránu. Po kontrole a validaci parametrů je provedeno na platební bráně následné vytažení parametrů potřebných pro autorizaci a její spuštění. Získání výsledku autorizace provádí obchodník již standardně pomocí existující operace payment/status.

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
callbackParams Object Struktura obsahující parametry předané z MasterPass wallet zpět obchodníkovi přes callbackUrl, detailnější popis viz dále
signature String Podpis požadavku, kódováno v BASE64

Popis položek objektu callbackParams

Položka Typ Popis
mpstatus String Status checkoutu v MasterPass wallet, hodnota získaná z parametru mpstatus předaného z MasterPass obchodníkovi přes callbackUrl.
oauthToken String Verifikační token, hodnota získaná z parametru oauth_token předaného z MasterPass obchodníkovi přes callbackUrl.
checkoutResourceUrl String URL pro získání dat z MasterPass wallet, vyplněno v případě, že zákazník úspěšně dokončí výběr karty v MasterPass wallet, hodnota získaná z parametru checkout_resource_url předaného z MasterPass obchodníkovi přes callbackUrl.
oauthVerifier String Verifikační řetězec, který platební brána použije pro získání dat z MasterPass wallet, vyplněno v případě, že zákazník úspěšně dokončí výběr karty v MasterPass wallet, hodnota získaná z parametru oauth_verifier předaného z MasterPass obchodníkovi přes callbackUrl.

Příklad volání: (zákazník dokončil výběr karty v MasterPass wallet)

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/basic/finish \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "callbackParams": {
    "mpstatus":"success",
    "oauthToken": "6a79bf9e320a0460d08aee7ad154f7dab4e19503",
    "checkoutResourceUrl":"https://sandbox.api.mastercard.com/masterpass/v6/checkout/616764812",
    "oauthVerifier":"fc8f41bb76ed7d43ea6d714cb8fdefa606611a7d"
  },
  "signature":"base64-encoded-request-signature"
}'

Příklad volání: (zákazník nedokončil výběr, zavřel MasterPass wallet)

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/basic/finish \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "callbackParams": {
    "mpstatus":"cancel"
  },
  "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 masterpass/basic/finish -- autorizace spuštěna, platba probíhá

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

POSThttps://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/checkout  

Voláním operace je provedena inicializace masterpass session (získání request tokenu a inicializace masterpass košíku). Výsledkem jsou parametry pro javascriptové volání pro otevření lighboxu v e-shopu obchodníka.

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.
callbackUrl String Callback URL, kterou masterpass wallet použije pro předání parametrů po zavření masterpass wallet, musí obsahovat platnou adresu e-shopu obchodníka včetně protokolu http:// nebo https://.
shippingLocationProfile String Volitelné nastavení restrikce při výběru dodací adresy. V případě, že parametr nebude vyplněn, nastavuje platební brána pro volání MasterPass.client.checkout defaultní hodnotu SP-0001.
signature String Podpis požadavku, kódováno v BASE64.

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/checkout \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "callbackUrl":"https://www.vasobchod.cz/masterpass/callback",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Příklad volání včetně nastavení shippingLocationProfile:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/checkout \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "callbackUrl":"https://www.vasobchod.cz/masterpass/callback",
  "shippingLocationProfile":"CSOBCZ001",
  "dttm":"20140425131559",
  "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.
lightboxParams Object Potřebné parametry pro volání lightboxu pro následné zobrazení MasterPass wallet v e-shopu obchodníka, vyplněno v případě, že resultCode je 0.
signature String Podpis odpovědi, kódováno v BASE64.

Popis parametrů objektu lightboxParams, datový typ všech parametrů je záměrně String (obchodník pouze dané hodnoty vezme a v nezměněné podobě je vyplní do js volání MasterPass.client.checkout, viz dále)

Položka Typ Popis
requestToken String Session ID pro MasterPass wallet.
callbackUrl String Callback URL obchodníka předaná v parametrech požadavku.
merchantCheckoutId String Identifikace obchodníka registrovaného v MasterPass.
allowedCardTypes String Povolené typy karet, které se zákazníkovi zobrazí v MasterPass wallet, vyplněno platební bránou v souladu s nastavením obchodníka.
suppressShippingAddressEnable String Povolení/zakázání výběru adresy v MasterPass wallet. Pro scénář standard bude vždy vyplněno na hodnotu false (= výběr adresy je povolen).
loyaltyEnabled String Povolení/zakázání výběru věrnostního programu. wallet. Pro scénář standard bude vždy vyplněno na hodnotu true (= výběr věrnostního programu je povolen).
version String Verze použitého MasterPass wallet.
shippingLocationProfile String Nastavení restrikce při výběru dodací adresy.

Příklad návratových hodnot pro masterpass/standard/checkout -- úspěšně provedená inicializace MasterPass wallet:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "lightboxParams": {
    "requestToken": "6a79bf9e320a0460d08aee7ad154f7dab4e19503",
    "callbackUrl": "https://www.vasobchod.cz/masterpass/callback",
    "merchantCheckoutId": "a4a6w4vzajswviqy5oeu11irc2e3yb51ws",
    "allowedCardTypes": "master,visa",
    "suppressShippingAddressEnable": "false",
    "loyaltyEnabled": "true",
    "version": "v6",
    "shippingLocationProfile": "CSOBCZ001"
  },
  "signature":"base64-encoded-response-signature"
 }

Ukázka volání MasterPass.client.checkout

Parametry získané ve volání masterpass/standard/checkout vyplní obchodník do javascriptového volání

MasterPass.client.checkout({
  "requestToken":"6a79bf9e320a0460d08aee7ad154f7dab4e19503",
  "callbackUrl":"https://www.vasobchod.cz/masterpass/callback",
  "failureCallback": mpassCallback,
  "cancelCallback": mpassCallback,
  "successCallback": mpassCallback,
  "merchantCheckoutId":"a4a6w4vzajswviqy5oeu11irc2e3yb51ws",
  "allowedCardTypes":"master,visa",
  "suppressShippingAddressEnable": "false",
  "loyaltyEnabled" : "true",
  "version":"v6",
  "shippingLocationProfile":"CSOBCZ001"
});

POSThttps://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/extract  

Voláním operace předává obchodník callback parametry z MasterPass na platební bránu. Po kontrole a validaci parametrů je provedeno následné vytažení parametrů (karta, adresa, loyalty program) potřebných pro vypočtení finální ceny v e-shopu obchodníka a následné dokončení nákupu (spuštění autorizace na platební bráně). Citlivé údaje jako číslo karty jsou po vytažení z MasterPass uchovávány pouze na platební bráně, nejsou předávány obchodníkovi.

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
callbackParams Object Struktura obsahující parametry předané z MasterPass wallet zpět obchodníkovi přes callbackUrl, detailnější popis viz dále
signature String Podpis požadavku, kódováno v BASE64

Popis položek objektu callbackParams

Položka Typ Popis
mpstatus String Status checkoutu v MasterPass wallet, hodnota získaná z parametru mpstatus předaného z MasterPass obchodníkovi přes callbackUrl.
oauthToken String Verifikační token, hodnota získaná z parametru oauth_token předaného z MasterPass obchodníkovi přes callbackUrl.
checkoutResourceUrl String URL pro získání dat z MasterPass wallet, vyplněno v případě, že zákazník úspěšně dokončí výběr karty v MasterPass wallet, hodnota získaná z parametru checkout_resource_url předaného z MasterPass obchodníkovi přes callbackUrl .
oauthVerifier String Verifikační řetězec, který platební brána použije pro získání dat z MasterPass wallet, vyplněno v případě, že zákazník úspěšně dokončí výběr karty v MasterPass wallet, hodnota získaná z parametru oauth_verifier předaného z MasterPass obchodníkovi přes callbackUrl .

Příklad volání: (zákazník dokončil výběr karty a adresy v MasterPass wallet)

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/extract \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "callbackParams": {
    "mpstatus":"success",
    "oauthToken": "6a79bf9e320a0460d08aee7ad154f7dab4e19503",
    "checkoutResourceUrl":"https://sandbox.api.mastercard.com/masterpass/v6/checkout/616764812",
    "oauthVerifier":"fc8f41bb76ed7d43ea6d714cb8fdefa606611a7d"
  },
  "signature":"base64-encoded-request-signature"
}'

Příklad volání: (zákazník nedokončil výběr, zavřel MasterPass wallet)

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/extract \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "callbackParams": {
    "mpstatus":"cancel"
  },
  "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.
checkoutParams Object Parametry vyčtené z MasterPass wallet po úspěšném výběru karty, doručovací adresy a věrnostního programu, struktura je vyplněna v případě, že resultCode je 0.
signature String Podpis odpovědi, kódováno v BASE64.

Struktura objektu checkoutParams

Položka Typ Popis
card Object zákazníkem vybraná bankovní karta
shippingAddress Object zákazníkem vybraná doručovací adresa
contact Object informace o zákazníkovi
rewardProgram Object zákazníkem vybraný věrnostní program

Struktura objektu card

Položka Typ Popis
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.
billingAddress Object Zákazníkem vybraná fakturační adresa.

Struktura objektu billingAddress obsahující údaje o fakturační adrese zákazníka

Položka Typ Popis
city String fakturační adresa - město
country String fakturační adresa - země
countrySubdivision String fakturační adresa - region
line1 String fakturační adresa - první řádek adresy - obsahuje zpravidla ulici a číslo
line2 String fakturační adresa - druhý řádek adresy
line3 String fakturační adresa - třetí řádek adresy
postalCode String fakturační adresa - poštovní směrovací kód

Struktura objektu shippingAddress obsahující údaje o doručovací adrese zákazníka spolu s kontaktními údaji

Položka Typ Popis
recipientName String jméno a příjmení zákazníka
recipientPhoneNumber String telefonní číslo zákazníka
city String doručovací adresa - město
country String doručovací adresa - země
countrySubdivision String doručovací adresa - region
line1 String doručovací adresa - první řádek adresy - obsahuje zpravidla ulici a číslo
line2 String doručovací adresa - druhý řádek adresy
line3 String doručovací adresa - třetí řádek adresy
postalCode String doručovací adresa - poštovní směrovací kód

Struktura objektu contact

Položka Typ Popis
firstName String křestní jméno
middleName String prostřední jméno
lastName String příjmení
country String stát
emailAddress String e-mail
phoneNumber String tel. číslo

Struktura objektu rewardProgram

Položka Typ Popis
rewardNumber String číslo věrnostní karty
rewardId String identifikátor věrnostní karty
rewardName String název věrnostního programu
expiration String expirace věrnostní karty ve formátu MM/YY

Příklad návratových hodnot pro masterpass/standard/extract

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "checkoutParams": {
    "card": {
      "maskedCln":"****4145",
      "expiration":"11/19",
      "billingAddress": {
        "city":"Praha 1",
        "country":"CZ",
        "line1":"Jindřišská 16",
        "postalCode":"11150"
      }
    },
    "shippingAddress": {
      "recipientName":"Jan Novák",
      "recipientPhoneNumber":"+420602123456",
      "city":"Praha 1",
      "country":"CZ",
      "line1":"Dlouhá 23",
      "postalCode":"11150"
    }
  },
  "signature":"base64-encoded-response-signature"
 }

POSThttps://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/finish  

Voláním operace předává obchodník platební bráně finální cenu pro autorizaci požadavku, platební brána spouští autorizaci. Získání výsledku autorizace provádí obchodník již standardně pomocí existující operace payment/status.

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
oauthToken String Verifikační token, hodnota získaná z parametru oauth_token předaného z MasterPass obchodníkovi přes callbackUrl, potřebné pro správné spárování jednotlivých MasterPass volání na straně platební brány
totalAmount Number Celková cena v setinách základní měny. Finální částka transakce vypočtená obchodníkem na základě parametrů získaných po checkoutu v MasterPass wallet (dodací adresa pro úpravu poštovného, věrnostní program pro aplikování slevy)
signature String Podpis požadavku, kódováno v BASE64

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.7/masterpass/standard/finish \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "oauthToken":"6a79bf9e320a0460d08aee7ad154f7dab4e19503",
  "totalAmount":10500,
  "signature":"base64-encoded-request-signature"
}'

📝 platební brána neumožňuje změnit currency, ta zůstává stejná z payment/init

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 masterpass/standard/finish -- autorizace spuštěna, platba probíhá

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

POST https://api.platebnibrana.csob.cz/api/v1.7/payment/button  

Přípraví parametry pro platbu platebním tlačítkem pro přesměrování uživatele z e-shopu na elektronické bankovnictví.

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)
brand String Platební tlačítko zvolené zákazníkem, povolené hodnoty csob, era
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 POST https://api.platebnibrana.csob.cz/api/v1.7/payment/button \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "brand":"csob",
  "dttm":"20140425131559",
  "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 tomtéž 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

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-1. Například v Javě je potřeba použít při inicializaci třídy java.security.Signature algoritmus "SHA1withRSA", v PHP je potřeba použít "OPENSSL_ALGO_SHA1", 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.7/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.7/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.7/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 získat z informačního portálu platební brány.

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).

Čí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)
180 Operation not allowed (nepovolená operace)
220 mpass@shop disabled (obchodník nemá povolenou přímou integraci MasterPass do e-shopu)
230 Merchant not onboarded for MasterPass (obchodník není registrovaný v MasterPass)
240 MasterPass request token already initialized
250 MasterPass request token does not exist
260 MasterPass server error (MasterPass platbu nelze dokončit, chyba serveru)
270 MasterPass canceled by user (zákazník nedokončil výběr karty/adresy v MasterPass wallet)
400 pt@shop (CSOB IB) disabled (obchodník nemá povolenou platební metodu pt@shop pro ČSOB)
410 pt@shop (ERA IB) disabled (obchodník nemá povolenou platební metodu pt@shop pro Poštovní spořitelnu)
420 pt@shop (CSOB IB) unavailable (platební metoda pt@shop není pro ČSOB dostupná)
430 pt@shop (ERA IB) unavailable (platební metoda pt@shop není pro Poštovní spořitelnu dostupná)
500 EET Rejected (EET hlášení bylo odmítnuto FS)
800 Customer not found (zákazník identifikovaný pomocí customerId nenalezen)
810 Customer found, no saved card(s)
820 Customer found, found saved card(s)
900 Internal error (interní chyba ve zpracování požadavku)

💳 Platební brána

  1. Průběh platby
  2. API integrace a zabezpečení
  3. Návod na přechod do produkčního prostředí
  4. Testovací karty
  5. API Sunset

💰 Platby

  1. Ověření karetních plateb
  2. Platba na bráně
  3. OneClick platba
  4. Platba na míru
  5. Apple Pay
  6. Google Pay
  7. Zaúčtování platby kartou na menší částku
  8. Platební tlačítko ČSOB
  9. Platba Skip Pay

🔬 eAPI 1.9

  1. Volání rozhraní eAPI
  2. Podpis požadavku a ověření podpisu odpovědi
  3. Přehled eAPI metod
  4. Základní metody
  5. Metody pro OneClick platbu
  6. Metody pro Apple Pay
  7. Metody pro Google Pay
  8. Metody pro platební tlačítko
  9. Metody pro platbu Skip Pay
  10. Dodatečná data o nákupu

📐 Návody a podklady

  1. Loga a prezentace platebních metod
  2. Logo obchodníka
  3. Barevné schéma

📟 API rozšíření

  1. Koncept API rozšíření
  2. Detailní datum a čas zpracování a vypořádání transakce
  3. Data o kartě pro OneClick platbu
  4. Data o kartě pro platbu na bráně
  5. Tokenizace
  6. Ověřovací kód na výpis

🔧 Časté dotazy (FAQ)

  1. Funkční a komerční dotazy
  2. Technické dotazy

📡 Archiv starších verzí eAPI

  1. eAPI 1.8
  2. eAPI 1.7
  3. eAPI 1.6
  4. eAPI 1.5
  5. eAPI 1.0
Clone this wiki locally