⚠️ Verzi eAPI 1.6 platební brána stále podporuje, nicméně doporučujeme používat nejnovější verzi 1.9. Přehled funkcí v jednotlivých verzích eAPI platební brány najdete v přehledové tabulce.

Platební brána ČSOB zpracovává transakce z e-shopů pomocí API, které má dvě klíčové funkce. Slouží k provedení platby klienta na vašem e-shopu (případně v mobilní aplikaci) a současně umožňuje i následně řídit životní cyklus platby, realizovat vratky v případě reklamace zboží apod. Komunikace mezi vaším e-shopem a platební bránou je zabezpečena pomocí elektronických podpisů všech požadavků i odpovědí.

Tato dokumentace popisuje způsob integrace platební brány do prostředí e-shopu jak pro platby klientů, tak jejich následnou správu. Součástí integrace je implementace API do prostředí vašeho e-shopu a zprovoznění zabezpečené komunikace, tedy vygenerování certifikátů a jejich výměna s bankou.

V nové verzi eAPI 1.6 byla doplněna platební metoda Platba na klik. Jedná se o přejmenování a vylepšení původní "opakované platby", která je v eAPI 1.5 dostupná pomocí operace payment/recurrent. Platba na klik umožňuje rychlejší platbu klientům, kteří již dříve v e-shopu nakupovali a dali souhlas s uložením karty. V anglosaském prostředí je známá často jako "card on file". Pro platbu na klik je doplněn její popis a popis souvisejících nových operací payment/oneclick/init a payment/oneclick/start

Koncept API rozšíření (extensions)

Od eAPI v1.6 byl doplněn koncept API rozšíření - přinášejí nové funkcionality bez vlivu na základní konstrukci API volání a lze je přidávat jednodušším způsobem, protože nemají vliv na výpočet podpisu volání.

Obecný popis rozšíření

eAPI 1.6 extension - datum vytvoření, autorizace a zúčtování transakce

Maskované číslo karty + expirace pro prvotní trx platby na klik

• [17.05.2016] doplněno eAPI rozšíření Maskované číslo karty + expirace pro prvotní trx platby na klik
• [27.06.2016] povolené hodnoty parametru currency v operaci payment/init a payment/oneclick/init doplněny o hodnotu HUF a PLN
• [27.01.2017] doplněn nový návratový kód 500, EET rejected, viz seznam
• [1.8.2017] doplněna podpora pro akceptaci nové měny HRK a nové lokalizace HR a SI

3D Secure - standard asociací Visa a MasterCard, vystupující pod komerčními názvy MasterCard SecureCode a Verified by Visa. Zajištuje vyšší bezpečnost online plateb kartami.

3D Secure na straně vydavatele karty - ověření platby u vydavatele karty, probíhá po přesměrování z platební brány na webové stránky vydavatele karty. Samotné ověření probíhá v prostředí České republiky nejčastěji formou zadání SMS kódu, zaslaného na kontaktní telefon držitele karty. Může nicméně probíhat i jinými způsoby. Ne všechny karty podporují 3D Secure na straně vydavatele - rozdíly nicméně obchodníkovi plně řeší platební brána a zpracování platby je z pohledu obchodníka shodné.

3D Secure na straně platební brány - zabezpečení platby v podobě zadávání citlivých platebních údajů držitelem karty nikoli obchodníkovi, ale přímo do webové stránky banky obchodníka. Tímto způsobem zadávání údajů zabraňuje 3D Secure standard zneužití citlivých platebních údajů obchodníkem.

API - rozhraní mezi platební bránou a e-shopem, specifikované touto dokumentací

Banka - Československá obchodní banka, a.s., provozovatel služeb platební brány na https://platebnibrana.csob.cz

Banka obchodníka - viz banka

Banka plátce - viz vydavatel karty

Držitel karty - viz plátce

e-shop - elektronický obchod provozovaný prostřednictvím WWW stránek nebo mobilní aplikace

Karta - platební nástroj používaný plátcem, souhrnné označení pro kreditní, debetní, předplacené a charge karty

Košík - všechny položky nákupu, kde součet cen položek včetně aplikovatelné DPH odpovídá hodnotě transakce

Obchodník - provozovatel e-shopu, příjemce plateb od plátců

Objednávka - objednávka a její interní označení v e-shopu, skládající se z položek košíku. Objednávka vzniká potvrzením košíku ze strany plátce. Jednou z možností, jak může být objednávka plátcem uhrazena, je transakcí na platební bráně. Objednávka je plně řízena e-shopem, stejně jako přiřazení transakce objednávce. Řízením objednávky na straně e-shopu se rozumí i změny stavu objednávky dle stavů transakce na platební bráně.

PCI DSS - Payment Card Industry Data Security Standard (více na www.pcistandard.cz)

Platba - viz transakce

Plátce - uživatel, který provedl nákup na e-shopu, uzavřel objednávku a chce ji zaplatit kartou

POS Merchant - systém banky pro správu transakcí personálem obchodníka

Stav transakce - jednoznačný status transakce v rámci jejího životního cyklu, definovaný platební bránou a v každý okamžik zjistitelný pro obchodníka pomocí API

Transakce - při výběru zaplacení objednávky kartou vzniká přesměrováním plátce na platební bránu. Transakce je jednoznačně identifikována a řízena platební bránou v rámci definovaných stavů.

Transakce platební brány - viz transakce.

