API integrace a zabezpečení - csob/platebnibrana GitHub Wiki
eCommerce se pohybuje ve světě otevřeného internetu, proto je nutné data putující mezi systémy e-shopu a platební bránou zabezpečit proti útokům zvenčí. Komunikační kanál je zabezpečen protokolem SSL, pro ověření autenticity obchodníka jsou však navíc všechny požadavky odesílané na platební bránu podepsané jeho privátním klíčem.
Platební brána má k dispozici veřejnou část klíče, pomocí které může ověřit, že požadavek vygeneroval právě tento obchodník. Pro správnou funkčnost je tedy nutné vygenerovat tento pár: privátní klíč + veřejný klíč, privátní část předat do systému obchodníka (e-shopu, backoffice apod.) a veřejnou část předat platební bráně, tedy bance. Tento proces je součástí integrace obchodníka a platební brány.
První fáze integrace následuje po sjednání poskytování služeb eCommerce v bance, kde obdržel obchodník své merchantID a uvedl, ze které e-mailové adresy bude s bankou komunikovat. V tomto okamžiku již jeho identita v systému platební brány existuje a vyčkává na další kroky takto:
Generování testovacích klíčů: Prostředky pro generování testovacích klíčů jsou dostupné na stránkách banky. Generátor zajišťuje, že přímo na stránce se do počítače obchodníka stáhne JavaScriptová aplikace obsahující generátor klíčů. Průvodce tohoto generátoru pak provede následující kroky:
- Vyžádá od plátce jeho merchantID a registrovanou e-mailovou adresu
- Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
- Nabídne pouze možnost generování testovacích klíčů
- Lokálně vygeneruje testovací pár klíčů private key/public key
- Privátní část private key uloží do souboru v počítači obchodníka
- Veřejnou část odešle zabezpečeným kanálem na platební bránu
Integrace: V tomto okamžiku může obchodník spustit integraci svého řešení (e-shopu) s platební bránou. Privátní klíč předá vývoji, který může vyvíjet a testovat proti veřejné iBráně. Jeho klíč je tam automaticky zaveden ihned po vygenerování.
Integrační prostředí (iBrána)
Pro integraci a otestování napojení e-shopu na eAPI platební brány je pro obchodníka k dispozici integrační prostředí (tzv. iBrána) bežící na adrese
https://iapi.iplatebnibrana.csob.cz.V tomto prostředí je 3DS autentizace a vlastní autorizace plateb prováděna oproti simulátoru, nicméně samotná funkcionalita platební brány včetně eAPI a uživatelského rozhraní je identická s produkčním prostředím. Obchodník tak může otestovat nejenom vlastní přechod z e-shopu na platební bránu a zpět (předávání parametrů), ale i finální vzhled platební brány - zobrazení loga obchodníka a jeho kontaktních údajů, zobrazení košíku a barevného schématu.
Schválení: Jakmile je integrace dokončena, obchodník o této skutečnosti informuje banku a provede sérii předepsaných testů. Banka ověří jejich výsledky oproti záznamům testovací iBrány a v pozitivním případě obchodníka aktivuje.
Generování ostrých klíčů: V tomto okamžiku může obchodník vygenerovat nové, ostré klíče, které použije pro provozní prostředí. Použije generátor produkčních klíčů dostupný na stránkách banky, který pracuje následovně:
- Vyžádá od plátce jeho merchantID a registrovanou e-mailovou adresu
- Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
- Zjistí, že obchodník je aktivován a má splněny integrační testy
- Lokálně vygeneruje ostrý pár klíčů private key/public key
- Privátní část private key uloží do souboru v počítači obchodníka
- Veřejnou část odešle zabezpečeným kanálem na platební bránu
- Platební brána odešle na registrovanou adresu obchodníka aktivační kód
Potvrzení ostrého klíče obchodníkem Pro vyšší bezpečnost, ale také pro případ, kdy za běhu systému potřebuje obchodník svůj klíč vyměnit, je zde ještě jeden krok oproti testovacímu prostředí:
Obchodník má přístup do systému ČSOB POS Merchant, kde se mu jeho nově vygenerovaný klíč objeví v částí eCommerce. Teprve zde jej potvrdí a zaktivuje. K této operaci je třeba jednorázový aktivační kód, který při převzetí veřejné části klíče odeslala brána na e-mail obchodníka. Okamžikem této aktivace se klíč přenese na platební bránu a ta jej ihned začne používat. Tímto krokem je dvojitě zabezpečeno předání klíče a současně obchodník sám určuje okamžik jeho zavedení na platební bránu.
Pískoviště
Systém umožňuje implementaci API rozhraní a přípravu na integraci e-shopu ještě před návštěvou banky a bez jakýchkoli závazků. Tomuto postupu říkáme nultá fáze - pískoviště, na kterém si můžete s bránou hrát (ale nezlobit). Lze tedy nejdříve zapojit vývoj, ověřit funkčnost napojení a teprve pak přejít do první fáze, navštívit banku a s obdrženým merchantID se napojit na testovací prostředí.
Ve skutečnosti ale probíhá stejně jako první fáze. V průvodci generováním klíčů na adrese https://iplatebnibrana.csob.cz/keygen se však vybere možnost Anonymní vývoj (nevyplňuje se merchantID ani e-mail) a průvodce následně zažádá platební bránu o přidělení vývojového merchantID. K tomuto merchantID pak obchodník vygeneruje na svém lokálním počítači klíče, veřejnou část přenese na platební bránu a privátní uloží do souboru.
Testovací přístup pro anonymní vývoj je platný jeden měsíc stejně jako testovací klíče. Přístupy jeho prostřednictvím jsou monitorovány a v případě zatížení neúměrného vývoji a testování mohou být služby pro toto merchantID omezeny.