mtransfer Technická dokumentace Varianta Standard

mTransfer Technická dokumentace Varianta Standard

mBank S.A., se sídlem ul. Senatorska 18, 00-950 Warszawa, Polsko, zapsaná v Celostátním soudním rejstříku (KRS) – Rejstříku podnikatelů vedeném u Obvodního soudu hl. m. Varšavy, XII. hospodářské oddělení, pod číslem KRS0000025237, REGON: 001254524, vykonávající bankovní činnost na území České republiky prostřednictvím pobočky banky mBank S.A., organizační složka, se sídlem Sokolovská 668/136d, 186 00 Praha 8, IČ: 27943445, zapsaná v obchodním rejstříku vedeném Městským soudem v Praze, oddíl A, vložka 58319

Obsah 1

Popis dokumentu ........................................................................................................................................ 1

2

Obecné informace o systému mPeníze ........................................................................................................... 1 2.1

Jak funguje systém mPeníze..................................................................................................................... 1

2.2

Zabezpečení ........................................................................................................................................... 1

2.3

Varianty ................................................................................................................................................. 1

3

Technický popis systému.............................................................................................................................. 1 3.1

Definice pojmů ....................................................................................................................................... 2

3.2

Aktivace a nastavení služby mTRANSFER ................................................................................................... 2

3.3

Definice rozhraní a umístění odkazu .......................................................................................................... 6

3.3.1

Vstupní parametry .......................................................................................................................... 7

3.3.2

Příklad zdrojového kódu .................................................................................................................. 7

4

5

Popis provádění plateb ................................................................................................................................. 8 4.1

Volba způsobu platby .............................................................................................................................. 8

4.2

Přihlášení do internetového bankovnictví.................................................................................................... 9

4.3

Zobrazení detailů transakce.....................................................................................................................10

4.4

Autorizace platby SMS ............................................................................................................................11

4.5

Výsledek platby .....................................................................................................................................12

4.6

Přesměrování na návratovou stránku ........................................................................................................12

4.6.1

Pozitivní URL .................................................................................................................................12

4.6.2

Negativní URL ...............................................................................................................................13

Testování a uvedení do provozu ...................................................................................................................13


1

Popis dokumentu

Tento dokument obsahuje podrobné informace o službě mPeníze 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 systému mPeníze.

2

Obecné informace o systému mPeníze

2.1

Jak funguje systém mPeníze

Systém mPeníze umožňuje zákazníkům mBank disponujícím účtem mKONTO realizovat online platby na účet obchodníka prostřednictvím speciálního odkazu 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 systému mPeníze se připisují na speciální účet obchodníka „mBUSINESS KONTO se službou mTRANSFER“ v případě varianty PRO, nebo na podnikatelský účet mBUSINESS KONTO 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 „mBUSINESS KONTO se službou mTRANSFER“ v případě varianty PRO, resp. od data aktivace služby mTRANSFER na podnikatelském účtu mBUSINESS KONTO v případě varianty STANDARD.

2.2

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.

2.3

Varianty

V rámci systému mPeníze 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.

3

Technický popis systému

Aby obchodník mohl prostřednictvím systému mPeníze přijímat platby ve variantě Standard, podmínky: 1)

Otevřít si v mBank podnikatelský účet mBUSINESS KONTO

2)

Aktivovat v internetovém bankovnictví službu mTRANSFER

musí splnit následující

1


3)

3.1

Umístit na svůj internetový obchod speciální odkaz pro provedení platby

Definice pojmů Obchodník = Osoba, která v systému mPeníze přijímá platby od zákazníků na svůj účet mBUSINESS KONTO se službou mTRANSFER. Zákazník = Osoba, která v systému mPeníze odesílá platby ze svého účtu mKONTO nebo mBUSINESS KONTO na účet obchodníka. Úspěšné provedení platby = Korektní dokončení platby v systému mPeníze, 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.

3.2

Aktivace a nastavení služby mTRANSFER

Pro registraci služby mTRANSFER se přihlaste do internetového bankovnictví mBank. V menu zvolte možnost Moje účty > mBUSINESS KONTO. Detail účtu mBUSINESS KONTO:

V detailu účtu pokračujte volbou mTRANSFER > Nová služba. V prvním kroku nastavte číslo účtu pro příjem plateb, pevnou část popisu transakce a zda chcete či nechcete dát zákazníkovi možnost změnit proměnný popis, výši částky nebo datum transakce. Jako pevnou část popisu transakce doporučujeme uvést doménu obchodu, např. obchodxyz.cz.