Vydavatel karty - banka nebo jiná finanční instituce, která vede účet držitele karty, zajištuje zúčtování transakcí a během transakce provádí ověření držitele karty v rámci 3D Secure na straně vydavatele

Zákazník e-shopu - viz plátce

Z pohledu plátce e-shopu se platba odehrává standardním způsobem, na který je zvyklý u obdobných řešení využívaných bankami v České republice. Po dokončení nákupu proběhne z e-shopu přesměrování na platební bránu, kde plátce vyplní údaje karty a potvrdí platbu. Pokud má u své karty nastaveno 3D Secure ověření, je přesměrován na stránku své banky, kde provede ověření. V českém prostředí toto ověření probíhá nejčastěji pomocí SMS zprávy, kterou banka zašle plátci na jeho mobilní telefon a plátce tento kód přepisuje do ověřovacího formuláře. Následně proběhne platba, plátce je informován o jejím výsledku a přesměrován zpět do e-shopu.

Pod pokličkou se ovšem odehrává mnohem více událostí, které plátce nevidí. Jednotlivé operace odehrávající se na pozadí zachycuje následující obrázek. Dále projdeme jednotlivé kroky platebního procesu, popíšeme si data předávaná mezi jednotlivými systémy a probereme události odehrávající se uvnitř.

Diagram ukazuje provedení platby ze strany plátce a předpokládá, že dojde k úspěšnému obchodu a odeslání zboží e-shopem. Pokud dojde ke komplikacím, změnám či zrušení objednávky ze strany plátce či obchodníka, je v dalším procesu k dispozici rozhraní umožňující správu platby a její dodatečně zrušení. To si ale probereme až v dále popsané sekci správa stavu transakce.

Transakce platby prochází několika kroky, které ovlivňuje obchodník, plátce a stav platební karty. Celý životní cyklus od založení platby po její dokončení a možné následné stavy na popud obchodníka ukazuje diagram níže, popíšeme si je detailně:

1) Platba založena je úvodní stav po volání metody payment/init. Po úspěšném založení se vyčkává na přesměrování plátce z e-shopu na stránku platební brány. Pokud založení transakce nelze provést, například z důvodu chyby ve vstupních datech nebo nepovolené operace daného obchodníka, požadavek spadne do stavu 6) Platba zamítnuta.

2) Platba probíhá po přesměrování plátce na stránku platební brány se transakce přepne do stavu probíhající platby. Na pozadí probíhající platby se odehrává mnoho kroků od ověření parametrů přes zjištění zda karta patří do 3D ověření, jeho samotný průběh u vydavatelské banky a následné provedení platby kartou. Tyto kroky jsou pro obchodníka skryty za průběhem platby, zajímá ho až samotná výsledek. Ten může být:

• 3) Platba zrušena - platba byla zrušena plátcem na platební bráně
• 6) Platba zamítnuta - zamítnuto bankou z důvodu nedostatku prostředků, nepotvrzení 3D ověření plátcem či jiného důvodu a nebo byl proces přerušen, např. protože plátce zavřel prohlížeč
• 4) Platba potvrzena - platba byla provedena a čeká až ji obchodník zařadí do zúčtování. Do tohoto stavu se úspěšná platba dostane, pokud je automatické zařazení do zúčtování vypnuto.
• 7) Čekání na zúčtování - platba byla provedena a automaticky zařazena do zúčtování

3) Platba zrušena   Tento stav nastane, pokud plátce na stránce platební brány klikne na tlačítko zrušit. Plátce se vrací automaticky do e-shopu (platební brána jej přesměruje) a z pohledu životního cyklu transakce je tento stav koncový. Chce-li plátce znovu tu samou objednávku v e-shopu zaplatit opět kartou, e-shop musí vygenerovat zcela nový platební požadavek.

4) Platba potvrzena   Tento stav nastane po úspěšném provedení transakce v případě, že je automatické zařazení do zúčtování vypnuto. Již v založení platby říkáme, zda chceme transakci ihned po potvrzení automaticky poslat do zúčtování a převést tak peníze na účet obchodníka, nebo zda necháme autorizovanou transakci čekat např. až připravíme zboží a teprve po odeslání zboží pošleme transakci do zúčtování.

V tomto stavu je možné ponechat platbu maximálně po dobu sedmi dní, kdy je platba ze strany banky garantována a na kartě plátce jsou prostředky blokovány. POZOR! Po uplynutí této doby již není možné transakci zařadit do zúčtování! (platba je odvolána, prostředky na kartě plátce jsou systémem automaticky odblokovány a banka platbu již negarantuje).

5) Platba odvolána Dokud neprojde potvrzená platba zúčtováním, lze ji odvolat. To znamená, že nebude vůbec držiteli karty účtována, blokované prostředky na kartě se uvolní a neplatí se žádný poplatek. Tento stav je koncový a nelze jej vrátit. Počet odvolaných plateb obchodníkem je bankou monitorován.

Spoléhat na možnost odvolání platby lze pouze u transakcí, které dosud nebyly zúčtovány. Odvolat platbu lze u transakcí ve stavu „Platba potvrzena“ (4) do té doby dokud nebude zařazena do zúčtování a neproběhne samotné zúčtování. U transakcí ve stavu „Čekání na zúčtování“ (7) lze odvolat platbu maximálně do půlnoci daného dne, po této době se provádí zúčtování transakcí, u zúčtovanou platby lze již jen provést operaci vrácení prostředků.

6) Platba zamítnuta   Tento stav byl již popsán výše, důvodů zamítnutí platby je více a jsou detailně rozlišeny v návratovém kódu operace. Principielně je lze řadit do několika skupin:

