Č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 28. června 2025. 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.

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.

3DS SDK vrátí Error Code 1310, Error Message "Failed verification of certificate chain from acsSignedContent" na integračním prostředí

Pro úspěšné otestování ověření pomocí 3DS SDK na integračním prostředí je potřeba do SDK nakonfigurovat následující testovací Monet+ CA certifikát. Tento certifikát je nakonfigurován v rámci integračního prostředí jednak v simulátoru „issuera“, stejný certifikát (jak pro VISA, tak pro MasterCard karty) musí být dostupný na straně 3DS SDK. Certifikát slouží pro zabezpečení dat v rámci potvrzení platby.

MIIDRTCCAi2gAwIBAgIJAJLLxUToqEONMA0GCSqGSIb3DQEBBQUAMDkxCzAJBgNVBAMMAmNhMQ4wDAY
DVQQKDAVNb25ldDENMAsGA1UEBwwEWmxpbjELMAkGA1UECAwCQ1owHhcNMTkwNTAyMTA1MDI4WhcNMz
kwNDI3MTA1MDI4WjA5MQswCQYDVQQDDAJjYTEOMAwGA1UECgwFTW9uZXQxDTALBgNVBAcMBFpsaW4xC
zAJBgNVBAgMAkNaMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApdbbhP/jFppHzJlvwAfs
3OJwf6aE4KHtQNX9OxZQEYU9oIaka1skt6cDdYPgnBq0V/NZyT6QhELQH0Jz1ODO7k54uDfHPKVa6q2
SCMHgtWzS1MnATTIs4Tk1MZmaUffcq0i8FZCkDUaTMvw3zjNXKNK63CTmzbZn780X5DsrOLe7PZhjY0
Oh3/xHmkPJxv6VyrQZrwS7sLVnHRNehubpcdRbSjTQ6vKvJijHFVLWWOaMCNF1mCpNNlx2ryhI2B28/
hjUoiWZOkuXENe2Zd6uGiyq4L3G6u5xQtb3agKYScly/Wsf4Um6WX/Fxq9rjvGFiuF8Taoat3UsC2WI
RiweswIDAQABo1AwTjAdBgNVHQ4EFgQUetOWxknkAOSnbLkRKuaCrEnTEAMwHwYDVR0jBBgwFoAUetO
WxknkAOSnbLkRKuaCrEnTEAMwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAiobsm/gVej
bD+bskg62Gg/X6dqn7TcixKT5EqseyIf32f+sUn2qG5UiK7L31wWzhhY5hvCrgDw0pHdVKNxC0Hm6DC
bnEExHUxXJWZi3F51xj4VHlrn6ZcVbTG79S30fxe4X2XNlXpdIGuTmPY4pl9p7YnB8edDJXpaP5BltJ
xTVhVIjwf7zxFemhW1ADOCg+Rv5SuakQjlR7Q2hKk0d7S/4urcEWRJABf4b4RsWJ/p7KJlBHRYSIX2z
DOKfsBRly5VIJhSgU9+gqztybhmTaBkapilSLSBNR0tTAeDZWlHz4Lbfx0IqF9FE4AukC4Lyqj6n/xg
Nvs8PfBjNaTLluIw==

Otisk zařízení, struktura fingerprint

Struktura fingerprint se v API používá na dvou místech:

• fingerprint struktura se vrací v response na init volání v případě, že vydavatel karty vyžaduje provedení otisku prohlížeče (actions.fingerprint.browserInit) nebo pokud je v rámci SDK potřeba provést jeho inicializaci (actions.fingerprint.sdkInit)
• fingerprint struktura se posílá v požadavku na process volání. Jedná se o dodatečná data pro ověření platby (obsahuje buď informace o browseru, pomocí kterého je platba prováděna nebo se jedná o parametry SDK pro autentizaci platby v rámci mobilní aplikace). Pokud je v operaci oneclick/init nastaveno clientInitiated = true, je vyplnění struktury fingerprint pro oneclick/process povinné. Pro applepay/process a googlepay/process je vyplnění struktury fingerprint povinné vždy.

V případě platby pomocí prohlížeče je na rozhodnutí vydavatele karty, zda se má provést otisk prohlížeče (je nutné jej provést pouze v případě, kdy se vrátí v response na init volání příslušná actions.fingerprint.browserInit). Přestože otisk prohlížeče není vydavatelem karty vyžadován, má obchodník povinnost zaslat potřebné údaje pro 3DS ověření v rámci požadavku na process volání. Dodatečná data pro ověření, tj. vyčtení potřebných proměnných (viz dokumentace) je tedy nutné provést obchodníkem na straně eshopu, získaná data následně použít pro naplnění fingerprint.browser struktury v process volání).