Volání rozhraní eAPI

Pro vývoj a integraci řešení je testovací platební brána pro obchodníky dostupná na adrese https://iapi.iplatebnibrana.csob.cz/.

Migraci na produkční prostředí (po odsouhlasení řešení ze strany banky) lze provést výměnou testovacích klíčů za produkční a přesměrováním api na https://api.platebnibrana.csob.cz/.

Omezení autorizace v integračním prostředí

Aby nedošlo k nechtěné záměně integračního a produkčního prostředí, je v integračním prostředí omezena úspěšná autorizace plateb pouze na testovací karty. V integračním prostředí je autorizace plateb prováděna oproti simulátoru, nelze použít opravdové "živé" platební karty. Simulace zamítnutí platby v autorizaci podle CVC kódu zůstává nezměněna.

Toto omezení minimalizuje způsobené škody v případě, kdy se na "živém e-shopu" nechtěně přepne z produkčního prostředí zpět na integraci.

eAPI vychází z principů REST API, je dostupné přes HTTPS protokol, data jsou posílaná v JSON formátu. Jednotlivé operace jsou implementované pomocí následujících HTTP metod:

Metoda volání	Popis
POST	vytvoření platby
GET	získání aktuálního stavu platby
PUT	změna stavu platby

V odpovědích na volání operací eAPI jsou použity následující HTTP status kódy:

Hodnota	Význam	Popis
200	OK	požadavek byl zpracován
400	Bad Request	požadavek nemůže být vyřízen
401	Unauthorized	požadavek nemůže být ověřen
403	Forbidden	přístup odepřen
404	Not Found	zdroj nebyl nalezen
405	Method Not Allowed	požadovaná metoda není podporována
429	Too Many Requests	příliš mnoho požadavků
500	Internal Server Error	interní chyba platební brány
503	Service Unavailable	služba je dočasně mimo provoz

Platební brána rozlišuje dva základní typy odpovědí:

HTTP response kód 200 v odpovědi značí úspěšně zpracovaný požadavek, v odpovědi je vrácen Content-Type application/json a jsou vyplněny všechny povinné parametry uvedené ve specifikaci dané operace. Pro tento typ je odpověď vždy podepsána.

Příklad odpovědi operace payment/init (povinné parametry pro tuto operaci jsou payId, dttm, resultCode, resultMessage a signature)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
}

Všechny ostatní odpovědi s HTTP response kódem jiným než 200 značí chybové odpovědi. Je vrácen Content-Type application/json, přičemž jsou vyplněny pouze parametry resultCode (viz výčet) a resultMessage (upřesňující text popisující danou chybu, text se může lišit od defaultního textu uvedeného v číselníku návratových kódů). Odpověď s HTTP response kódem jiným než 200 není podepsána.

To, jaký HTTP response kód se vrátí, záleží na typu chyby:

V případě chybějících anebo nevalidních parametrů merchantId, signature je vrácen http status code 401 Unauthorized.

Příklady odpovědí:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ 
  "resultCode": 100,
  "resultMessage": "Missing parameter merchantId"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 100,
  "resultMessage": "Missing parameter signature"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid parameter merchantId M1MIPS0000"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Merchant key not found for merchantId M1MIPS0000"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Wrong signature"
}

V případě chybějícího anebo nevalidního parametru dttm nebo v případě, že obchodník je v systémech banky deaktivován nebo nemá povolenou danou operaci, je vrácen http status code 403 Forbidden.

Příklady odpovědí:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 100,
  "resultMessage": "Missing parameter dttm"
}

Formát parameteru dttm je yyyyMMddHHmmss. V případě nevalidního formátu vrací platební brána odpověď:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid format of dttm parameter"
}

 

U požadavku vyplňujte vždy aktuální datum a čas odpovídající časové zóně CET / CEST, platební brána kontroluje předávanou hodnotu a toleruje určitou odchylku (řádově v minutách) v porovnání s aktuálním časem synchronizovaným na serverech platební brány. V případě chybné hodnoty je vrácena následující odpověď:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid dttm, accepting only current, received 20211229101112"
}

V případě, že obchodník je v systémech banky deaktivován, je vrácena odpověď:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 120,
  "resultMessage":"Merchant blocked"
}