• Inicializace platby obsahovala chybná data
• Obchodník nemá povolenu platební operaci
• Plátce neprovedl správně 3D ověření
• Banka plátce (vydavatel karty) nepovolila platbu kartou
• Plátce zavřel prohlížeč a transakce vypršela

Specifickým stavem je zamítnutí platby ze strany banky. Teprve návratový kód upřesňuje, z jakého důvodu banka vydavatele karty transakci zamítla. Z pohledu obchodníka jde však o neúspěšnou platbu a tento detail je pouze informativní.

Platební brána v případě neúspěchu platby kartou plátce ihned neodsoudí k neúspěchu, ale sama mu znovu nabídne možnost platit jinou kartou. Tím se sníží skupina plátců, které neúspěch a návrat do e-shopu odradí. Z pohledu obchodníka je takováto "transakce napodruhé" po celou dobu ve stavu Platba probíhá a až výsledný úspěch či neúspěch ji přesune do příslušného stavu.

7) Čekání na zúčtování   je stav, kdy jsou transakce již řazeny do fronty a dle nastavení zúčtovacích pravidel banky zpracovávány. Dokud transakce není zúčtována, lze ji stále odvolat. Tento postup již byl popsán výše.

8) Platba zúčtována je pro obchodníka ten správný koncový stav. Vše proběhlo, transakce byla zařazena do zúčtování, toto provedeno a peníze budou na cestě. Tento stav je sice koncový, nicméně pokud se obchodník rozhodne transakci zrušit (např. zákazník objednávku zruší, nebo zboží vrátí v zákonné lhůtě) může na nad touto transakcí vyvolat operací vrácení prostředků.

9) Zpracování vrácení Pokud obchodník přesto zažádá o zpracování transakce vrácení prostředků, přesune se existující transakce do tohoto stavu a operace probíhá. Zpracování vrácení je v bance schvalováno na základě podkladů dodaných obchodníkem bance, proto může tento stav trvat i několik dní.

10) Platba vrácena Sem se dostává životní cyklus transakce po schválení jejího vrácení a reálném provedení transakce opačným směrem k původnímu plátci.

Založení platby payment/init V okamžiku, kdy je na e-shopu iniciována koncová fáze nákupu, přechází se k platbě a je vybrána metoda platby kartou, e-shop zakládá platbu na platební bráně. Kromě standardních údajů, jako je vlastní identifikace obchodníka, částka a referenční číslo objednávky, může e-shop zaslat do platební brány také detail nákupu včetně položek košíku. Tím se výrazně zpřehlední platební proces a zvýší důvěra zákazníka v korektní průběh operací na e-shopu a platební bráně.

Referenční číslo objednávky přiděluje e-shop obchodníka. Ve výsledku se referenční číslo objednávky objeví na výpisu transakcí z banky. Použije se tedy v systému obchodníka (účetnictví) pro párování plateb e-shopu proti bankovnímu účtu a musí tedy splňovat podmínku variabilního symbolu - numerickou hodnotu o maximálně deseti místech. V aplikaci POSMerchant je referenční číslo objednávky zobrazeno ve sloupci Variabilní symbol.

Po založení platby přiřadí platební brána každé transakci jednoznačné ID platby payId. Tento identifikátor se vrací v odpovědi na payment/init a nese se s celou platební transakcí ve všech stavech.

Číslo objednávky, které obchodník předává platební bráně při založení platby, musí být v rámci jeho e-shopu unikátní. V případě, že obchodník založí na platební bráně dvě transakce se stejným číslem objednávky, mají tyto transakce sice odlišné payId, ale na výpise z banky se objeví jako dvě platby se stejným variabilním symbolem.

Pokud je zákazník na e-shopu přihlášen a jeho identita je známá, je možné předat také jednoznačný identifikátor zákazníka. To umožní, aby si zákazník na bráně svou platební kartu bezpečně uložil a při následných návštěvách tohoto e-shopu ji mohl znovu použít bez opisování dlouhého čísla karty.

Přesměrování na bránu payment/process Pokud je platba na bráně úspěšně založena, může v následných krocích e-shop přesměrovat plátce na bránu. V odkaze předává pouze svůj jednoznačný identifikátor této platby, všechna ostatní data platební operace, stejně jako obsah košíku a identita obchodníka, jsou již na bráně připraveny během kroku Založení platby.

Operaci přesměrování na bránu je potřeba použít v případě, že zákazník opakovaně přechází tam a zpět mezi e-shopem a platební bránou (např. pomocí navigace v prohlížeči). Pro jednou založenou platbu s již nastaveným číslem objednávky, kdy tato platba má na platební bráně přidělené unikátní payId nelze volat znovu operaci založení platby se stejným číslem objednávky -- vznikla by nová platba s duplicitním číslem objednávky.

Zjištění stavu platby payment/status Systém e-shopu může kdykoli zjistit stav kterékoli své platby na platební bráně. Zavoláním této metody dostává zpět informaci, zda platba probíhá, případně ve kterém kroku se nachází a po dokončení platby pak informaci s jakým výsledkem byla platba dokončena.

Toto volání je nepovinné, u jednodušších implementací e-shopu nemusí být použito a čeká se pouze na návrat plátce zpět jeho přesměrováním na návratovou URL e-shopu.