2


Zřízení služby mTRANSFER, krok 1/3:

3


V následujícím kroku potvrďte zvolené údaje. Zřízení služby mTRANSFER, krok 2/3:

4


V posledním kroku je oznámen výsledek založení služby. Zřízení služby mTRANSFER, krok 3/3:

Po zaregistrování se služba zobrazí seznamu služeb mTRANSFER pro daný účet. Seznam služeb mTRANSFER:

5


3.3

Definice rozhraní a umístění odkazu

Transakci zahajuje server obchodníka prostřednictvím odkazu na webové stránce nebo v e-mailu. Web http://www.mpenize.cz/ kromě informačních stránek obsahuje stránku pro výběr platby. URI této stránky se skládá z konstantní části a definice parametrů (query string). Parametry pro query string jsou shodné s těmi, které se následně posílají do internetového bankovnictví mBank. URI = ? 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ží. Příklad: https://mpenize.cz/paymentSelectionScreen?ServiceId=12345678&Amount=49.99&TrDate=NOW&Description=Popis %20bankovn%ED%20transakce&SessionId=xyz0123&OrderId=zyx3210&VS=0123456789&SS=9876543210&KS=055 8 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. Význam, délka a formát přenášených parametrů je následující: Povinné parametry: ServiceId = Identifikační číslo služby o

Řetězec složený přesně z 8 číslic.

o

ServiceId je generované při registraci služby mTRANSFER.

o

K jednomu účtu lze aktivovat až 50 ServiceId.

Amount = Převáděná částka o

Řetězec složený maximálně z 10 znaků.

o

Povolenými znaky jsou číslice [0-9], (\) a (.).

o

Desetinným separátorem je tečka.

TrDate = Datum transakce o

Doporučená hodnota parametru je NOW, kdy se vloží systémové datum serveru mBank.

o

Formát DDMMYYYY.

Nepovinné parametry: Description = Popis transakce o

Řetězec složený maximálně ze 140 znaků.

o

Kódován standardní metodou URL Encode, udaná délka je před zakódováním.

o

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á.

6


SessionId = Identifikace relace o


o

Povolené znaky jsou [a-z], [A-Z], [0-9].

OrderId = Identifikace transakce o


o

Povolené znaky jsou [a-z], [A-Z], [0-9].

VS = Variabilní symbol bankovní transakce. o


o

Povolené znaky jsou [0-9].

KS = Konstantní symbol bankovní transakce. o


o


SS = Specifický symbol bankovní transakce. o


o


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.

3.3.1

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://mpenize.cz/paymentSelectionScreen?ServiceId=12345678&Amount=49.99&TrDate=NOW&Description =Popis%20bankovn%ED%20transakce&SessionId=xyz0123&OrderId=zyx3210&VS=0123456789&SS=9876543210&K S=0558

3.3.2

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 (mpenize_start.asp) 7


3)

Otevření stránky s odkazem pro přesměrování na platbu v prohlížeči a provedení testovací transakce.

Příklad: mpenize_start.asp

<%@LANGUAGE="VBScript"%> <% '----------------------------------------------------' mPenize link example - ASP '----------------------------------------------------Dim ADDRESS ADDRESS="https://mpenize.cz" Dim SessionNum Application.Lock 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." %> "> Zaplatit přes mPeníze
<% Response.Write "
--------------------------------
Session:"&SessionNum %>

4

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.

4.1

Volba způsobu platby

Zákazník je nejdříve přesměrován na stránku, kde zvolí způsob platby: Online platba Kreditní karta Půjčka

8


4.2

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. Pokud zákazník zadá heslo třikrát špatně, internetový kanál je zablokován.

9


4.3

Zobrazení detailů transakce

Po přihlášení se zákazníkovi zobrazí stránka s detaily transakce.

Zákazníkovi je nabídnut k transakci seznam účtů, které splňují následující podmínky: Jedná se o mKONTO nebo o mBUSINESS KONTO 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.

10


4.4

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.

11


4.5

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.

4.6

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.

4.6.1

Pozitivní URL

12


4.6.2

5

Negativní URL

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 mPeníze z webové stránky obchodníka za použití osobního účtu mKONTO (mBUSINESS KONTO, mKREDITKA)

2)

Kontrola správnosti vstupních parametrů a korektního dokončení transakce

3)

Kontrola testovacích plateb v transakční historii účtu

13


mtransfer Technická dokumentace Varianta Standard

Recommend Documents