V případě, že obchodník nemá povolenou danou operaci, je vrácena odpověď:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 180,
  "resultMessage": "Operation not allowed"
}

V případě chybějících nebo nevalidních parametrů je vrácen http status code 400 Bad request. V tomto případě provádí platební brána validaci ostatních parametrů z požadavku (jedná se o validaci zbylých parametrů mimo výše uvedené "základní" parametry merchantId, dttm a signature).

Příklady odpovědí:

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "resultCode": 100,
  "resultMessage": "Missing parameter totalAmount"
}

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid parameter totalAmount, received -100"
}

V případě výskytu interní chyby při zpracování požadavku je vrácen http status code 500 Internal Server Error.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "resultCode": 900,
  "resultMessage": "Internal error"
}

V případě nedostupnosti (např. v rámci plánované odstávky) je vrácen http status code 503 Service Unavailable.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "resultCode": 900,
  "resultMessage": "Request rejected"
}

Pro init metody platí, že založená platba může být v rámci initu rovnou zamítnuta. Poté, co se úspěšně dokončí validace parametrů z požadavku a platba se založí (je přiděleno a vráceno payId), pokračuje se v provádění následných kontrol, které zpravidla souvisejí s nastavením obchodníka, případně s dostupností externích systémů. Pokud není možné tento proces dokončit, změní se stav platby na 6 - Platba zamítnuta. V takovémto případě se vrací HTTP response kód 200, odpověď je podepsána, jsou vyplněny všechny povinné parametry pro danou operaci a vrácené parametry resultCode a resultMessage obsahují důvod zamítnutí:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131601",
  "resultCode": 110,
  "resultMessage":"Currency parameter USD not allowed",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Číselník návratových kódů  

resultCode	resultMessage
0	OK (operace proběhla korektně, transakce založena, stav aktualizován apod.)
100	Missing parameter {name} (chybějící povinný parametr)
110	Invalid parameter {name} (chybný formát parametru)
120	Merchant blocked (obchodník nemá povoleny platby)
130	Session expired (vypršela platnost požadavku)
140	Payment not found (platba nenalezena)
150	Payment not in valid state (nesprávný stav platby, operaci nelze provést)
160	Payment method disabled (operace není povolena, obchodník si o nastavení musí smluvně zažádat)
170	Payment method unavailable (nedostupnost poskytovatele metody, služba není v tomto čase dosažitelná)
180	Operation not allowed (nepovolená operace)
190	Payment method error (chyba ve zpracování u poskytovatele metody)
200	Duplicate purchaseId (duplicitní purchaseId pro NEJsplátku)
230	Merchant not onboarded for MasterPass (obchodník není registrovaný v MasterPass), deprecated
240	MasterPass request token already initialized (MasterPass token byl již inicializován), deprecated
250	MasterPass request token does not exist (nenalezen MasterPass token, nelze dokončit platbu pomocí MasterPass), deprecated
270	MasterPass canceled by user (zákazník nedokončil výběr karty/adresy v MasterPass wallet), deprecated
500	EET Rejected (EET hlášení bylo odmítnuto FS)
600	mallpay payment declined in precheck (operaci mallpay/init nelze dokončit z důvodu zamítnutí žádosti v systému mallpay)
700	Oneclick template not found (OneClick šablona nebyla nalezena)
710	Oneclick template payment expired (OneClick šablona nebyla použita více jak 13 měsíců, platba expirovala)
720	Oneclick template card expired (karta pro OneClick šablonu expirovala)
730	Oneclick template customer rejected (OneClick šablona byla zrušena na pokyn zákazníka)
740	Oneclick template payment reversed (OneClick šablona byla reverzována)
750	Cardholder account closed (Zrušení OneClick šablony z důvodu uzavření účtu držitele karty)
800	Customer not found (zákazník identifikovaný pomocí customerId nenalezen)
810	Customer found, no saved card(s) (zákazník identifikovaný pomocí customerId byl nalezen, ale nemá žádné dříve uložené karty na platební bráně)
820	Customer found, found saved card(s) (zákazník identifikovaný pomocí customerId byl nalezen a má uložené karty na platební bráně)
900	Internal error (interní chyba ve zpracování požadavku)