Jak jsme si výše řekli, stav transakce může e-shop ověřit po jejím skončení. Transakce je držena v aktivní části brány následujících 48 hodin po jejím provedení. Pokud plátce, třeba omylem, vyvolá z historie prohlížeče opět platební bránu, nedojde k žádným komplikacím. bude mu zobrazena korektní potvrzovací stránka platební brány s informací, jak tato platba dopadla.

Jak vyplývá z výše popsaného životního cyklu transakce, po jejím úspěšném dokončení je ještě několik kroků, kterými může obchodník řídit její stav:

Odvolání transakce payment/reverse Metoda odvolá úspěšně autorizovanou transakci a vyřadí ji ze systému, transakce nebude provedena a prostředky na kartě plátce se uvolní. Metodu lze použít pouze pro nezaúčtované transakce. Je nutno počítat s tím, že při volání metody ve stavu 7) Čekání na zúčtování může dojít ke zpracování zúčtování transakce, metoda vrátí chybu a transakce již bude proplacena.

Zařazení transakce do zúčtování payment/close Tuto operaci voláme pouze v případě, že v založení platby máme vypnuto její automatické zařazení do zúčtování. Volání této funkce zařadí transakci do zúčtování a může být v e-shopu například spojena s okamžikem odeslání zboží.

Žádost o vrácení transakce payment/refund Tuto operaci voláme v případě, že je třeba vrátit prostředky zpět plátci. Příkladem je třeba reklamace zboží, zrušení objednávky nebo odstoupení od koupě na e-shopu v zákonné lhůtě. Nově od eAPI v1.5 lze provést tzv. částečný refund, vrácená částka je menší než původní autorizovaná částka.

Kontrola brány echo Metoda pouze profoukne bránu a ověří vzájemnou funkčnost a korektnost podpisů obou stran. V odpovědi vrací čas systému na bráně.

Kontrola zákazníka customer/info Pokud je plátce na e-shopu přihlášen a jeho identita je známá, může si při platbě na bráně uložit své karty pro příští návštěvu e-shopu. Tato metoda umožní obchodníkovi zjistit, zda je pro bránu tento plátce známý a má uloženou nějakou kartu. Žádné další detaily však z důvodu bezpečnosti brána neposkytuje. Funkci lze využít např. pro propagaci platby uloženou kartou.

eCommerce se pohybuje ve světě otevřeného internetu, proto je nutné data putující mezi systémy e-shopu a platební bránou zabezpečit proti útokům zvenčí. Komunikační kanál je zabezpečen protokolem SSL, pro ověření autenticity obchodníka jsou však navíc všechny požadavky odesílané na platební bránu podepsané jeho privátním klíčem.

Platební brána má k dispozici veřejnou část klíče, pomocí které může ověřit, že požadavek vygeneroval právě tento obchodník. Pro správnou funkčnost je tedy třeba vygenerovat tento pár privátní klíč + veřejný klíč, privátní část si předat do systému obchodníka (e-shopu, backoffice apod.) a veřejnou část předat platební bráně, tedy bance. Tento proces je součástí integrace obchodníka a platební brány.

První fáze integrace následuje po sjednání poskytování služeb eCommerce v bance, kde obdržel obchodník své MerchantID a uvedl, ze které emailové adresy bude s bankou komunikovat. V tomto okamžiku již jeho identita v systému platební brány existuje a vyčkává na další kroky takto:

Generování testovacích klíčů Prostředky pro generování testovacích klíčů jsou dostupné na stránkách banky. Generátor pracuje tak, že přímo na stránce se do počítače obchodníka stáhne JavaScriptová aplikace obsahující generátor klíčů. Průvodce tohoto generátoru pak provede následující kroky:

1. Vyžádá od plátce jeho MerchantID a registrovanou eMailovou adresu
2. Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
3. Nabídne pouze možnost generování testovacích klíčů
4. Lokálně vygeneruje testovací pár klíčů private key/public key
5. Privátní část private key uloží do souboru v počítači obchodníka
6. Veřejnou část odešle zabezpečeným kanálem na platební bránu

Integrace V tomto okamžiku může obchodník spustit integraci svého řešení (e-shopu) s platební bránou. Privátní klíč předá vývoji, který může vyvíjet a testovat proti veřejné iBráně. Jeho klíč je tam automaticky zaveden ihned po vygenerování.

Integrační prostředí (iBrána)

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.

V tomto prostředí je 3DS autentizace a vlastní autorizace plateb prováděna oproti simulátoru, nicméně samotná funkcionalita platební brány včetně eAPI a uživatelského rozhraní je identická s produkčním prostředím. Obchodník tak může otestovat nejenom vlastní přechod z eshopu na platební bránu a zpět (předávání parametrů) 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.

Schválení Jakmile je integrace dokončena, obchodník o této skutečnosti informuje banku a provede sérii předepsaných testů. Banka ověří jejich výsledky oproti záznamům testovací iBrány a v pozitivním případě obchodníka aktivuje.

Generování ostrých klíčů V tomto okamžiku může obchodník vygenerovat nové, ostré klíče, které použije pro provozní prostředí. Použije generátor produkčních klíčů dostupný na stránkách banky , který bude pracovat následovně:

1. Vyžádá od plátce jeho MerchantID a registrovanou eMailovou adresu
2. Zkontroluje na platební bráně, zda je obchodník registrován a v jaké fázi se nachází
3. Zjistí, že obchodník je aktivován a má splněny integrační testy
4. Lokálně vygeneruje ostrý pár klíčů private key/public key
5. Privátní část private key uloží do souboru v počítači obchodníka
6. Veřejnou část odešle zabezpečeným kanálem kanálem na platební bránu
7. Platební brána odešle na registrovanou adresu obchodníka aktivační kód

