Home
➡️ Obsah a jednotlivé články ve wiki najdete v navigačním sloupci po pravé straně
Základní podporu 3D Secure 2, funkční na platební bráně od roku 2020, jsme výrazně rozšířili. Platební brána nyní podporuje předávání dodatečných dat o nákupu pro vylepšení ověření. Tato dodatečná data doporučujeme předávat v co největším rozsahu, protože se tím výrazně zvyšuje pravděpodobnost ověření bez potvrzení zákazníkem, které činí platbu pohodlnější a rychlejší.
Zásadní změna přichází v oblasti OneClick plateb, kde je nutné rozlišovat transakce s přítomností / bez přítomnosti zákazníka a technicky umět provést ověření zákazníka v prostředí e-shopu pomocí 3D Secure.
Podle toho, které služby platební brány používáte, si prosím prostudujte změny.
Platba na bráně
- Doporučujeme předávat dodatečná data o platbě. Zvýšíte tím šanci na ověření bez potvrzení zákazníkem, které činí platbu pohodlnější a rychlejší.
- Používání Apple Pay na platební bráně nevyžaduje žádné další úpravy.
OneClick platba
- Je nutné začít rozlišovat platby za přítomnosti zákazníka a bez přítomnosti zákazníka.
- API metody pro OneClick platbu jsme významně změnili, abychom byli schopni obsloužit ověření OneClick platby (3D Secure) přímo v e-shopu, bez přesměrování na bránu. Prostudujte si, prosím, pečlivě API metody pro OneClick platbu v nové podobě.
Apple Pay v e-shopu
- Máte-li Apple Pay integrovanou přímo v e-shopu, je nutné přejít na nový způsob obsluhy Apple Pay, který pracuje s dodatečnými daty o platbě při inicializaci Apple Pay platby. Následná zpracování transakce je nově řešeno tak, že umí obsloužit ověření transakce pomocí 3D Secure pro případ, že si vydavatel ověření vyžádá.
- Změněné API metody využívají stejnou logiku a transakční flow jako OneClick, tj. doporučujeme implementovat Apple Pay a OneClick současně.
Změny v ověřování karetních plateb nemají žádný dopad do platební metody Skip Pay a Platebního tlačítka ČSOB.
Apple Pay jsme vylepšili o vyšší úroveň zabezpečení transakcí pro asociaci Mastercard tak, aby nemuselo docházet k dodatečnému ověření a platba Apple Pay zůstala stejně pohodlná jako dosud. Pro zákazníky se nic nezmění (ti budou nadále potvrzovat Apple Pay transakce pomocí Touch ID nebo Face ID), e-shop bude nově posílat stejná bezpečnostní data jako pro běžné karetní transakce a 3D Secure 2. S tím souvisí změny v inicializaci Apple Pay transakcí, které jsou technicky popsány zde. Se současným spuštěním Google Pay jsou nyní sjednoceny procesy komunikace mezi e-shopem a platební bránou při zpracování transakcí z peněženek Apple Pay a Google Pay. Doporučujeme proto jejich implementaci najednou.
API platební brány nově podporuje možnost přímo integrovat platbu peněženkou Google Pay do e-shopu, nebo mobilní aplikace. Vaši klienti tak mohou jednoduše zaplatit pomocí karet v Google Pay a to bez opuštění e-shopu. Podporujeme jak karty v Android telefonech, tak karty uložené v Google účtu. Platba z Androidu je velice podobná jako u Apple Pay (ověření uživatele proběhne pomocí biometrie telefonu), platba v prohlížeči pomocí karty uložené v Google účtu je bez ověření na straně zákazníka, a proto musí být ověřena pomocí 3D Secure 2. Více informací o možnostech, které nabízí Google Pay najdete zde, specifikaci technické integrace pak v API metodách pro Google Pay.
V souladu s rozhodnutím vlády ČR o zrušení EET bylo k 31.12.2022 pozastaveno zpracování EET hlášení. EET rozšíření (původně dostupné ve verzích API 1.6, 1.7 a 1.8) je neaktivní.
Nové eAPI je současnost a zároveň budoucnost komunikace mezi obchodníkem a platební bránou. Než začnete bránu do vašeho e-shopu nebo mobilní aplikace eAPI integrovat, podívejte se, prosím, na kompletní dokumentaci k eAPI mezi e-shopem a bránou a návod, jak simulovat různé transakční stavy a jaké používat testovací karty.
V současné době jsou podporovány verze 1.0, 1.5, 1.6, 1.7, 1.8 a 1.9. Ukončování jednotlivých eAPI je popsáno detailněji na stránce API Sunset.
| Verze eAPI | Uvedeno | Nedoporučeno | Termín ukončení | Nové funkce a změny |
|---|---|---|---|---|
| 1.0 | 06/2015 | 10/2018 | 1.3.2023 | Výchozí verze při spuštění nové platební brány do provozu. |
| 1.5 | 10/2015 | 10/2019 | 1.4.2023 | Přidává opakovanou platbu (registraci a její následné provedení), umožňuje provedení částečné vratky transakce. Od 1.2.2023 je opakovaná platba povolena jen pro eAPI 1.9. |
| 1.6 | 04/2016 | 10/2019 | 1.4.2023 | Přidává datum zaúčtování (extension), umožňuje nastavit životnost transakce na bráně a možnost multibrandingu na jednom merchantID (více barevných schémat, logotypů). |
| 1.7 | 01/2017 | 10/2019 | 1.5.2023 | Přidává podporu platebního tlačítka ČSOB (jako náhradu systému PaySec). Paralelně byla spouštěna podpora EET, která byla dostupná v eAPI 1.6, 1.7 a 1.8. API ve verzi 1.9 EET již nepodporuje, provoz EET ukončen k 31.12.2022. |
| 1.8 | 10/2019 | 04/2022 | n/a | Přidává podporu Apple Pay, mallpay, Platby na míru, mění algoritmus podpisu na SHA-256 a přidává povinnost předávat klientskou IP adresu při OneClick platbě. V rámci operace payment/init byl zrušen parametr description (mění se tím i výpočet podpisu). Od 1.2.2023 je Apple Pay platba povolena jen pro eAPI 1.9. |
| 1.9 | 04/2022 | n/a | n/a | Přidává podporu Google Pay a vylepšené ověřování pomocí 3D Secure 2 a vylepšené zabezpečení Apple Pay. Již nepodporuje rozšíření pro EET (provoz ve starších verzích ukončen k 31.12.2022). |
Při nové implementaci doporučujeme vždy zvolit nejnovější dostupnou verzi API. Zejména při výrazných vylepšeních funkcí budou starší verze omezovány, protože nové verze eAPI budou reagovat mimo jiné na změny v povinných pravidlech karetních asociací.
| Funkce | Volání | 1.0 | 1.5 | 1.6 | 1.7 | 1.8 | 1.9 |
|---|---|---|---|---|---|---|---|
| Založení platby | payment/init |
✔️ 1 | ✔️ 1 | ✔️ | ✔️ | ✔️ | ✔️ |
| Opakovaná platba | payment/recurrent |
– | ❌8 | – | – | – | – |
| Platba na klik | oneclick/init |
– | – | ❌2,8 | ❌2,8 | ❌8 | ✔️ |
| Apple Pay | applepay/init |
– | – | – | – | ❌9 | ✔️ |
| Google Pay | googlepay/init |
– | – | – | – | – | ✔️ |
| Platba na míru | payment/init |
– | – | – | – | ✔️ | ✔️ |
| mallpay (resp. Skip Pay) | mallpay/init |
– | – | – | – | ✔️ | ✔️ |
| Platební tlačítko ČSOB | button/init |
– | – | – | ✔️3 | ✔️ | ✔️ |
| Zjištění stavu platby | payment/status |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Odvolání transakce | payment/reverse |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Zařazení transakce do zúčtování | payment/close |
✔️ 4 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Žádost o vrácení transakce | payment/refund |
✔️ 5 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Kontrola brány | echo |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Kontrola zákazníka | echo/customer |
✔️6 | ✔️6 | ✔️6 | ✔️6 | ✔️ | ✔️ |
| Hlášení tržby EET | rozšíření | – | – | ❌ | ❌ | ❌ | –7 |
1) neumožňuje nastavit životnost transakce (pouze default 30 min), nepodporuje multibranding
2) od eAPI 1.8 byla operace payment/oneclick/init přejmenována na oneclick/init
3) od eAPI 1.8 byla operace payment/button přejmenována na button/init
4) eAPI 1.0 umožňuje zaúčtování jen v plné výši, verze 1.5 a novější pak i zaúčtování platby kartou na menší částku
5) eAPI 1.0 umožňuje zaúčtování jen návrat (refund) v plné výši, verze 1.5 a novější pak i částečnou vratku, resp. několik po sobě jdoucích částečných vratek až do výše původní transakce
6) od eAPI 1.8 byla operace customer/info přejmenována na echo/customer
7) EET rozšíření není od verze 1.9 podporováno. Ve verzích 1.6, 1.7 a 1.8 byla podpora ukončena k 31.12.2022.
8) Ukončení OneClick plateb pro eAPI 1.8 a nižší (všechny OneClick šablony vytvořené ve starších verzích eAPI lze použít v eAPI 1.9)
9) Ukončení platební metody Apple Pay integrované přímo do e-shopu obchodníka (applepay@shop) pro eAPI 1.8 a nižší
Pro integraci a otestování napojení e-shopu na eAPI platební brány je pro obchodníka k dispozici integrační prostředí (tzv. iBrána) bežící na adrese https://iapi.iplatebnibrana.csob.cz. iBrána není nic jiného než pískoviště otevřené na hraní - bez smlouvy a komplikací. Dokumentaci i nástroj pro generování šifrovacích klíčů najdete tady na Gitu a můžete si naši platební bránu vyzkoušet ihned.
V tomto prostředí je 3DS autentizace a vlastní autorizace plateb prováděna oproti simulátoru (takže prosím používejte tyto karty), nicméně samotná funkcionalita platební brány včetně eAPI a uživatelského rozhraní je identická s produkčním prostředím. Můžete si tak otestovat nejenom vlastní přechod z e-shopu na platební bránu a zpět (předávání parametrů pomocí API) ale i finální vzhled platební brány - zobrazení loga obchodníka a jeho kontaktních údajů, zobrazení košíku a barevného schématu.