eAPI 1.0
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.
3D Secure - standard asociací Visa a MasterCard, vystupující pod komerčními názvy MasterCard SecureCode a Verified by Visa. Zajištuje vyšší bezpečnost online plateb kartami.
3D Secure na straně vydavatele karty - ověření platby u vydavatele karty, 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 - rozdíly nicméně 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
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 transakcí na platební bráně. Objednávka je plně řízena e-shopem, stejně jako přiřazení transakce 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 v každý okamžik 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
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.
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 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í, jeho samotný průběh u vydavatelské banky a následné provedení platby kartou. Tyto kroky jsou pro obchodníka skryty za průběhem platby, zajímá ho až samotná výsledek. Ten může být:
- 3) Platba zrušena - platba byla zrušena plátcem na platební bráně
- 6) Platba zamítnuta - zamítnuto bankou z důvodu nedostatku prostředků, nepotvrzení 3D ověření plátcem či jiného důvodu a nebo byl proces přerušen, např. protože plátce zavřel prohlížeč
- 4) Platba potvrzena - platba byla provedena a čeká až ji obchodník zařadí do zúčtování. Do tohoto stavu se úspěšná platba dostane, pokud je automatické zařazení do zúčtování vypnuto.
- 7) Čekání na zúčtování - platba byla provedena a automaticky zařazena do zúčtování
3) Platba zrušena Tento stav nastane, pokud plátce na stránce platební brány klikne na tlačítko zrušit. Plátce se vrací automaticky do e-shopu (platební brána jej přesměruje) a z pohledu životního cyklu transakce je tento stav koncový. Chce-li plátce znovu tu samou objednávku v e-shopu zaplatit 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 sedmi dní, kdy je platba ze strany banky garantována a na kartě plátce jsou prostředky blokovány. POZOR! Po uplynutí této doby již není možné transakci zařadit do zúčtování! (platba je odvolána, prostředky na kartě plátce jsou systémem automaticky odblokovány a banka platbu již negarantuje).
5) Platba odvolána Dokud neprojde potvrzená platba zúčtováním, lze ji odvolat. To znamená, že nebude vůbec držiteli karty účtována, blokované prostředky na kartě se uvolní a neplatí se žádný poplatek. Tento stav je koncový a nelze jej vrátit. Počet odvolaných plateb obchodníkem je bankou monitorován.
Spoléhat na možnost odvolání platby lze pouze u transakcí, které dosud nebyly zúčtovány. Odvolat platbu lze u transakcí ve stavu „Platba potvrzena“ (4) do té doby dokud nebude zařazena do zúčtování a neproběhne samotné zúčtování. U transakcí ve stavu „Čekání na zúčtování“ (7) lze odvolat platbu maximálně do půlnoci daného dne, po této době se provádí zúčtování transakcí, u zúčtovanou 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. Principielně 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íží skupina plátců, které neúspěch a návrat do e-shopu odradí. Z pohledu obchodníka je takováto "transakce napodruhé" po celou dobu ve stavu Platba probíhá a až výsledný úspěch či neúspěch ji přesune do příslušného stavu.
7) Čekání na zúčtování je stav, kdy jsou transakce již řazeny do fronty a dle nastavení zúčtovacích pravidel banky 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 na nad touto transakcí vyvolat operací vrácení prostředků.
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. Stav je koncový.
Založení platby payment/init V okamžiku, kdy je na e-shopu iniciována koncová fáze nákupu, přechází se k platbě a je vybrána metoda platby kartou, e-shop zakládá platbu na platební bráně. Kromě standardních údajů, jako je vlastní identifikace obchodníka, částka a referenční číslo objednávky, může e-shop zaslat do platební brány také detail nákupu včetně položek košíku. Tím se výrazně zpřehlední platební proces a zvýší důvěra zákazníka v korektní průběh operací na e-shopu a platební bráně.
Referenční číslo objednávky přiděluje e-shop obchodníka. Ve výsledku se referenční číslo objednávky objeví na výpisu transakcí z banky. Použije se tedy v systému obchodníka (účetnictví) pro párování plateb e-shopu proti bankovnímu účtu a musí tedy splňovat podmínku variabilního symbolu - numerickou hodnotu o maximálně deseti místech. V aplikaci POSMerchant je referenční číslo objednávky zobrazeno ve sloupci Variabilní symbol.
Po založení platby přiřadí platební brána každé transakci jednoznačné ID platby payId. Tento identifikátor se vrací v odpovědi na payment/init a nese se s 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ýpise 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 opakovaně 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 odkaze 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í
payIdnelze 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 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.
Jak jsme si výše řekli, 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, třeba omylem, vyvolá z historie prohlížeče opět platební bránu, nedojde k žádným komplikacím. bude mu zobrazena korektní potvrzovací stránka platební brány s informací, jak tato platba dopadla.
Jak vyplývá z výše popsaného životního cyklu transakce, po jejím úspěšném dokončení je ještě několik kroků, kterými může obchodník řídit její stav:
Odvolání transakce payment/reverse Metoda odvolá úspěšně autorizovanou transakci a vyřadí ji ze systému, transakce nebude provedena a prostředky na kartě plátce se uvolní. Metodu lze použít pouze pro nezaúčtované transakce. Je nutno počítat s tím, že při volání metody ve stavu 7) Čekání na zúčtování může dojít ke zpracování zúčtování transakce, metoda vrátí chybu a transakce již bude proplacena.
Zařazení transakce do zúčtování payment/close Tuto operaci voláme pouze v případě, že v založení platby máme vypnuto její automatické zařazení do zúčtování. Volání této funkce zařadí transakci do zúčtování a může být v e-shopu například spojena s okamžikem odeslání zboží.
Žádost o vrácení transakce payment/refund Tuto operaci voláme v případě, že je třeba vrátit prostředky zpět plátci. Příkladem je třeba reklamace zboží, zrušení objednávky nebo odstoupení od koupě na e-shopu v zákonné lhůtě.
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.
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 tř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é emailové 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:
- Vyžádá od plátce jeho MerchantID a registrovanou eMailovou adresu
- Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
- Nabídne pouze možnost generování testovacích klíčů
- Lokálně vygeneruje testovací pár klíčů private key/public key
- Privátní část private key uloží do souboru v počítači obchodníka
- Veřejnou část odešle zabezpečeným kanálem na platební bránu
Integrace V tomto okamžiku může obchodník spustit integraci svého řešení (e-shopu) s platební bránou. Privátní klíč předá vývoji, který může vyvíjet a testovat proti veřejné iBráně. Jeho klíč je tam automaticky zaveden ihned po vygenerování.
Integrační prostředí (iBrána)
Pro integraci a otestování napojení eshopu na eAPI platební brány je pro obchodníka k dispozici integrační prostředí (tzv. iBrána) bežící na adrese https://iapi.iplatebnibrana.csob.cz.
V tomto prostředí je 3DS autentizace a vlastní autorizace plateb prováděna oproti simulátoru, nicméně samotná funkcionalita platební brány včetně eAPI a uživatelského rozhraní je identická s produkčním prostředím. Obchodník tak může otestovat nejenom vlastní přechod z eshopu 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ě:
- Vyžádá od plátce jeho MerchantID a registrovanou eMailovou adresu
- Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
- Zjistí, že obchodník je aktivován a má splněny integrační testy
- Lokálně vygeneruje ostrý pár klíčů private key/public key
- Privátní část private key uloží do souboru v počítači obchodníka
- Veřejnou část odešle zabezpečeným kanálem kanálem na platební bránu
- Platební brána odešle na registrovanou adresu obchodníka aktivační kód
Potvrzení ostrého klíče obchodníkem Pro vyšší bezpečnost, ale také pro případ, kdy za běhu systému potřebuje obchodník svůj klíč vyměnit, je zde ještě jeden krok oproti testovacímu prostředí:
Obchodník má přístup do systému PosMerchant, kde se mu jeho nově vygenerovaný klíč objeví v částí eCommerce. Teprve zde jej potvrdí a zaktivuje. K této operaci je třeba jednorázový aktivační kód, který při převzetí veřejné části klíče odeslala brána na email obchodníka. Okamžikem této aktivace se klíč přenese na platební pránu a ta jej ihned začne používat. Tímto krokem je jednak 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 email) 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.
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í pak, 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 eshopu" 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 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ěd z hlediska bezpečnosti pouze obecný HTTP status kód (např. 400 Bad Request nebo 403 Forbidden).
Tučně uvedené parametry jsou pro volání povinné
| 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
|
| 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
|
| 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ě. Defaultně je mutace česká. Povolené hodnoty: CZ, EN, DE, SK
|
| signature | String | Podpis požadavku, kódováno v BASE64 |
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 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: Ve verzi 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/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"
}'
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 15ti 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 |
| 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":"123456789",
"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":"123456789",
"dttm":"20140425131559",
"resultCode": 100,
"resultMessage":"Missing parameter 'totalAmount'",
"paymentStatus": 6,
"signature":"base64-encoded-response-signature"
}
Požadavek obsahuje položky přímo v URL adrese https://api.platebnibrana.csob.cz/api/v1/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/payment/process/012345/123456789/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 302 Found
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.
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í ve v1 podporovat zpracování návratovych hodnot pomocí metody GET i POST (platební brána provadí redirect podle parametru returnMethod, u některých akcí -- např. zrušení platby uživatelem -- nicméně provede vždy redirect pomocí GET metody).
Příklad návratových hodnot při přesměrování z platební brány na e-shop pomocí metody POST:
Http-Method: POST
Address: https://vasobchod.cz/gateway-return
Payload:
payId=123456789&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=123456789&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“.
Požadavek obsahuje položky přímo v URL adrese https://api.platebnibrana.csob.cz/api/v1/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/payment/status/012345/123456789/20140425131559/base64-encoded-request-signature
Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.
Příklad návratových hodnot pro payment/status:
{
"payId":"123456789",
"dttm":"20140425131559",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 4,
"authCode":"F7A23E",
"signature":"base64-encoded-response-signature"
}
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/payment/reverse \
-H "Content-Type:application/json" \
-d '{
"merchantId":"012345",
"payId":"123456789",
"dttm":"20140425131559",
"signature":"base64-encoded-request-signature"
}'
Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.
Příklad návratových hodnot pro payment/reverse:
{
"payId":"123456789",
"dttm":"20140425131559",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 5,
"signature":"base64-encoded-response-signature"
}
Operace zařadí transakci do zúčtování.
| Položka | Typ | Popis |
|---|---|---|
| merchantId | String | ID obchodníka přiřazené platební bránou |
| payId | String | Jednoznačné ID platby (přidělené platební bránou v operaci init) |
| dttm | String | Datum a čas odeslání požadavku ve formátu YYYYMMDDHHMMSS |
| 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/payment/close \
-H "Content-Type:application/json" \
-d '{
"merchantId":"012345",
"payId":"123456789",
"dttm":"20140425131559",
"signature":"base64-encoded-request-signature"
}'
Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.
Příklad návratových hodnot pro payment/close:
{
"payId":"123456789",
"dttm":"20140425131559",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 7,
"authCode":"F7A23E",
"signature":"base64-encoded-response-signature"
}
Voláním operace je zažádáno o návrat prostředků nazpět plátci. Aplikuje se na již zaúčtované transakce.
| 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/payment/refund \
-H "Content-Type:application/json" \
-d '{
"merchantId":"012345",
"payId":"123456789",
"dttm":"20140425131559",
"signature":"base64-encoded-request-signature"
}'
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":"123456789",
"dttm":"20140425131559",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 8,
"signature":"base64-encoded-response-signature"
}
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/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/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/echo/012345/20140425131559/base64-encoded-request-signature
Poznámka: hodnoty parametrů musí být „URL enkódovány“.
| 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"
}
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/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/customer/info/012345/cust123%40mail.com/20140425131559/base64-encoded-request-signature
Poznámka: hodnoty parametrů musí být „URL enkódovány“.
| 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",
}
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“.
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/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/payment/close \
-H "Content-Type:application/json" \
-d '{
"merchantId":"012345",
"payId":"123456789",
"dttm":"20140425131559",
"signature":"base64-encoded-request-signature",
}'
RETEZEC_ZPRAVY = "012345|123456789|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/customer/info/012345/cust123%40mail.com/20140425131559/url-encoded-signature
RETEZEC_ZPRAVY = "012345|cust123@mail.com|20140425131559"
signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))
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":"123456789",
"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 = "123456789|20140425131559|0|OK|1"
U transakcí ve stavu 4 nebo 7 (odpověď u operací payment/status, payment/close apod) se posílá se i autorizační kód, který je také součástí podpisu:
{
"payId":"123456789",
"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 = "123456789|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":"123456789",
"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 = "123456789|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).
| 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 (obchodnik 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) |
| 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) |