Časté technické dotazy

Při odeslání požadavku na eAPI se vrací http status 400 (Bad request) nebo 401 (Unauthorized)

Pravděpodobně se jedná o špatný podpis požadavku. Nejčastější chyby a opomenutí jsou následující:

řetězec pro výpočet podpisu je chybný nebo je použit špatný algoritmus pro podpis požadavku, více viz specifikace v rámci eAPI
používá se špatný privátní klíč obchodníka pro podpis požadavku (jedná se např. o záměnu privátního klíče pro integrační a produkční prostředí)
v případě parametru closePayment u operace payment/init se do řetězce pro podpis nevkládá povolená hodnota true nebo false ale (v případě použití php) hodnota 1 nebo 0

Pozn. pro eAPI 1.0 - 1.8 se vrací v případě neplatného podpisu http response kód 400 Bad request. Od eAPI 1.9 je v případě neplatného podpisu vrácen http response kód 401 Unauthorized, včetně detailního popisu chyby. Viz popis na stránce Volání rozhraní eAPI.

Jaký algoritmus nastavit při vytváření a ověřování podpisu?

Pro podepisování je potřeba použít algoritmus založený na SHA-1 (pro eAPI v1.7 a nižší), nebo SHA-256 (pro eAPI v1.8 a vyšší). Například v Javě je potřeba použít při inicializaci třídy java.security.Signature algoritmus "SHA256withRSA", v PHP je potřeba použít pro volání funkcí openssl_sign() a openssl_verify() algoritmus "OPENSSL_ALGO_SHA256".

Příklad podepisování v Javě

Příklad podepisování v .NET

Kolik může košík obsahovat položek?

Ve verzi v1.0, v1.5, v1.6, v1.7, v1.8 a v1.9 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é").

Při odesílání payment/init se vrací chybový kód 900

Pozor na správné zformátování položek košíku, platební brána očekává pro parametr cart seznam prvků, tzn. položky musí být uzavřeny v [ a ], a to i v případě, že košík obsahuje jen jednu položku.

správně:

"cart":[ { "name":"Rezervace", "quantity":1, "amount":10000 } ]

špatně:

"cart": { "name":"Rezervace", "quantity":1, "amount":10000 }

Pozor na formátování parametru extensions pro EET, je třeba jej formátovat také jako pole a ne jako objekt.

"extensions":[ { "extension": "eetV3", "dttm": "20170125131559", "data": { "premiseId": 181, "cashRegisterId": "00/2535/CN58", "totalPrice": 17896.00 }, "signature": "base64-encoded-extension-signature" } ]

Jak načíst veřejný klíč ve formátu PEM?

Veřejný klíč platební brány potřebný na straně obchodníka k ověření podpisu odpovědi je distribuován v textovém PEM formátu. Níže jsou uvedeny příklady jeho inicializace před vlastním použitím v programovacích jazycích Java, PHP a pro platformu .NET.

JAVA

String publicKeyFileName = "test.pub";
String content = FileUtils.readFileToString(new File(publicKeyFileName));
content = StringUtils.remove(content, "-----BEGIN PUBLIC KEY-----");
content = StringUtils.remove(content, "-----END PUBLIC KEY-----");
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64.decodeBase64(content));
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PublicKey publicKey = keyFactory.generatePublic(keySpec);

PHP

$publicKeyFileName = "test.pub";
$fp = fopen ($publicKeyFileName, "r" );
if (! $fp) {
    throw new Exception ( "Public key " . $publicKeyFileName . " not found" );
}
$content = fread ($fp, filesize ( $publicKeyFileName ) );
fclose ( $fp );
$publicKey = openssl_get_publickey ( $content );

.NET

Ukázka načítání klíče pro podepisování a ověřování podpisu je v samostatném snippetu.

Při odeslání payment/process se vrací http status 404, not found

Operace payment/process se volá pomocí http metody GET. Zkontrolujte, zda je poslední část url - parametr signature - "URL encoded". Vzhledem k tomu, že podpis požadavku je přenášen v kódování Base64, obsahuje pravděpodobně i znak /. Platební brána takto nesprávně formátovaný požadavek nepřijme (nemůže načíst správně parametr signature).

Jaké časové pásmo použít pro vyplnění hodnoty parametru dttm?

Pro parametr dttm posílaný v požadavcích na platební bránu vyplňte hodnotu pro časové pásmo CET/CEST. Stejné časové pásmo je použito pro vyplnění parametru dttm v odpovědích z platební brány. Přínosem pro obchodníka bude snazší orientace při dohledávání případných problémů v odesílaných požadavcích. Tento parametr je primárně použit pro výpočet podpisu.

Jaké kódování použít pro české znaky v JSON datech?

Texty předávané v JSON požadavcích je potřeba kódovat v UTF-8.

Založení platby proběhne neúspěšně z důvodu chybové SSL hlášky?

Je možné, že používáte nepodporovanou/starou verzi openssl, případně kryptografické protokoly SSL v2/v3, TLS v1.0 nebo TLS v1.1. Doporučujeme tedy aktualizovat verzi OpenSSL s podporou nejméně TLS v1.2 v případě výskytu níže uvedené hlášky.

reason: error:14077410:SSL routines:SSL23 _GET_SERVER_HELLO:sslv3 alert handshake failure

Integrace - TLS v1.2 vyžadováno od 12/2017

Produkce - TLS v1.2 vyžadováno od 07/2018