Potvrzení ostrého klíče obchodníkem Pro vyšší bezpečnost, ale také pro případ, kdy za běhu systému potřebuje obchodník svůj klíč vyměnit, je zde ještě jeden krok oproti testovacímu prostředí:

Obchodník má přístup do systému PosMerchant, kde se mu jeho nově vygenerovaný klíč objeví v částí eCommerce. Teprve zde jej potvrdí a zaktivuje. K této operaci je třeba jednorázový aktivační kód, který při převzetí veřejné části klíče odeslala brána na email obchodníka. Okamžikem této aktivace se klíč přenese na platební pránu a ta jej ihned začne používat. Tímto krokem je jednak dvojitě zabezpečeno předání klíče a současně obchodník sám určuje okamžik jeho zavedení na platební bránu.

Pískoviště

Systém umožňuje implementaci API rozhraní a přípravu na integraci e-shopu ještě před návštěvou banky a bez jakýchkoli závazků. Tomuto postupu říkáme nultá fáze, pískoviště - na kterém si můžete s bránou hrát (a nezlobit). Lze tedy nejdříve zapojit vývoj, ověřit funkčnost napojení a teprve pak přejít do první fáze, navštívit banku a s obdrženým merchantID se napojit na testovací prostředí.

Ve skutečnosti ale probíhá stejně, jako první fáze. V průvodci generováním klíčů na adrese https://iplatebnibrana.csob.cz/keygen se však vybere možnost Anonymní vývoj (nevyplňuje se merchantID ani email) a průvodce následně zažádá platební bránu o přidělení vývojového merchantID. K tomuto merchantID pak obchodník vygeneruje na svém lokálním počítači klíče, veřejnou část přenese na platební bránu a privátní uloží do souboru.

Testovací přístup pro anonymní vývoj je platný jeden měsíc, stejně jako testovací klíče. Přístupy jeho prostřednictvím jsou monitorovány a v případě zatížení neúměrného vývoji a testování mohou být služby pro toto merchantID omezeny.

Platbou na klik rozumíme možnost automatizovaně provést platbu bez přesměrování držitele karty na platební bránu a bez zadávání platebních údajů, přičemž potřebné údaje jsou převzaty z dříve provedené autorizované platby. Tato funkce je určena pro pohodlnou platbu při následných nákupech klienta v e-shopu nebo v aplikaci. Klient musí být v e-shopu registrován, aby byl e-shop schopen předat při následujících transakcích potřebné údaje. Veškerá volání mezi e-shopem a bránou probíhají backendově, tj. z pohledu klienta se opravdu jedná o platbu "na jedno kliknutí".

Funkce Platby na klik není přístupná univerzálně, musí být ze strany ČSOB pro konkrétního obchodníka povolena.

Celý proces obsahuje nejprve zpracování klasické platby:

• obchodník pošle při založení platby v rámci operace payment/init v parametru payOperation hodnotu oneclickPayment (platba je na bráně označena jako šablona pro platby)
• platba dále probíhá klasickým způsobem, tzn. plátce je z eshopu obchodníka přesměrován na platební bránu pomocí operace payment/process, na platební bráně zadá potřebné údaje pro vlastní platbu (číslo karty, expiraci a CVC kód), po dokončení autorizace je plátce přesměrován z platební brány zpět na eshop.

Platbu na klik provede obchodník následovně:

• obchodník volá na eAPI nejprve operaci payment/oneclick/init. V parametrech odkazuje na dříve provedenou platbu, která byla označena jako šablona pro platby, tato platba musí být úspěšně autorizována.
• v rámci operace payment/oneclick/init se nejprve ověří vstupní parametry, transakci se přidělí unikátní payId, které se vrátí v odpovědi zpět obchodníkovi
• pro spuštění vlastní autorizace volá obchodník na eAPI operaci payment/oneclick/start. Jako jeden ze vstupních parametrů předává payId platby na klik přidělené v předchozím kroku. Platební brána provede načtení potřebných údajů z dříve provedené platby včetně čísla karty a expirace a požadavek se posílá do autorizace.
• výsledek autorizace obchodník ověří pomocí volání payment/status

Přečtěte si, prosím, také obecný článek, ve kterém se dočtete o pravidlech (banky a karetních asociací), které je třeba dodržet. Připravili jsme pro vás i několik doporučení jak platbu na klik nejlépe implementovat.

Upozornění: vzhledem k charakteru platby na klik se vlastní zpracování následných plateb provádí bez interakce s plátcem / držitelem karty, tzn. probíhá bez zadávání CVC kódu a bez 3DS ověření.

Poznámka: platební brána rozlišuje mezi platbou dříve uloženou kartou a platbou na klik. Platba dříve uloženou kartou zjednodušuje plátci zadávání platebních údajů v rozhraní platební brány, přičemž je vyžadováno a zadávání CVC kódu a 3DS ověření, zatímco platba na klik umožňuje automatizovaný způsob provádění plateb pro obchodníka bez nutnosti interakce s držitelem karty.

Od eAPI v1.5 byla přidána možnost uzavřít transakci na menší částku než na jakou byla původně autorizovaná.

Z pohledu business procesu nově tedy eAPI umožňuje autorizovat a následně uzavřít na menší částku. Ať už z důvodu, že obchodník nemůže část zboží dodat, nebo že konečná cena nákupu vzniká až poté, co zákazník opustil e-shop. Obchodník nicméně tento okamžik umí předvídat - nezavře při inicializaci transakce automaticky pomocí "closePayment": true, je nicméně schopen uzavřít transakci později na jeden pokus.

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í pak, 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 eshopu" 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:

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

