Technická dokumentace Varianta Standard
Obsah Popis dokumentu...1 Obecné informace o službě mtransfer...1 Jak funguje služba mtransfer...1 Zabezpečení...1 Varianty...1 Technický popis systému...1 Aktivace a nastavení služby mtransfer...1 Definice rozhraní a umístění odkazu...4 Vstupní parametry...5 Příklad zdrojového kódu...5 Popis provádění plateb...6 Přihlášení do internetového bankovnictví...6 Zobrazení detailů transakce...6 Autorizace platby SMS...7 Výsledek platby...7 Přesměrování na návratovou stránku...8 Pozitivní URL...8 Negativní URL...8 Testování a uvedení do provozu...9 Pravidla pro umístění propagační ikony mtransfer...9
Popis dokumentu Tento dokument obsahuje podrobné informace o službě mtransfer včetně postupu implementace na webovou stránku a popisu běžného užívání systému. Dokument je určen osobám odpovídajícím za otázky z oblasti obchodu a informatiky spojené se zavedením a údržbou služby mtransfer. Obecné informace o službě mtransfer Jak funguje služba mtransfer Služba mtransfer umožňuje zákazníkům mbank disponujícím účtem mkonto či mkonto Business realizovat online platby na účet obchodníka prostřednictvím platebního tlačítka umístěného na webové stránce internetového obchodu případně v e-mailu. Platby zákazníků uskutečněné prostřednictvím služby mtransfer se připisují na speciální účet obchodníka mkontobusiness se službou mtransfer v případě varianty PRO, nebo na podnikatelský účet mkonto Business s aktivovanou službou mtransfer v případě varianty Standard. Transakce z účtu zákazníka na účet obchodníka je provedena okamžitě po dokončení platby. Celá transakční částka je připsána na účet obchodníka. Úrok na účtu obchodníka se řídí stávající úrokovou sazbou k tomuto typu účtu. Informace o provedené transakci jsou dostupné v transakční historii účtu. Poplatek za vedení služby se započítává od data aktivace účtu mkonto Business se službou mtransfer v případě varianty PRO, resp. od data aktivace služby mtransfer na podnikatelském účtu mkonto Business v případě varianty Standard. Zabezpečení Provádění transakcí ze strany zákazníka je zabezpečeno internetovou relací šifrovanou protokolem SSL přístupnou na základě správné kombinace identifikačního čísla klienta a hesla a dále potvrzením transakce prostřednictvím SMS. Po přihlášení do internetového bankovnictví nemá zákazník přístupné jiné operace kromě příslušné transakce. Varianty V rámci systému mtransfer mbank má obchodník na výběr dvě varianty služeb, umožňující online platby: a) Varianta Standard b) Varianta Pro S ohledem na potřeby menších internetových obchodů mbank nabízí jednodušší variantu služby Standard. Varianta Pro je určena především velkým internetovým obchodům, které mají zájem o širší spolupráci, vyžadují pokročilejší kontrolu nad platbami, případně potřebují platební systém integrovat s dalšími systémy. Varianta Pro zahrnuje navíc obchodníkům umožňuje: Definovat vlastní návratové stránky (pozitivní a negativní URL) Přijímat online serverové notifikace (NPM) Přijímat CSV výpisy odesílané každou hodinu formou šifrovaných souborů obsahujících údaje o veškerých transakcích v daný den. Tento dokument popisuje způsob implementace pro variantu Standard. Technický popis systému Aby obchodník mohl prostřednictvím služby mtransfer přijímat platby ve variantě Standard, musí splnit následující podmínky: 1) Otevřít si v mbank podnikatelský účet mkonto Business 2) Aktivovat v internetovém bankovnictví službu mtransfer 3) Umístit na svůj internetový obchod speciální odkaz pro provedení platby Definice pojmů Obchodník = Osoba, která v systému mtransfer přijímá platby od zákazníků na svůj účet mkonto Business se službou mtransfer. Zákazník = Osoba, která se službou mtransfer odesílá platby ze svého účtu mkonto nebo mkonto Business na účet obchodníka. Úspěšné provedení platby = Korektní dokončení platby se službouu mtransfer, po kterém se klientovi zobrazí pozitivní URL Neúspěšné provedení platby = Chybné dokončení platby, kdy zákazník: o Použil chybný autorizační SMS kód. o Stiskl tlačítko Storno nebo Konec. Pozitivní URL = Adresa webové stránky na níž je zákazník přesměrován po úspěšném provedení platby Negativní URL = Adresa webové stránky na níž je zákazník přesměrován po neúspěšném provedení platby, například když se odhlásí z internetového bankovnictví před dokončením platby. Disponent účtu používá stejné identifikační číslo klienta a přístupové heslo bez ohledu na počet účtů, kterými v mbank disponuje. Aktivace a nastavení služby mtransfer Pro registraci služby mtransfer se přihlaste do internetového bankovnictví mbank a jděte do firemního profilu. V menu zvolte možnost Moje Finance > Účty > mkonto Business > mtransfer (zaregistrovat službu) 1/9
Zřízení služby mtransfer Standard, krok 1/6. Detail účtu mkonto Business po přihlášení do internetového bankovnictví ve firemním profilu.: Zřízení služby mtransfer Standard, krok 2/6. Vyberte Moje Finance. Zřízení služby mtransfer Standard, krok 3/6. Vyberte Účty. 2/9
Zřízení služby mtransfer Standard, krok 4/6. Klikněte myší na podsvícené mkonto Business. Zřízení služby mtransfer Standard, krok 5/6. Vyberte Zaregistrovat službu. 3/9
Zřízení služby mtransfer Standard, krok 6/6. Uveďte informaci do části Pevná část popisu převodu. Poté potvrďte. Jako pevnou část popisu transakce doporučujeme uvést doménu obchodu, např. obchodxyz.cz. Po zadání informace do pole Pevná část popisu převodu a potvrzení obdržíte Vaše ID služby, které budete potřebovat dále. Definice rozhraní a umístění odkazu Transakci zahajuje server obchodníka prostřednictvím odkazu na webové stránce nebo v e-mailu. Příklad odkazu: https://cz.mbank.eu/paymentselectionscreen?serviceid=12345678&amount=49.99&trdate=now&description=popis%20bankovn%ed%20transakce&sessionid=xyz0123&orderid=zyx3210&vs=0123456789&ss=9876543210&ks=0558 Odkaz se skládá z konstantních a definovaných parametrů (query string) Parametry pro query string jsou shodné s těmi, které se následně posílají do internetového bankovnictví mbank. Význam, délka a formát přenášených parametrů je následující: Povinné parametry: ServiceId = Identifikační číslo služby Řetězec složený přesně z 8 číslic. ServiceId je generované při registraci služby mtransfer. K jednomu účtu lze aktivovat až 50 ServiceId. Amount = Převáděná částka Řetězec složený maximálně z 10 znaků. Povolenými znak y jsou číslice [0-9], (\) a (.). Desetinným separátorem je tečka. TrDate = Datum transakce Doporučená hodnota parametru je NOW, kdy se vloží systémové datum serveru mbank. Formát DDMMYYYY. Nepovinné parametry: Description = Popis transakce Řetězec složený maximálně ze 140 znaků. Kódován standardní metodou URL Encode, udaná délka je před zakódováním. Povolené znaky jsou [a-z], [A-Z], [0-9]. Pevná část popisu transakce Řetězec složený maximálně z 35 znaků. Tato část je pro každé ServiceId vždy stejná. Jako vstupní parametr jej doplní server mbank na základě nastavení služby mtransfer v internetovém bankovnictví (viz část 3.2 Aktivace a nastavení služby mtransfer). Mezera, 1 znak. Proměnná část popisu transakce Řetězec složený maximálně ze 104 znaků (69 před zakódováním). Do tohoto řetězce lze zahrnout všechny dodatečné informace, které nemohou být začleněny do jiných parametrů odkazu, nebo tato část může zůstat zcela prázdná. 4/9
SessionId = Identifikace relace Řetězec složený maximálně ze 64 znaků. Povolené znaky jsou [a-z], [A-Z], [0-9]. OrderId = Identifikace transakce Řetězec složený maximálně ze 32 znaků. Povolené znaky jsou [a-z], [A-Z], [0-9]. VS = Variabilní symbol bankovní transakce. Řetězec složený maximálně z 10 znaků. Povolené znaky jsou [0-9]. KS = Konstantní symbol bankovní transakce. Řetězec složený maximálně z 4 znaků. Povolené znaky jsou [0-9]. SS = Specifický symbol bankovní transakce. Řetězec složený maximálně z 10 znaků. Povolené znaky jsou [0-9]. URI = <konstantní_část_uri>?<query_string> Všechny jednotlivé parametry v odkazu jsou oddělené prostřednictvím separátoru & a následují po části adresy paymentselectionscreen?. Na pořadí parametrů v odkazu nezáleží. Parametry odkazu jsou přenášeny metodou HTTP GET přes protokol HTTPS na stránku mtransfer.asp umístěnou na serveru mbank. Hodnoty všech přenášených parametrů se kódují standardní metodou URLEncode, udaná délka parametrů je před zakódováním. Názvy parametrů query stringu doporučujeme zadávat jako case-sensitive. Výstupní parametry budou stejné jako vstupní, pokud je zákazník v průběhu platby nezměnil. Parametry lze regulérně měnit prostřednictvím formuláře v prvním kroku platby. Upozornění: Pokud zákazník provede změnu parametrů v odkazu, platba se provede, proto je třeba všechny parametry plateb na straně obchodníka kontrolovat. Vstupní parametry V odkazu na stránku mbank jsou přenášeny následující parametry: ServiceId Amount TrDate Description SessionId OrderId VS KS SS Příklad: https://cz.mbank.eu/paymentselectionscreen?serviceid=12345678&amount=49.99&trdate=now&description=popis%20bankovn%ed%20 transakce&sessionid=xyz0123&orderid=zyx3210&vs=0123456789&ss=9876543210&ks=0558 Příklad zdrojového kódu Postup implementace: 1) Aktivace služby, definující adresu pro NPM notifikaci, pozitivní a negativní návratovou stránku 2) Vytvoření webové stránky obsahující odkaz pro přesměrování na platbu s příslušným ServiceID pro danou doménu (mtransfer_start.asp) 3) Otevření stránky s odkazem pro přesměrování na platbu v prohlížeči a provedení testovací transakce. Příklad: mtransfer_start.asp <%@LANGUAGE="VBScript"%> <% '----------------------------------------------------- ' mtransfer link example - ASP '----------------------------------------------------- Dim ADDRESS ADDRESS="https://cz.mbank.eu/" Dim SessionNum Application.Lock 5/9
Application("SessionNum")=Application("SessionNum")+1 SessionNum=Application("SessionNum") Application("Session"&SessionNum)="START" Application.UnLock VariableDescription="Any description you wish." OrderId="Any orderid you are able to generate." VS="Any bank indetifier you wish." SS="Input correct bank identifier." KS="Input correct bank identifier." %> <a href=" <% Response.Write (ADDRESS&"/paymentSelectionScreen?ServiceId=12345678&Amount=0.01&TrDate="now"&Description="&VariableDescription"&SessionId="&SessionNum"&OrderId="&OrderId"&VS="&VS"&SS="&SS"&KS="&KS) ) %>"> Zaplatit pres mtransfer </a> <br> <% Response.Write "<br>--------------------------------<br>session:"&sessionnum %> Popis provádění plateb Zákazník provádí platby prostřednictvím internetového bankovnictví mbank, kam je přesměrován speciálním odkazem obsahujícím parametry dané platby. Přihlášení do internetového bankovnictví Poté je přesměrován na přihlašovací stránku internetového bankovnictví mbank, kde se přihlásí prostřednictvím identifikačního čísla klienta a hesla. Zobrazení detailů transakce Po přihlášení se zákazníkovi zobrazí stránka s detaily transakce. 6/9
Zákazníkovi je nabídnut k transakci seznam účtů, které splňují následující podmínky: Jedná se o mkonto nebo o mkonto Business Zákazník je majitelem, spolumajitelem nebo všeobecným disponentem účtu Pro každý z účtů zákazníka je uveden jeho druh a číslo včetně dostupných finančních zdrojů. V nastavení služby mtransfer je možné zákazníkovi povolit editaci následujících polí: Popis transakce (proměnná část popisu transakce) a Částka Datum operace (zákazník může libovolně změnit datum platby) Zákazníkovi jsou dostupné tyto funkce: Storno Pokračovat V případě stisknutí tlačítka Storno je zákazník přesměrován na negativní URL a transakce se neprovede. Autorizace platby SMS Při volbě Pokračovat se zobrazí stránka, kde je nutné platbu potvrdit unikátním SMS kódem zaslaným na mobilní telefon registrovaný v mbank. Zákazník má dostupné tyto funkce: Zpět, Upravit, Potvrdit, Potvrdit později. V prvních dvou uvedených případech je zákazník přesměrován na předcházející stránku. V případě, že zákazník zvolí poslední možnost, platba není provedena a je na jeho účtu v internetovém bankovnictví zařazena mezi Operace k autorizaci. Pokud zákazník zadá Potvrdit, zobrazí se výsledek platby. Výsledek platby Po autorizaci transakce je klient přesměrován na stránku s potvrzením o provedení transakce a platba je bezprostředně realizována nebo je v případě pozdější splatnosti naplánována jako budoucí operace. Peníze jsou převedeny na účet obchodníka okamžitě v den splatnosti, tato operace se považuje za standardní transakci zpoplatněnou dle sazebníku mbank. Pokud se zákazník neodhlásí volbou Odhlásit se, je po stanoveném časovém intervalu automaticky odhlášen a přesměrován na návratovou stránku. 7/9
Přesměrování na návratovou stránku Jak po provedení transakce tak případně po předčasném stornování je zákazník odhlášen a přesměrován na návratovou stránku obchodníka (pozitivní nebo negativní URL). Implicitní návratové stránky mbank jsou: http://info.mbank.cz/mtransfer_pozitivni.html http://info.mbank.cz/mtransfer_negativni.html Ve variantě Standard jsou tyto stránky předdefinované a nelze je měnit. Pozitivní URL Negativní URL 8/9
Testování a uvedení do provozu Před spuštěním do ostrého provozu doporučujeme provést testování. Testování probíhá na provozním účtu obchodníka, pro tyto účely nejsou mbank zřizovány testovací účty. Pro testovací objednávku doporučujeme nastavit parametr Amount=0.01. Doporučený postup testování: 1) Kontrola iniciace platby přes mtransfer z webové stránky obchodníka za použití osobního účtu mkonto 2) Kontrola správnosti vstupních parametrů a korektního dokončení transakce 3) Kontrola testovacích plateb v transakční historii účtu Pravidla pro umístění propagační ikony služby mtransfer Pro realizace propagace je nutné obchod označit podle stanovených podmínek ikonou odkazující na informační stránky http://www.mbank.cz/firemni/sluzby/mtransfer/ Pro umístění propagační ikony služby mtransfer požijte následující HTML kód: <a href="http://www.mpenize.cz/" title="www.mpenize.cz"> <img src="http://www.mbank.cz/mpenize.gif" alt="ikona mpeníze" border="0"> </a> Jakákoliv změna grafické podoby nebo použití ikonky jako platebního odkazu není dovolena. Nepoužívejte propagační ikonu jako platební odkaz. K tomuto účelu prosím použijte text, který bude obsahovat název platebního systému mtransfer například Zaplatit přes mtransfer, viz příklad v části Chyba! Nenašel se žádný zdroj odkazů. 9/9