Založení platby proběhne neúspěšně z důvodu nedůvěryhodného certifikátu při komunikaci s eAPI

Server obchodníka, na kterém běží jeho e-shop, komunikuje s eAPI pomocí adresy https://api.platebnibrana.csob.cz zabezpečené pomocí https protokolu. Obchodník na straně e-shopu v rámci integrace nastavuje nejenom adresu serveru platební brány, ale podle typu použité technologie (např. Java) musí/může provést i dodatečnou konfiguraci spočívající v přidání jednoho nebo více certifikátů, které jsou vystaveny pro https://api.platebnibrana.csob.cz do tzv. truststore souboru. Tímto způsobem je na straně e-shopu nastaveno, že při navazování bezpečného spojení s https://api.platebnibrana.csob.cz má e-shop tomuto serveru důvěřovat. Implementace důvěry certifikátů je na rozhodnutí programátora třetí aplikace. Doporučujeme tuto integraci z bezpečnostních důvodů používat.

Certifikát pro https://api.platebnibrana.csob.cz je vydáván na omezenou dobu. Aktuální platnost a výměna je popsána v následující sekci Výměna certifikátu.

V případě problémů s navázáním spojení s https://api.platebnibrana.csob.cz je potřeba stáhnout nový certifikát z https://api.platebnibrana.csob.cz včetně všech CA certifikátů, kterými je tento nový certifikát podepsán. Tento nový certifikát včetně souvisejících CA certifikátů je pak potřeba přidat do truststore souboru (např. Java).

To, zda je nutné provést výše popsané přidání jednoho nebo více certifikátů do truststore souboru, závisí na konkrétním nastavení daného systému, na němž běží e-shop obchodníka. Je možné, že systém obchodníka, na kterém běží e-shop, používá v případě Java technologie defaultní cacerts soubor, ve kterém jsou uloženy kořenové certifikáty dodávané v rámci instalačního balíku Javy. V takovém případě s největší pravděpodobností nebude nutné provádět žádné úpravy (nový certifikát pro https://api.platebnibrana.csob.cz je podepsán pomocí certifikátu certifikační autority, který je podepsán kořenovým certifikátem uloženým v tomto cacerts souboru, kořenový certifikát je pro původní i nový certifikát pro https://api.platebnibrana.csob.cz stejný). Je potřeba mít také updatovaný JAVA balíček, ve kterém jsou aktuální CA certifikáty.

Výměna certifikátu https://api.platebnibrana.csob.cz

Týká se to zákazníků, kteří mají implementováno ověření důvěry certifikátů na https://api.platebnibrana.csob.cz.

Konec platnosti serverového certifikátu je v pondělí 4. září 2022. Měsíc předem bude zde zveřejněn termín výměny serverového certifikátu za nový. Pozor s novým certifikátem se mění i všechny nadřazené CA certifikáty.

Aktuální certifikát je možné nalézt na https://api.platebnibrana.csob.cz.

Dne 01.09.2022 ve 22:00 dojde k výměně stávajících certifikátů jejichž platnost končí v pondělí 4. září 2022. Nové certifikáty jsou zobrazeny níže, je nutné importovat oba typy(RSA + ECDSA).

RSA:

ECDSA:

Transakce platebním tlačítkem ČSOB je klientem z účtu zaplacena, v POS Merchantu ji vidím jako autorizovanou, ale v mém e-shopu je transakce zamítnuta

Transakce platebním tlačítkem má jedno specifikum v životním cyklu - autorizovaná transakce se okamžitě dostane do stavu 8. Je možné, že váš e-shop vyhodnocuje jako "zaplaceno" pouze stavy 4 a 7. Je tedy nutné provést drobný zásah do integrace v e-shopu.

Vygenerovaný klíč nelze automaticky stáhnout v Safari prohlížeči

Místo stažení se vygenerovaný klíč v keygen aplikaci ve starších verzích prohlížeče Safari pouze zobrazí na stránce. Pokud nemůžete aktualizovat na novější verzi Safari, doporučujeme manuálně uložit pomocí ⌘+S.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Časté technické dotazy

Při odeslání požadavku na eAPI se vrací http status 400 (Bad request) nebo 401 (Unauthorized)

Jaký algoritmus nastavit při vytváření a ověřování podpisu?

Kolik může košík obsahovat položek?

Při odesílání payment/init se vrací chybový kód 900

Jak načíst veřejný klíč ve formátu PEM?

JAVA

PHP

.NET

Při odeslání payment/process se vrací http status 404, not found

Jaké časové pásmo použít pro vyplnění hodnoty parametru dttm?

Jaké kódování použít pro české znaky v JSON datech?

Založení platby proběhne neúspěšně z důvodu chybové SSL hlášky?

Založení platby proběhne neúspěšně z důvodu nedůvěryhodného certifikátu při komunikaci s eAPI

Výměna certifikátu https://api.platebnibrana.csob.cz

Transakce platebním tlačítkem ČSOB je klientem z účtu zaplacena, v POS Merchantu ji vidím jako autorizovanou, ale v mém e-shopu je transakce zamítnuta

Vygenerovaný klíč nelze automaticky stáhnout v Safari prohlížeči

💳 Platební brána

💰 Platby

🔬 eAPI 1.9

📐 Návody a podklady

📟 API rozšíření

🔧 Časté dotazy (FAQ)

📡 Archiv starších verzí eAPI

Clone this wiki locally