Při zpracování požadavku jsou nejprve kontrolovány základní parametry a ověřen podpis požadavku. V případě chyby při této základní kontrole obsahuje odpověd z hlediska bezpečnosti pouze obecný HTTP status kód (např. 400 Bad Request nebo 403 Forbidden).

Tučně uvedené parametry jsou pro volání povinné

Upozornění: pokud je payOperation nastavena na oneclickPayment, ignoruje se předávaný parametr customerId. Při zpracování šablony pro platbu tedy lze zadat v rozhraní platební brány pouze novou kartu, nelze platit dříve uloženou kartou.

item - Položka košíku (objekt cart)  

Položky jsou uváděny po řádcích. Každý řádek košíku má název položky, počet ks, celkovou cenu za uvedený počet ks položky a nepovinný pomocný popis.

Pozn: pokud je amount=0, zobrazení obsahu košíku na platební bráně uvádí text ZDARMA

POZOR: Od verze v1 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é"). Omezení je dáno grafickou úpravou platební brány a v další verzi bude limit položek výrazně posunut.

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.6/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20140425131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Nákup: vasobchod.cz",
      "quantity": 1,
      "amount": 1789600,
      "description":"Lenovo ThinkPad Edge E540"
    },
    {
      "name": "Poštovné",
      "quantity": 1,
      "amount": 0,
      "description": "Doprava PPL"
    }
  ],
  "description":"Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)",
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"CZ",
  "signature":"base64-encoded-signature-of-payment-request"
}'

eAPI vrací pro operace payment/init, payment/status, payment/close, payment/reverse a payment/refund jednotnou sadu parametrů popisujících aktuální stav platebního požadavku, výsledek operace (kód a textový popis), a případně autorizační kód pro úspěšně autorizované požadavky. U jednotlivých volání funkcí jsou již uvedeny pouze příklady návratových hodnot s odkazem na tuto společnou definici.

Příklad návratových hodnot pro payment/init -- úspěšně založená transakce:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro payment/init -- chybně založená transakce:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 100,
  "resultMessage":"Missing parameter 'totalAmount'",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Požadavek obsahuje položky přímo v URL adrese https://api.platebnibrana.csob.cz/api/v1.6/payment/process/{merchantId}/{payId}/{dttm}/{signature}

Přesměrování na platební bránu po předchozí inicializaci platby. Na rozdíl od ostatních operací eAPI (které se mohou odesílat pomocí jakéhokoli http klienta ze systému obchodníka a vrací návratové hodnoty ve formátu JSON) se v případě této operace musí GET požadavek odeslat z prohlížeče plátce, výsledkem je stránka platební brány.

Příklad volání:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.6/payment/process/012345/d165e3c4b624fBD/20140425131559/base64-encoded-request-signature

Server vrací přesměrování na stránku platební brány pro zobrazení výsledku zpracování požadavku ...

HTTP/1.1 303 See Other
Location: https://platebnibrana.csob.cz/pay/vasobchod.cz/6544-4564-sd65111-GF544DS/

V případě korektního zpracování se zobrazí stránka platební brány pro zadání potřebných údajů pro zaplacení, v případě chyby při zpracování (neplatné parametry, chybný podpis požadavku, platba neexistuje apod.) se zobrazí stránka platební brány s popisem chyby.

V tomto místě je vhodné upřesnit, jaké parametry bude obsahovat přesměrování z platební brány zpět na e-shop.

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init doplněné o parametr merchantData. Jsou předány na návratovou adresu e-shopu (parametr returnUrl získaný v payment/init) a to přes prohlížeč plátce pomocí metody POST nebo GET (parametr returnMethod) .

Poznámka: eShop musí od v1.5 podporovat zpracování návratovych hodnot pomocí metody GET i POST (platební brána provadí redirect podle parametru returnMethod, u některých akcí -- např. zrušení platby uživatelem -- nicméně provede vždy redirect pomocí GET metody).

Příklad návratových hodnot při přesměrování z platební brány na e-shop pomocí metody POST:

Http-Method: POST
Address: https://vasobchod.cz/gateway-return
Payload:
payId=d165e3c4b624fBD&dttm=20140425131559&resultCode=0&resultMessage=OK&paymentStatus=4
&authCode=F7A23E&merchantData=base64-encoded-merchant-data&signature=base64-encoded-response-signature

Poznámka: parametry jsou předávané jako Form URL Encoded data posílané v těle POST požadavku

Příklad návratových hodnot při přesměrování z platební brány na e-shop pomocí metody GET:

Http-Method: GET
Address: https://vasobchod.cz/gateway-return?payId=d165e3c4b624fBD&dttm=20140425131559&resultCode=0&resultMessage=OK&paymentStatus=4
&authCode=F7A23E&merchantData=base64-encoded-merchant-data&signature=base64-encoded-response-signature

Poznámka: hodnoty parametrů jsou „URL enkódovány“.

Požadavek obsahuje položky přímo v URL adrese https://api.platebnibrana.csob.cz/api/v1.6/payment/status/{merchantId}/{payId}/{dttm}/{signature}

Příklad volání:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.6/payment/status/012345/d165e3c4b624fBD/20140425131559/base64-encoded-request-signature

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/status:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 4,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

