Postup integrace, klíče a kde je vzít - csob/posmerchantapi GitHub Wiki

pmAPI je přístupné z otevřeného internetu, proto je nutné data putující mezi systémy obchodníka a banky zabezpečit proti útokům. Komunikační kanál je zabezpečen protokolem SSL (HTTPS), pro ověření identity obchodníka jsou však navíc všechny požadavky odesílané na pmAPI podepsané jeho privátním klíčem a všechny odpovědi podepsané privátním klíčem banky.

pmAPI dostane 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 komunikace je tedy třeba vygenerovat tento pár privátní klíč + veřejný klíč. Privátní část předat do systému obchodníka (informační systém obchodníka komunikující na pmAPI) a veřejnou část předat na pmAPI, tedy bance. Tento proces je součástí integrace obchodníka.

3.1. První fáze

Integrace pmAPI začíná po sjednání poskytování těchto služeb v bance. Obchodník obdrží své MerchantID a uvede, ze které emailové adresy bude s bankou komunikovat.

Postup integrace a spuštění ostrého provozu

3.2. Generování testovacích klíčů

Prostředky pro generování testovacích klíčů jsou dostupné na stránkách POSmerchant v integračním prostředí. Klíče se generují pomocí technologie JavaScript přímo na počítači obchodníka. Privátní část klíče se nepřenáší přes internet, banka k němu nemá přístup. Počítač by měl být bezpečný - nainstalována aktuální verze antivirového programu, dodržování pravidel bezpečného používání.

Generování a registrace testovacího klíče probíhá v POSMerchantu v integračním prostředí (https://iposman.iplatebnibrana.csob.cz/posmerchant) na záložce Obchodníci, po kliknutí na ikonu klíče. Tato funkce je dostupná až po sjednání a povolení funkce pmAPI.

Nabídne se možnost vygenerování testovacího klíče, případně vložení vlastního veřejného klíče.

Při zvolení možnosti vložit vlastní klíč, vloží obchodník veřejnou část svého RSA klíče (public key).

Při zvolení možnosti vygenerování testovacího klíče proběhne generování pomocí technologie JavaScript přímo na počítači obchodníka. Soukromý klíč neopustí počítač.

Veřejný klíč (public key) slouží k ověření podpisu zprávy od obchodníka na straně pmAPI. Tento klíč je vhodné stáhnout a zazálohovat pro případ jeho obnovy/opětovného zavedení na POSMerchant při problémech. Je nutné jej odeslat na server pomocí tlačítka POTVRDIT KLÍČE. Obchodník s tímto klíčem nepracuje.

Soukromý klíč (private key) slouží k podpisu zprávy zaslané obchodníkem na pmAPI. Tento klíč je nutné stáhnout, bezpečně zazálohovat a předat do systému komunikujícího na pmAPI.

Po POTVRZENÍ KLÍČE je na registrovanou emailovou adresu distribuován aktivační kód pro potvrzení a aktivaci klíče.

3.3. Integrace

V tomto okamžiku může obchodník spustit integraci svého řešení (informačního systému) s pmAPI. Privátní klíč obchodníka společně s veřejným klíčem banky předá vývoji, který může vyvíjet a testovat proti veřejnému testovacímu prostředí pmAPI.

3.3.1. Integrační prostředí pmAPI

Pro integraci a otestování napojení obchodníkova informačního systému na pmAPI je obchodníkovi k dispozici veřejné integrační prostředí pmAPI.

V tomto prostředí je možné ověřit správnou implementaci všech podporovaných funkcí, podpisů požadavků a parsování odpovědí. Integrační prostředí nepracuje s reálnými transakcemi nebo výpisy, poskytuje pouze automaticky generované odpovědi, závislé na přijatém požadavku. Nicméně samotná funkcionalita je identická s produkčním prostředím.

3.4. Schválení

Jakmile je obchodník spokojen s výsledky integračních testů napojení svého informačního systému na testovací prostředí pmAPI, informuje banku o dokončení integračních testů a vůle zahájit přechod do ostrého provozu. Banka ověří výsledky testů a udělí obchodníkovi souhlas s přechodem do produkčního prostředí.

Ověření splnění všech integračních testů je dostupné v POSMerchantu v integračním prostředí (https://iposman.iplatebnibrana.csob.cz/posmerchant) na záložce Obchodníci, po kliknutí na ikonu fajfky. Tato funkce je dostupná až po sjednání a povolení funkce pmAPI.

Zde je zobrazen seznam požadovaných volání pmAPI, které je doporučeno provést pro splnění integračních testů.

3.5. Generování ostrých klíčů

Po schválení přechodu do ostrého provozu je obchodníkovi umožněno vygenerovat nové, ostré klíče, které budou použity pro provoz v produkčním prostředí. Generátor ostrých klíčů je dostupný na stránkách POSmerchant. Generátor ostrých klíčů pracuje shodným způsobem, jako generátor testovacích klíčů, tedy lokálně na počítači obchodníka.

Generování a registrace ostrého klíče probíhá v POSMerchantu (https://posman.csob.cz/posmerchant) na záložce Obchodníci, po kliknutí na ikonu klíče. Tato funkce je dostupná až po sjednání a povolení funkce pmAPI.

Nabídne se možnost vygenerování klíče, případně vložení vlastního veřejného klíče.

Při zvolení možnosti vložit vlastní klíč, vloží obchodník veřejnou část svého RSA klíče (public key).

Při zvolení možnosti vygenerování klíče proběhne generování pomocí technologie JavaScript přímo na počítači obchodníka. Soukromý klíč neopustí počítač.

Veřejný klíč (public key) slouží k ověření podpisu zprávy od obchodníka na strane pmAPI. Tento klíč je vhodné stáhnout a zazálohovat pro případ jeho obnovy/opětovného zavedení na POSMerchant při problémech. Je nutné jej odeslat na server pomocí tlačítka POTVRDIT KLÍČE. Obchodník s tímto klíčem nepracuje.

Soukromý klíč (private key) slouží k podpisu zprávy zaslané obchodníkem na pmAPI. Tento klíč je nutné stáhnout, bezpečně zazálohovat a předat do systému komunikujícího na pmAPI.

Po POTVRZENÍ KLÍČE je na registrovanou emailovou adresu distribuován aktivační kód pro potvrzení a aktivaci klíče.

3.6. 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 oproti testovacímu prostředí jeden krok navíc.

Obchodník má přístup do systému POSMerchant ČSOB, kde se jeho nově vygenerovaný klíč zobrazí v částí Platební terminály. Zde jej potvrdí a zaktivuje. K této operaci je třeba jednorázový aktivační kód, který obchodník obdržel na email při jeho generování, a který byl společně s veřejnou částí klíče odeslán na pmAPI. Okamžikem této aktivace se klíč aktivuje a pmAPI 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í.

3.7. Ostrý provoz

V tuto chvíli je již možné využívat veškeré funkce pmAPI.