Home

Vítejte ve wiki platební brány ČSOB!

➡️ Obsah a jednotlivé články ve wiki najdete v navigačním sloupci po pravé straně

⬇️ Please scroll down for 🇬🇧 English

Novinky ve verzi platební brány 1.7 (a s ní souvisejícím eAPI 1.7)

MasterPass

Platební brána nově podporuje platbu peněženkami dle globálního standardu MasterPass. Nová platební metoda bude dostupná pro všechny obchodníky přímo na platební bráně (tj. klient si může MasterPass jako preferovanou platbu vybrat po přesměrování na bránu). Chcete-li nabídnout zákazníkům komfortnější platbu MasterPass, můžete využít nových API funkcí (payment/masterpass) a vyvolávat platbu MasterPass přímo z e-shopu, bez potřeby přesměrování na platební bránu. Během takto implementované platby můžete z digitální peněženky MasterPass přijmout i adresu a další údaje klienta, které pak klient nemusí u vás v e-shopu vyplňovat.

Spuštění podpory MasterPass předpokládáme v první polovině února 2017. Implementovat a testovat proti prostředí iBrána můžete již nyní dle specifikace eAPI 1.7.

Platební tlačítka ČSOB a ERA

V souvislosti s uzavíráním platebního systému PaySec přebírá platební brána zpracování transakcí [platebními tlačítky ČSOB a Poštovní spořitelny](Platební tlačítko ČSOB a Poštovní spořitelny). Podobně jako u MasterPass je platba tlačítkem dostupná na bráně (bez nutnosti implementace v e-shopu), nebo jako přímá integrace do e-shopu pomocí nových API funkcí payment/button.

Spuštění platebních tlačítek předpokládáme v dubnu 2017. Implementovat a testovat proti prostředí iBrána můžete již nyní dle specifikace eAPI 1.7.

Novinky ve starších verzích eAPI a archiv dokumentace najdete [zde](Archiv starších verzí eAPI).

Podporované verze eAPI

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 shopu nebo mobilní aplikace eAPI integrovat, podívejte se, prosím, na kompletní dokumentaci k eAPI mezi e-shopem a bránou, 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 a 1.7. K dispozici je dokumentace verze 1.7, jejíž funkce budou postupně spouštěny v Q1/2017.

Verze eAPI	Uvedeno	Nedoporučeno	Ukončeno	Nové funkce a změny
1.0	06/2015	n/a	n/a	Výchozí verze při spuštění nové platební brány do provozu
1.5	10/2015	n/a	n/a	Přidává opakovanou platbu (registraci a její následné provedení), umožňuje provedení částečné vratky transakce
1.6	04/2016	n/a	n/a	Přidává datum zaúčtování (extension), umožňuje nastavit životnost transakce na bráně a možnost multibrandingu na jednom Merchant ID (více barevných schémat, logotypů)
[1.7](eAPI v1.7)	01/2017	n/a	n/a	Přidává podporu MasterPass a [platebních tlačítek ČSOB a ERA](Platební tlačítko ČSOB a ERA) (jako náhradu systému PaySec). Paralelně je spouštěna [podpora EET](Hlášení tržeb z platební brány), která je dostupná v eAPI 1.6 a vyšším.

Při nové implementaci doporučujeme vždy zvolit nejnovější dostupnou verzi API. Ačkoli ukončování podpory starších verzí API není v roce 2017 na pořadu dne, starší verze nebudou podporovány navždy. 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í	eAPI v1.0	eAPI v1.5	eAPI v1.6	eAPI v1.7
Založení platby	payment/init	✅ *	✅ *	✅	✅
Přesměrování na bránu	payment/process	✅	✅	✅	✅
Opakovaná platba	payment/recurrent	❌	✅	❌	❌
Platba na klik	payment/oneclick	❌	❌	✅	✅
MasterPass	payment/masterpass	❌	❌	❌	✅
Platební tlačítko ČSOB	payment/button	❌	❌	❌	✅
Platební tlačítko Poštovní spořitelny	payment/button	❌	❌	❌	✅
Zjištění stavu platby	payment/status	✅	✅	✅	✅
Odvolání transakce	payment/reverse	✅	✅	✅	✅
Zařazení transakce do zúčtování	payment/close	✅**	✅	✅	✅
Žádost o vrácení transakce	payment/refund	❎ ***	✅	✅	✅
Kontrola brány	echo	✅	✅	✅	✅
Kontrola zákazníka	customer/info	✅	✅	✅	✅
Hlášení tržby EET	rozšíření	❌	❌	✅	✅

*) neumožňuje nastavit životnost transakce (pouze default 30 min), nepodporuje multibranding

**) eAPI v1 umožňuje zaúčtování jen v plné výši, eAPI v1.5, v1.6 a v1.7 pak i zaúčtování na menší částku

***) eAPI v1 umožňuje návrat jen v plné výši, eAPI v1.5, v1.6 a v1.7 pak i částečný refund

Chcete si jen zkusit, jak brána funguje?

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

Welcome to the ČSOB payment gateway wiki!

Rozdíly v integraci pomocí Legacy API a moderním eAPI

Platební brána má momentálně dvě rozhraní. Legacy API umožňuje přechod z již používané brány GP Webpay pro většinu obchodníků bez vývoje. Legacy API podporuje základní trasakční funkce, nepodporuje však funkce související se zjišťováním stavu transakcí a správou objednávek. Pokud ve Vašem e-shopu používáte SOAP rozhraní původní platební brány GP Webpay pro zjišťování stavů objednávek, implementujte, prosím, rovnou nové eAPI, protože Legacy API tuto funkci nemá.