Operace reversuje (zruší před odesláním do uzávěrky) již autorizovanou transakci. Při zavolání této funkce na transakci, která již do uzávěrky odešla se vrací chyba. V takovém případě je pro zrušení transakce potřeba zadat žádost o vrácení prostředků.

Příklad volání:

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.6/payment/reverse \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/reverse:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 5,
  "signature":"base64-encoded-response-signature"
 }

Operace zařadí transakci do zúčtování.

Update 14.11.2015: V operaci payment/close byl přidán nový nepovinný parametr totalAmount (uzavření transakce a zaúčtování na menší částku)

Příklad volání:

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.6/payment/close \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Příklad volání: (zaúčtování na menší částku)

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.6/payment/close \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "totalAmount":10000,
  "signature":"base64-encoded-request-signature"
}'

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/close:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

Voláním operace je zažádáno o návrat prostředků nazpět plátci. Aplikuje se na již zaúčtované transakce. Nově od eAPI v1.5 lze provést tzv. částečný refund vyplněním nepovinného parametru amount. Částečný refund lze provádět opakovaně, přičemž platí, že částka v parametru amount musí být menší než rozdíl původní autorizované částky a sumy doposud provedených (schválených) částečných refundů.

Příklad volání:

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.6/payment/refund \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Zpracování u této operace je asynchronní, parametr paymentStatus v návratových hodnotách proto obsahuje aktuální stav platebního požadavku (Platba zúčtována), stav platebního požadavku je možné sledovat přes payment/status.

Příklad návratových hodnot pro payment/refund:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 8,
  "signature":"base64-encoded-response-signature"
 }

Pomocná operace, která slouží pro ověření správnosti složeného podpisu požadavku a kontrolu podpisu odpovědi při vývoji aplikace. Operaci je možné volat pomocí metody POST (parametry poslány v těle požadavku ve formátu JSON) nebo pomocí metody GET -- požadavek obsahuje položky přímo v URL adrese : https://api.platebnibrana.csob.cz/api/v1.6/echo/{merchantId}/{dttm}/{signature}

Příklad volání pomocí metody POST:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.6/echo \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Příklad volání pomocí metody GET:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.6/echo/012345/20140425131559/base64-encoded-request-signature

Poznámka: hodnoty parametrů musí být „URL enkódovány“.

Příklad návratových hodnot pro echo:

{
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "signature":"base64-encoded-response-signature"
 }

Operace pro zjištění informace o uloženém zákazníkovi. Požadavek obsahuje položky přímo v URL adrese : https://api.platebnibrana.csob.cz/api/v1.6/customer/info/{merchantId}/{customerId}/{dttm}/{signature}

Příklad volání:

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.6/customer/info/012345/cust123%40mail.com/20140425131559/base64-encoded-request-signature

Poznámka: hodnoty parametrů musí být „URL enkódovány“.

Příklad návratových hodnot:

{
  "customerId":"[email protected]",
  "dttm":"20140425131559",
  "resultCode": 800,
  "resultMessage":"Customer not found",
  "signature":"base64-encoded-response-signature",
 }

Operace provede platbu na klik. Podmínkou je, že existuje autorizovaná platba (tzv. "šablona pro platbu"), která byla provedena na platební bráně standardním způsobem.

Poznámka: z šablony pro platbu se přebírá nastavení closePayment (příznak, zda se platba zařadí do zúčtování) a dále parametr merchantData.

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.6/payment/oneclick/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "origPayId":"ef08b6e9f2234BC",
  "orderNo":"5547123",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/oneclick/init -- úspěšně založená transakce:

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Příklad návratových hodnot pro payment/oneclick/init -- zamítnutá transakce (nevalidní vstupní parametry):

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 110,
  "resultMessage":"Invalid 'totalAmount' parameter, must be positive",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Operace nastartuje autorizaci platby na klik.

Poznámka: z šablony platbu se přebírá nastavení closePayment (příznak, zda se platba zařadí do zúčtování) a dále parametr merchantData.

Příklad volání:

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.6/payment/oneclick/start \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature"
}'

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/init.

Příklad návratových hodnot pro payment/oneclick/start

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 2,
  "signature":"base64-encoded-response-signature"
 }

Pozn. Výsledek autorizace je potřeba zjistit následným voláním payment/status. Doporučená doba volání je 2-3 vteřiny po volání payment/oneclick/start, pokud je stav platby stále 2 (platba probíhá), doporučujeme periodicky volat co 5 vteřin (celková doba autorizace závisí na zpracování požadavku s systémech VISA/MC a může být v opravdu nejhorším případě až 60 vteřin).

Příklad návratových hodnot pro payment/oneclick/start -- neautorizovaná transakce (expirovaná karta):

{
  "payId":"c165e8c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"Card for payment/oneclick expired",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Z dat odesílaných na server sestavíme RETEZEC_ZPRAVY tak, že jednotlivé datové položky seřadíme za sebe v pořadí, v jakém jsou ve specifikaci uvedeny. Pro oddělení jednotlivých položek se použije oddělovač „|“. Do výpočtu zahrneme všechny parametry odeslané v požadavku. Pokud tedy nebude některý nepovinný parametr použit, nebude ani ve výsledném řetězci.

Pokud je položkou zprávy vnořený datový objekt, prostupuje se položkami tohoto objektu. V případě seznamu (např. položky items v inicializaci platby) se do výsledného řetězce vkládají položky ve stejném pořadí, v jakém jsou uvedeny ve zprávě.

Čísla jsou reprezentována v ASCII podobě, znaky jsou zapisované ve své binární reprezentaci (nejsou povoleny entity \uXXXX).

Pro samotný výpočet podpisu se pak použije privátní klíč obchodníka

signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

V případě ověření podpisu na platební bráně u GET operací do podpisu vstupují hodnoty parametrů, které jsou „URL dekódovány“.

Pro podepisování je potřeba použít algoritmus založený na SHA-1. Například v Javě je potřeba použít při inicializaci třídy java.security.Signature algoritmus "SHA1withRSA", v PHP je potřeba použít "OPENSSL_ALGO_SHA1", což je defaultní algoritmus pro funkce openssl_sign() a openssl_verify().

Příklad sestavení podpisu pro požadavek posílaný pomocí metody POST:

V operaci pro založení platby podepisujeme parametry následujícím způsobem ...

curl -v –X POST https://api.platebnibrana.csob.cz/api/v1.6/payment/init \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "orderNo":"5547",
  "dttm":"20140425131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":1789600,
  "currency":"CZK",
  "closePayment": true,
  "cart":[
    {
      "name": "Nákup: vasobchod.cz",
      "quantity": 1,
      "amount": 1789600,
      "description":"Lenovo ThinkPad Edge E540"
    },
    {
      "name": "Poštovné",
      "quantity": 1,
      "amount": 0,
      "description": "Doprava PPL"
    }
  ],
  "description":"Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)",
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"CZ",
  "returnUrl":"https://vasobchod.cz/gateway-return",
  "returnMethod":"POST",
  "signature":"base64-encoded-signature-of-payment-request"
}'

RETEZEC_ZPRAVY = "012345|5547|20140425131559|payment|card|1789600|CZK|true|https://vasobchod.cz/gateway-return|POST|Nákup: vasobchod.cz|1|1789600|Lenovo ThinkPad Edge E540|Poštovné|1|0|Doprava PPL|Nákup na vasobchod.cz (Lenovo ThinkPad Edge E540, Doprava PPL)|some-base64-encoded-merchant-data|CZ"

signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Jak je vidět, nepovinný parametr customerId není v požadavku vyplněn, není ani součástí hodnoty RETEZEC_ZPRAVY, po hodnotě merchantData následuje hodnota parametru language -- bez nutnosti vkládat extra odddělovač | pro nevyplněný parametr.

Při vytváření hodnoty RETEZEC_ZPRAVY nezáleží na pořadí položek v JSON požadavku, určující je pořadí parametrů uvedených v této specifikaci -- viz příklad umístění parametrů returnUrl a returnMethod.

Příklad sestavení podpisu pro požadavek posílaný pomocí metody PUT:

V operaci pro zařazení transakce do zúčtování podepisujeme parametry merchantId, payId a dttm následujícím způsobem ...

curl -v –X PUT https://api.platebnibrana.csob.cz/api/v1.6/payment/close \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"012345",
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "signature":"base64-encoded-request-signature",
}'

RETEZEC_ZPRAVY = "012345|d165e3c4b624fBD|20140425131559"
signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Příklad sestavení podpisu pro požadavek posílaný pomocí metody GET:

V operaci pro zjištění informací o uloženém zákazníkovi podepisujeme parametry merchantId, customerId a dttm následujícím způsobem ...

Přenášené parametry musí být „URL enkódovány“.

curl -v –X GET https://api.platebnibrana.csob.cz/api/v1.6/customer/info/012345/cust123%40mail.com/20140425131559/url-encoded-signature

RETEZEC_ZPRAVY = "012345|[email protected]|20140425131559"
signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Podobně jako u vytvoření podpisu požadavku se pro ověření podpisu odpovědi z jednotlivých položek odpovědi vytvoří RETEZEC_ZPRAVY a pro ověření podpisu se použije veřejný klíč platební brány. Ten lze získat z informačního portálu platební brány.

Pro následující odpověď pro založení platby pomocí payment/init

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

bude řetězec pro ověření podpisu následující:

RETEZEC_ZPRAVY = "d165e3c4b624fBD|20140425131559|0|OK|1"

U transakcí ve stavu 4 nebo 7 (odpověď u operací payment/status, payment/close apod) se posílá se i autorizační kód, který je také součástí podpisu:

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 4,
  "authCode": "qwFDF32",
  "signature":"base64-encoded-response-signature"
 }

řetězec pro ověření podpisu bude následující:

RETEZEC_ZPRAVY = "d165e3c4b624fBD|20140425131559|0|OK|4|qwFDF32"

Při přesměrování z platební brány zpět na e-shop je součástí odpovědi i parametr merchantData (pokud byl předán v rámci operace payment/init) ...

{
  "payId":"d165e3c4b624fBD",
  "dttm":"20140425131559",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "authCode": "qwFDF32",
  "merchantData": "base64-encoded-merchant-data",
  "signature":"base64-encoded-response-signature"
 }

řetězec pro ověření podpisu bude následující:

RETEZEC_ZPRAVY = "d165e3c4b624fBD|20140425131559|0|OK|7|qwFDF32|base64-encoded-merchant-data"

Poznámka: obecně platí, že parametry paymentStatus, authCode a merchantData se přidávají do řetězce pro ověření podpisu jen pokud jsou vyplněné (např. pro transakci ve stavu 3 nebude vyplněn authCode ale bude vyplněn parametr merchantData, výsledný řetězec pak bude ve formátu payId|dttm|resultCode|resultMessage|paymentStatus|merchantData).