Návod na migraci z platební brány ČSOB GP Webpay na novou platební bránu ČSOB najdete zde. Legacy API nebude již nadále rozvíjeno a proto doporučujeme v horizontu do léta 2016 vyvinout ve vašem e-shopu podporu eAPI. Jedině tak budete moci využívat všechny chystané funkce nové platební brány.

eAPI je zcela nové, moderní RESTful API pro komunikaci e-shopu s platební bránou a také základ pro rozvoj nových služeb. Kombinuje do jednoho interfacu jak transakční, tak obslužné funkce.

➡️ Please use the right sidebar to navigate

New features in the Gateway v1.7 (and the eAPI 1.7)

MasterPass

Payment gateway now supports digital wallets based on the global MasterPass standard. The new payment method is available for all merchants and their customers on the payment gateway (without the need to implement MasterPass functionality in the e-shop). We also offer new API integration of MasterPass for merchants who want to offer their customers a more convenient way to pay with MasterPass without leaving the shop. New API operation (payment/masterpass) allows you to extract shipping and billing data from the digital wallet, making your checkout experience faster and more convenient (as the customer do not need to type their address and other data).

We expect to launch MasterPass support by mid February 2017. However you can develop and test already now, based on eAPI 1.7 documentation.

Payment Button ČSOB and ERA

Payment buttons of ČSOB and ERA (invoke of transfer from a current account with a real time payment guarantee) . Similar to MasterPass, the payment buttons are available both on the payment gateway and for direct implementation in your e-shop (using new eAPI operation payment/button).

We expect to launch full support for payment buttons in April 2017. However you can develop and test already now, based on eAPI 1.7 documentation.

For new features and documentation of older eAPI versions, please refer to [overview](Archived eAPI versions) of all new features across eAPI versions.

Using the eAPI

Please read the documentation (in this wiki) carefully before starting your implementation. You will also find php and java examples in the repo itself. All information needed for a successfull implementation is listed in the wiki. Should you encounter a problem, feel free to open an issue. Please consult the FAQ (both commercial and technical) and past (closed) issued before raising a new issue.

We currently support versions 1.0, 1.5, 1.6. Documentation of eAPI 1.7 is available as of January 2017 and new features (MasterPass and payment buttons) will be launched gradually over the course of Q1/17.

eAPI version	Launched	Deprecated	Discontinued	New features and changes
1.0	06/2015	n/a	n/a	Initial version
1.5	10/2015	n/a	n/a	Adds recurring payment, allows for partial refund
1.6	04/2016	n/a	n/a	Adds dynamic transaction TTL support, ability to use multiple brands and colour schemes with one Merchant ID
1.7	01/2017	n/a	n/a	Adds support for MasterPass and ČSOB/ERA payment button (feature replacement of the discontinued PaySec payment system). Support for electronic registration of sales ("EET") is launched in parallel to eAPI 1.7 and is available as extension for eAPI 1.6 and higher.

We strongly suggest implementation of the up-to-date API version. While we do not intend to discontinue support of older API versions neither in 2015 nor in 2016, we will deprecate and discontinue older versions in the future. This will happen mainly with large releases of new features, often tied to changes in compulsory rules of Visa and MasterCard.

Feature	Call	eAPI v1.0	eAPI v1.5	eAPI v1.6	eAPI v1.7
Payment initiation	payment/init	✅ *	✅ *	✅	✅
Redirecting to gateway	payment/process	✅	✅	✅	✅
Recurrent payment	payment/recurrent	❌	✅	❌	❌
One click payment	payment/oneclick	❌	❌	✅	✅
MasterPass	payment/masterpass	❌	❌	❌	✅
Payment button ČSOB	payment/button	❌	❌	❌	✅
Payment button Poštovní spořitelna	payment/button	❌	❌	❌	✅
Payment status detection	payment/status	✅	✅	✅	✅
Transaction reversal	payment/reverse	✅	✅	✅	✅
Confirm transaction and settle	payment/close	✅**	✅	✅	✅
Refund request	payment/refund	❎ ***	✅	✅	✅
Gateway verification	echo	✅	✅	✅	✅
Customer verification	customer/info	✅	✅	✅	✅
Electronic records of sales	Extension	❌	❌	✅	✅

*) eAPI v1 and 1.5 does not support multibranding and dynamic transaction TTL (only default value of 30 minutes)

**) eAPI v1 allows only closing payment with full amount while the eAPI v1.5, v1.6, v1.7 can process also a closing with a smaller amount than initially authorised

***) eAPI v1 allows only for a full refunds while the eAPI v1.5, v1.6, v1.7 can process also a partial refund

Differences between the Legacy API and modern new eAPI

The payment gateway features two APIs. The legacy API allows for a simple switch from the GP Webpay system (previously used by ČSOB to process eCommerce transactions). It supports basic transaction functions, but it does not support the SOAP based backoffice calls. Therefore, if you currently use GP Webpay and you have implemented the transaction management through SOAP, please implement eAPI.

Necessary steps to be taken during the Legacy API migration are described in a separate article. Please remember this Legacy API will not be further developed in any way and all new features will be supported only by the new eAPI.

The eAPI is a completely new, modern, RESTful API for communication between your shop and the payment gateway. It is also a platform for new products and services that we will launch soon. This one API combines transaction as well as backoffice management functions.