1. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
MOPET
CZ,
a.s.
Připojení
obchodníka
do
systému
Mobito
Příručka
pro
integraci
MOPET
CZ,
a.
s.
Page
1
of
48
Confidential
document

2. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
Změny
v
dokumentu
Verze
Datum
Autor
Popis
0.1
12.1.2012
Tomáš
Severýn
Vytvoření
dokumentu
0.2
8.2.2012
Tomáš
Severýn
Úprava
po
interním
kole
připomínek
0.3
21.2.2012
Tomáš
Severýn
Úprava
zabezpečovacího
mechanismu
(počítání
HASH)
0.4
24.2.2012
Tomáš
Severýn
Úprava
platebního
tlačítka
-­‐pole
timestamp
včetně
popisu
v
příloze
B,
aktualizace
přílohy
A
–
formátování
a
číslo
verze
MOPET
CZ,
a.
s.
Page
2
of
48
Confidential
document

3. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
Obsah
1.
Cíl
dokumentu
.................................................................................................................................
4
2.
Manažerské
shrnutí
.........................................................................................................................
4
2.1.
Představení
společnosti
Mopet
a
systému
Mobito
.................................................................
4
2.2.
Možnosti
připojení
..................................................................................................................
4
2.3.
Náročnost
implementace:
.......................................................................................................
4
Platební
tlačítko:
.............................................................................................................................
4
Mobito
kód
a
připojení
na
rozhraní:
...............................................................................................
5
2.4.
K
čemu
slouží
testovací
prostředí:
..........................................................................................
5
2.5.
Testovací
fáze:
.........................................................................................................................
5
2.6.
Poskytovaná
podpora:
............................................................................................................
5
Zkratky
používané
v
dokumentu
.....................................................................................................
5
3.
Platební
tlačítko
..............................................................................................................................
6
3.1.
Obecné
předpoklady
scénářů:
................................................................................................
6
3.2.
Mobito
Platební
Tlačítko
(Bez
Integrace)
................................................................................
6
3.3.
Mobito
Platební
Tlačítko
(Integrace)
.......................................................................................
7
3.4.
Požadavky
na
zobrazení
platebního
tlačítka
.........................................................................
10
3.5.
Testování
platebního
tlačítka
................................................................................................
10
4.
Integrace
plateb
spuštěných
klientem
(Mobito
Code)
..................................................................
11
4.1.
Testování
MobitoCode
..........................................................................................................
13
5.
Integrace
WebServices
požadavky
na
platbu
................................................................................
13
5.1.
Testování
Web
Services
.........................................................................................................
14
6.
Integrace
Notifikace
......................................................................................................................
15
7.
Integrace
WebServices
-­‐
Zjištění
stavu
transakcí
.........................................................................
15
8.
Ověření
klienta
..............................................................................................................................
15
8.1.
Bezpečnostní
kód
..................................................................................................................
15
8.2.
Algoritmus
.............................................................................................................................
15
9.
FAQs
..............................................................................................................................................
16
10.
Příloha
A
Technický
popis
rozhraní
(EN)
...................................................................................
17
11.
Příloha
B
Kód
platebního
tlačítka
..............................................................................................
46
MOPET
CZ,
a.
s.
Page
3
of
48
Confidential
document

4. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
1. Cíl
dokumentu
Cílem
tohoto
dokumentu
je
seznámit
obchodníky
s
možnostmi
zapojení
do
systému
Mobito
a
zároveň
je
provést
procesem
připojování
jednotlivých
kanálů.
Součástí
tohoto
dokumentu
jsou
všechny
informace
nutné
k
implementaci,
integraci
a
otestování
vybrané
platební
metody
společnosti
Mopet
CZ.
2. Manažerské
shrnutí
2.1. Představení
společnosti
Mopet
a
systému
Mobito
Společnost
MOPET
CZ,
a.s.
je
akciová
společnost,
jejímiž
spoluvlastníky
jsou
čeští
mobilní
operátoři
O2
Telefonica,
Vodafone
a
T-­‐Mobile
a
bankovní
domy
Česká
spořitelna,
Raiffeisenbank,
UniCredit
a
GE
Money
Bank.
Základním
cílem
společnosti
je
vybudovat
transakční
centrum
pro
mobilní
platby
a
uvést
na
český
trh
službu
Mobito,
umožňující
platit
a
posílat
peníze
v
reálném
čase
přes
mobilní
telefon
tam,
kde
nyní
zákazníci
používají
převážně
hotovost,
bez
ohledu
na
to,
které
banky
nebo
operátora
jsou
klienty.
Lze
tak
platit
mobilním
telefonem
za
zboží
a
služby,
hradit
složenky
a
faktury,
posílat
si
mezi
sebou
peníze
či
zaplatit
mobilním
telefonem
nákup
na
internetu
nebo
v
mobilu.
Společnost
vznikla
ke
konci
roku
2010
a
její
snahou
je
spuštění
všech
procesů
a
služeb
počátkem
roku
2012.
Projekt
přípravy
služby
je
v
plném
proudu
–
co
se
IT
oblasti
týče,
vzniká
nyní
i
firemní
infrastruktura
systémů
jako
transakční
jádro,
ERP
systém,
napojení
na
banky,
operátory
a
platební
bránu
a
další
podpůrné
systémy.
Mobito
je
nový
platební
standard
na
českém
trhu,
který
umožňuje
zákazníkům
platit
prostřednictvím
mobilních
telefonů
za
zboží
a
služby.
Hlavním
prvkem
Mobita
je
tzv.
„request
for
payment
–
žádost
k
zaplacení“,
kterou
dostává
zákazník
do
svého
mobilu
a
potvrzuje
ji
PINem.
Mobito
je
zdarma,
funguje
na
všech
mobilních
telefonech
a
pro
klienty
všech
českých
bank
a
mobilních
operátorů.
Mobito
má
ambici
stát
se
synonymem
pro
peníze
v
mobilu
a
inovativní
univerzální
platební
metodu,
která
bude
mít
své
pevné
místo
vedle
hotovosti
a
platebních
karet.
Peníze
v
mobilu,
jinak
než
je
doposud
znáte,
to
je
Mobito.
2.2. Možnosti
připojení
Obchodník
má
3
možnosti
připojení
k
systému
Mobito.
Jsou
to:
1. Platební
tlačítko
2. Integrace
pomocí
webových
služeb
pro
platbu
3. Integrace
Mobito
kód
Každá
z
možností
bude
detailněji
probrána
v
následujících
kapitolách.
2.3. Náročnost
implementace:
Platební
tlačítko:
Společnost
Mopet
se
snaží
maximálně
zjednodušit
přístup
ke
svým
platebním
metodám
pro
maximálně
širokou
skupinu
obchodníků.
Na
základě
této
dlouhodobé
vize
jsme
se
pokusili
navrhnout
MOPET
CZ,
a.
s.
Page
4
of
48
Confidential
document

5. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
připojení
na
platební
bránu
v
maximálně
zjednodušené
podobě.
Předpokládána
náročnost
implementace
základní
funkčnosti
by
měla
být
do
1
MD
(práce
člověka
za
jeden
8
hodinový
den)
Mobito
kód
a
připojení
na
rozhraní:
Tato
funkcionalita
je
o
něco
složitější,
protože
vyžaduje
znalosti
a
zkušenost
s
implementací
webových
služeb,
větší
znalost
vnitřních
procesů
obchodníka
a
náročnější
způsob
připojení
na
testovací
a
produkční
prostředí.
Připojení
přes
tyto
metody
řešíme
individuálně
mimo
standardní
procesy
připojení
obchodníka.
Tato
integrace
vyžaduje
vlastní
rozhraní
na
straně
obchodníka,
pomocí
kterého
je
náš
systém
informován
o
nabízeném
zboží/službách.
Tímto
umožňuje
vytvořit
nové
obchodní
kanály
například
z
mobilního
telefonu,
dále
integraci
do
stávající
infrastruktury
pokladních
systémů
a
zapojení
plateb
do
obchodních
procesů.
Očekávaná
doba
implementace
by
se
měla
pohybovat
okolo
3MD
připojení
na
rozhraní,
a
5MD
připojení
pro
Mobito
code.
Poté
je
potřeba
počítat
s
cca
1MD
na
testy.
Do
odhadu
nejsou
započítány
pracnosti
nutné
na
změnu
procesů
ve
Vašem
systému
případně
infrastruktury.
2.4. K
čemu
slouží
testovací
prostředí:
Testovací
prostředí
poskytuje
společnost
Mopet
CZ
pro
podporu
integrace
obchodníka
na
produkt
Mobito.
Na
tomto
prostředí
si
obchodník
ověří,
že
jeho
systém
funguje
dle
specifikace
a
Mopet
CZ
mu
na
základě
tohoto
testu
umožní
přístup
na
produkční
prostředí.
Tímto
testem
se
obchodník
nezříká
zodpovědnosti
za
kvalitu
a
fungování
svojí
části
systému
v
živém
prostředí.
2.5. Testovací
fáze:
Společnost
Mopet
standardně
nabízí
3
týdenní
testovací
okno.
První
dva
týdny
slouží
primárně
pro
potřeby
připojovaného
obchodníka.
V
rámci
tohoto
období
si
obchodník
může
otestovat
svojí
část
systému
dle
svojí
potřeby.
Poslední
týden
slouží
pro
provedení
testů
popsaných
v
dokumentu
Popis
Připojení
obchodníka
v
příslušných
kapitolách
u
každé
platební
metody.
Na
základě
úspěšného
provedení
těchto
testů
je
zahájen
proces
„zprovoznění
obchodníka
pro
produkci“.
2.6. Poskytovaná
podpora:
Společnost
Mopet
poskytuje
podporu
pro
integraci
obchodníka
na
mailové
adrese:
podpora.obchodnika@mopetcz.cz
V
případě
jakýchkoliv
problémů
se
můžete
obrátit
na
tento
mail.
Zkratky
používané
v
dokumentu
Zkratka
Popis
WSDL
Web
Service
Definition
File
–
soubor
popisující
rozhraní
webových
služeb
XML
Extensible
Markup
Language
RFP
Request
for
payment
-­‐
Požadavek
na
platbu
-­‐
klientovi
je
zaslána
informace
o
platbě,
kterou
může
potvrdit,
zrušit
a
v
některých
případech
odložit
MOPET
CZ,
a.
s.
Page
5
of
48
Confidential
document

6. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
3. Platební
tlačítko
3.1. Obecné
předpoklady
scénářů:
• Klient
–
Fyzická
osoba
zaregistrována
a
aktivována
do
služby
Mobito.
Klient
má
na
účtu
dostatek
prostředků
na
zaplacení
poptávané
služby
/
vybraného
zboží
(klient
má
možnost
zaplatit
zboží
i
bez
předchozí
dotace
účtu
–
klient
s
online
připojeným
platebním
instrumentem)
• Obchodník
–
Fyzická,
nebo
právnická
osoba,
se
kterou
je
uzavřena
smlouva
s
firmou
Mopet
CZ.
Obchodník
je
zaregistrován
a
aktivován
do
služby
Mobito
3.2. Mobito
Platební
Tlačítko
(Bez
Integrace)
Popis
Platební
tlačítko
bez
integrace
slouží
například
pro
nadace
/
občanská
sdružení
(OS),
která
chtějí
využít
možnosti
přes
Mobito
zaslat
dar.
Uživatelská
zkušenost:
-­‐ Klient
–
chce
vložit
dar
přes
web
nebo
mobilní
web
nadace
-­‐ Obchodník
/
OS
-­‐
chce
na
své
stránky
zobrazit
tlačítko
„darujte“
a
není
možné
jakékoliv
složité
programování
Scénář
platby:
-­‐ Klient
(web
OS)
–
stiskne
tlačítko
„darovat“,
-­‐ Web
OS–
přesměrování
klienta
na
platební
bránu
Mobito
a
předání
údajů
o
platbě
(částka,
popis)
-­‐ Klient
(platební
brána
Mobito)
–
zadání
Mobito
ID
(tel.
čísla
/
ID)
a
potvrzení
platby.
-­‐ Mobito
systém
–
zaslání
požadavku
na
platbu
na
tel.
číslo
klienta
registrované
u
Mobito
účtu
(nativní
notifikace,
USSD
notifikace)
-­‐ Klient
(mobilní
telefon)
–
přijetí
a
autorizace
transakce
unikátním
PINem
-­‐ Mobito
systém
–
ověření
transakce
a
notifikace
o
úspěšném
zaplacení
–
notifikace
klientovi
a
zaslání
potvrzujícího
emailu
do
OS.
Přesměrování
na
web
OS
-­‐ Klient
(web
obchodníka)
–
klientovi
je
zobrazena
notifikace
o
úspěšném
zaplacení
na
mobilu
/
je
možné
zobrazit
stránku
s
poděkováním
Jak
to
udělat:
Jak
to
udělat
/
Nastavení
pro
platbu
1) Přihlášení
se
do
portálu
pro
obchodníky
–
pomocí
administrátorského
účtu,
který
obdržíte
při
podpisu
smlouvy
2) Nastavení
obchodního
místa
-­‐
vytvoření
Virtuálního
zaměstnance
a) Vytvořte
pomocí
návodu
základní
strukturu
–jednoho
Virtuálního
zaměstnance
přímo
pod
svým
účtem
b) WWW
adresu,
kterou
chcete,
aby
se
zobrazila
na
Mobito
Bráně
vložte
do
parametru
Název
Virtuálního
zaměstnance
c) Odpověď
na
e-­‐mail
–
nastavte
e-­‐mail
na
který
Vám
budou
chodit
informace
o
platbách
MOPET
CZ,
a.
s.
Page
6
of
48
Confidential
document

7. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
3) Nastavení
adres
pro
přesměrování
na
bránu
a) Jako
cílovou
adresu
pro
ukončení
platby
nastavte
odkaz
na
stránku
na
vašem
serveru,
kde
uživateli
poděkujete
za
dar.
Adresu
pro
chybu
ponechte
prázdnou.
b) Stránku
pro
případ
neúspěch
ponechte
prázdnou,
v
případě
neúspěchu
se
uživateli
zobrazí
automatická
informace
naší
brány
c) Adresy
musí
být
ve
tvaru
https://server:port/soubor
4) Nastavte
si
na
Portálu
pro
obchodníky
e-­‐mail
notifikaci
o
provedené
platbě,
abyste
měli
přehled.
5) SourceAuthKey
Zobrazí
se
na
výpisu
detialů
Virtuálního
zaměstnance
a) Tento
klíč,
stejně
jako
vaše
Identifikační
číslo
(SourceID)
vložte
do
předpřipraveného
kódu
b) pro
tlačítko
6) Na
vaše
webové
stránky
vložte
HTML
kód
(viz
příloha
B)
s
jednoduchým
platebním
tlačítkem
s
přednastavenou
částkou
(případně
několik
tlačítek
s
různými
částkami
nebo
tlačítko
s
možností
uživatelské
editace
částky).
Do
pole
timestamp
vložte
aktuální
datum.
7) Celou
implementaci
je
možné
provést
bez
programování.
3.3. Mobito
Platební
Tlačítko
(Integrace)
Popis
Platební
tlačítko
umožňuje
začlenit
Mobito
jako
platební
metodu
např.
do
e-­‐shopu
obchodníka
sloužící
k
okamžitému
zaplacení
zboží.
Uživatelská
zkušenost:
-­‐ Klient
–
Nákup
mobilem
vzdáleně
přes
web
nebo
mobilní
web
obchodníka
(registrovaný
i
neregistrovaný
klient
webu)
-­‐ Obchodník
(eShop)
-­‐
Mobito
jako
platební
metoda,
integrace
Mobito
platebního
tlačítko
na
webu
/
mobilním
webu
obchodníka.
Jak
to
udělat
/
Nastavení
pro
platbu
1) Přihlášení
se
do
portálu
pro
obchodníky
–
pomocí
administrátorského
účtu,
který
obdržíte
při
podpisu
smlouvy
2) Nastavení
obchodního
místa
-­‐
vytvoření
Virtuálního
zaměstnance
MOPET
CZ,
a.
s.
Page
7
of
48
Confidential
document

8. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
a) Vytvořte
pomocí
návodu
základní
strukturu
obchodu
–
1
Virtuálního
zaměstnance
přímo
pod
svým
účtem
obchodníka
nebo
pod
některou
Vaší
pobočkou
(volitelně,
v
případě
že
chcete
mít
transakce
z
tohoto
obchodu
na
separátním
účtu
od
ostatních
transakcí)
b) WWW
adresu
obchodu,
kterou
chcete,
aby
se
zobrazila
na
Mobito
Bráně
vložte
do
parametru
Název
Virtuálního
zaměstnance
3) Nastavení
adres
pro
přesměrování
na
bránu
a) U
Virtuáního
zaměstnance
nastavte
adresy,
na
které
bude
zákazník
přesměrován
v
případě
úspěchu
případně
neúspěchu
transakce
b) Tyto
adresy
musí
být
ve
tvaru
https://server:port/soubor
4) SourceAuthKey,
SecurityToken
–
Zobrazí
se
na
výpisu
detialů
Virtuálního
zaměstnance
a) SourceAuthKey
se
použije
při
odesílání
požadavku
na
bránu
a
slouží
namísto
hesla.
Generuje
systém
po
vytvoření
Virtuálního
Employee
b) SecurityToken
slouží
pro
zajištění
bezpečnosti
návratu,
tento
kód
se
poté
použije
pro
podpis
a
na
Vaší
straně
pro
ověření
podpisu
zpráv
o
zaplacení.
Scénář
platby:
1) Klient
(web
obchodníka)
–
výběr
zboží
nebo
služby
na
webu
obchodníka,
výběr
platební
metody
–
Mobito
a
potvrzení
platby.
2) Web
obchodníka
–
přesměrování
klienta
na
platební
bránu
Mobito
a
předání
údajů
o
platbě
(částka,
popis
zboží
/
služby)
3) Klient
(platební
brána
Mobito)
–
zadání
Mobito
ID
(tel.čísla
/
ID)
a
potvrzení
platby.
4) Mobito
systém
–
zaslání
požadavku
na
platbu
na
tel.
číslo
klienta
registrované
u
Mobito
účtu
(nativní
notifikace,
USSD
notifikace)
5) Klient
(mobilní
telefon)
–
přijetí
a
autorizace
transakce
unikátním
PINem
6) Mobito
systém
–
ověření
transakce
a
notifikace
o
úspěšném
zaplacení
–
notifikace
klientovi
a
notifikace
webu
obchodníkovi.
Přesměrování
na
web
obchodníka
7) Klient
(web
obchodníka)
–
klientovi
je
zobrazena
notifikace
o
úspěšném
zaplacení
zboží
/
služby
a
další
instrukce.
a) Obchodník
-­‐
ověří
platnost
odpovědi
brány
pomocí
ověření
podpisu
(viz
kapitola
ověření)
Alternativy
scénáře
-­‐
obchodník:
A) Předvyplnění
Mobito
ID
-­‐
Web
obchodníka
předá
platební
bráně
Mobito
ID
zákazníka
(bude
předvyplněno)
–
krok
2
MOPET
CZ,
a.
s.
Page
8
of
48
Confidential
document

9. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
Alternativy
scénáře
-­‐
klient:
A) Transakce
nedokončena
/
neautorizována
-­‐
V
případě
neúspěšného
potvrzení
transakce
(klient
neautorizoval
transakci,
vypršel
limit)
je
klient
přesměrován
na
web
obchodníka
(definovaná
failure
–
chybová
-­‐
URL)
B) Transakce
dokončena,
ale
klient
uzavřel
Mobito
platební
bránu
před
přesměrováním
na
web
obchodníka
a. Manuálně
zjistit
stav
transakce
v
portálu
pro
obchodníky
b. Je
možné
nastavit
systém
tak,
aby
po
zaplacení
vyvolal
webovou
adresu
obchodníka
s
informacemi
o
zaplacení
c. Je
možné
zavolat
GetPaymentStatus
metodu
rozhraní
API,
kde
je
uveden
status
platby
Technické
požadavky
integrace:
-­‐ Odeslání
požadavku
na
platbu
-­‐
integrace
platebního
tlačítka
Mobito
na
web
obchodníka
(HTTP
POST
protokol)
-­‐ Přijetí
výsledku
transakce
–
schopnost
přijetí
a
zobrazení
výsledku
transakce
na
definovaném
URL
obchodníka
(nastavení
success
/
failure
URL
na
Mobito
portálu
obchodníka),
pokud
obchodník
vyžaduje
ověření,
schopnost
vypočítat
kontrolní
součet
(viz
kapitola
ověření)
Detailní
technický
popis
rozhraní
–
viz
Mobito
API
(příloha
A)
sd PaymentButton
MerchantSystem MobitoPaymentGateway Handset
POST/GET Redirect()
Enter MobitoID()
SendRFP()
PIN()
Redirect()
MOPET
CZ,
a.
s.
Page
9
of
48
Confidential
document

10. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
3.4. Požadavky
na
zobrazení
platebního
tlačítka
Ve
chvíli
implementace
požádejte
na
e-­‐mail
podpora.obchodnika@mopetcz.cz
o
zaslání
grafických
podkladů.
V
rámci
těchto
grafických
podkladů
jsou:
• Ikony,
které
je
možné
uvést
v
seznamu
platebních
metod,
případně
v
patičce
stránek
• Ikony,
které
požadujeme
uvést
v
případě
výběru
platební
metody
• Pozadí
pro
platební
tlačítko
(pokud
takové
využíváte)
3.5. Testování
platebního
tlačítka
Pro
ověření
funkčnosti
platebního
tlačítka
nejprve
nastavte
tlačítko
dle
návodu
v
kapitolách
výše.
Pro
testování
prosím
kontaktujte
alespoň
týden
předem
-­‐
email
podpora.obchodnika@mopetcz.cz
s
předmětem
„platební
tlačítko
-­‐
test“,
do
kterého
uveďte
následující
informace:
1) Kontaktní
osobu
2) Předpokládaný
čas
možných
testů
3) Název
obchodníka
+
www
stránky
Testovací
transakce
-­‐
úspěch
1) Kontaktujte
podpora.obchodnika@mopetcz.cz
a
potvrďte
si,
připravenost
pro
testy
2) Vytvořit
zkušební
transakci
–
Na
vašem
systému
vytvořte
transakci
tak,
aby
se
Vám
vygenerovalo
platební
tlačítko
3) Stisknutí
tlačítka
–
Stisk
tlačítka
vyvolá
přesměrování
na
platební
bránu
Mobito
a) Dojde
li
k
přesměrování
-­‐
pokračujte
bodem
3)
b) Pokud
k
přesměrování
nedojde
i) Zkontrolujtem,
zda
se
Vám
zobrazilo
tlačítko
správně
(nikoliv
jako
kód
<form…)
ii) Zkontrolujde,
zda
Váš
prohlížeč
neotevírá
jiné
okno
iii) Zkontrolujte,
že
máte
správné
informace
ve
zdrojovém
kódu
stránky
4) Zadejte
do
zobrazené
brány
číslo
-­‐
606079502
5) Počkejte,
až
náš
pracovník
potvrdí
transakci
a) Dojde
li
k
přesměrování
na
Váš
server,
zkontrolujte
přijetí
parametrů
a
ověření
(viz
kapitola
Bezpečnostní
kód
a
algoritmus
pro
jeho
vytvoření)
b) Nedojde
li
k
přesměrování,
zkontrolujte
adresu,
na
kterou
se
snaží
systém
přesměrovat
a
případně
ji
opravte
v
portálu
pro
obchodníky
Testovací
transakce
-­‐
neúspěch
6) Vytvořit
zkušební
transakci
–
Na
vašem
systému
vytvořte
transakci
tak,
aby
se
Vám
vygenerovalo
platební
tlačítko
7) Stisknutí
tlačítka
–
Stisk
tlačítka
vyvolá
přesměrování
na
platební
bránu
Mobito
8) Zadejte
do
zobrazené
brány
číslo
–
Jakékoliv
vaše
číslo
9) Počkejte,
až
náš
pracovník
zruší
transakci
a) Dojde
li
k
přesměrování
na
Váš
server,
zkontrolujte
přijetí
parametrů
a
ověření
b) Nedojde
li
k
přesměrování,
zkontrolujte
adresu,
na
kterou
se
snaží
systém
přesměrovat
a
případně
ji
opravte
v
portálu
pro
obchodníky
Testovací
transakce
–
vypršení
časového
limitu
10) Kontaktujte
podpora.obchodnika@mopetcz.cz
a
potvrďte
si,
že
chcete
testovat
vypršení
časového
limitu
11) Vytvořit
zkušební
transakci
–
Na
vašem
systému
vytvořte
transakci
tak,
aby
se
Vám
vygenerovalo
platební
tlačítko
12) Stisknutí
tlačítka
–
Stisk
tlačítka
vyvolá
přesměrování
na
platební
bránu
Mobito
13) Zadejte
do
zobrazené
brány
číslo
-­‐
602
356
797
MOPET
CZ,
a.
s.
Page
10
of
48
Confidential
document

11. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
14) Vyčkejte
do
vypršení
časového
limitu
a) Zkontrolujte
přijaté
parametry
4. Integrace
plateb
spuštěných
klientem
(Mobito
Code)
Popis
Pokud
chcete
využít
mobilní
telefon
klientů
jako
nákupní
prostředí,
je
možné
integrovat
je
pomocí
rozhraní
MobitoCode.
Uživatelská
zkušenost:
-­‐ Klient
–
Nákup
mobilem
například
na
základě
plakátu,
reklamy
v
TV,
čísla
faktury
apod.
-­‐ Obchodník
-­‐
Mobito
jako
platební
metoda
podpořená
jinými
informačními
kanály
(jakýkoliv
informační
kanál,
ze
kterého
si
klient
může
kód
zapamatovat)
Scénář
platby:
1) Klient
(mobilní
telefon)
–
přihlásí
se
do
Mobito
aplikace
a
zadá
kód.
2) Server
obchodníka
–
je
kontaktován
pro
zjištění,
zda
je
kód
ještě
platný
a
zda
obchodník
požaduje
po
klientovi
upřesnění
objednávky
a) Obchodník
si
může
vyžádat
(volitelně)
vyplnit
od
klienta:
i) Výběr
z
1-­‐9
voleb
(volby
vztahující
se
k
danému
kódu)
ii) Číslo
–
např.
počet,
variabilní
symbol,
číselný
identifikátor
apod.
iii) Text
–
upřesňující
údaje
k
objednávce
(např.
SPZ,
PSČ,
jméno
apod.)
–
max
120
znaků
bez
diakritiky
3) Klient
(mobilní
telefon)
–
zadání
požadovaných
zpřesňujících
údajů
4) Server
obchodníka
–
Obdrží
zpřesňující
informace,
a
zašle
celkovou
částku
k
zaplacení
a) v
případě
že
je
to
možné
v
tuto
chvíli
je
nejvhodnější
chvíle,
kdy
se
provede
rezervaci
zboží
5) Mobito
systém
–
zaslání
požadavku
na
platbu
na
tel.
číslo
klienta
(nativní
notifikace,
USSD
notifikace)
6) Klient
(mobilní
telefon)
–
přijetí
a
autorizace
transakce
unikátním
PINem
Mobito
systém
–
ověření
transakce
a
notifikace
o
úspěšném
zaplacení
–
notifikace
klientovi
a
notifikace
webu
obchodníkovi.
MOPET
CZ,
a.
s.
Page
11
of
48
Confidential
document

12. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
sd MobitoCo...
Handset mBroker MerchantSystem
GetToMobitoCodeInput()
SendCode()
LookupCode()
GetMobitoCodeInfo()
GetMobitoCodeInfo Response()
DisplayChoices()
Choose(Choice, Amount)
validate choice and amount()
PreValidateMobitoCodeOrder(choice,
amount, text)
Reserve()
PreValidateMobitoCodeOrder response()
GenerateRequestForPayment()
RequestForPayment()
Authorisation()
RequestForPaymentConfirmation()
Confirmation()
PutReservedAsSold()
Jak
to
udělat
/
Nastavení
pro
platbu
1) Přihlášení
se
do
portálu
pro
obchodníky
–
pomocí
administrátorského
účtu,
který
obdržíte
při
podpisu
smlouvy
2) Kontaktování
Mopet
Backoffice
a) Nastavení
Branche
a
virtuálního
zaměstnance
typu
Mobito
code
b) Získání
technických
popisů
služeb(wsdl)
podle
kterých
vyvinete
na
Váš
server
služby
potřebné
pro
integraci
3) Zobrazení
vytvořeního
virtuálního
zaměstnance
4) SourceAuthKey,
Zobrazí
se
na
výpisu
detialů
Virtuálního
zaměstnance
a) SourceAuthKey
se
použije
při
odesílání
požadavku
na
bránu
a
slouží
namísto
hesla.
Generuje
systém
po
vytvoření
Virtuálního
Employee
5) Nastavení
URL
pro
kontaktování
MOPET
CZ,
a.
s.
Page
12
of
48
Confidential
document

13. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
a) U
virt.
zaměstnance
nastavte
adresu,
na
kterou
Vás
bude
kontaktovat
náš
systém
v
případě
kódu
b) Případně
zavolejte
web
service
ConfigureMobitoCodeListener
(za
pomoci
nastaveného
sourceAuthKey
–
zobrazeno
u
virt.
zaměstnance
a
SourceID
–
ID
Virt.
Zaměstnance.
6) Ve
smlouvě
vám
bude
přidělen
kód.
Podle
tohoto
kódu
systém
rozpozná,
že
se
jedná
o
Vaše
kódy,
proto
je
nutné,
aby
všechny
Vaše
kódy
začínali
na
tento
kód
a) Příklad
–
přiřazený
kód
je
123,
zákazník
je
přesměrován
k
vám
s
kódy
i) 123
ii) 12300001
iii) 123auto
apod.
iv) Ale
už
ne
001123
apod.
4.1. Testování
MobitoCode
Pro
testování
Mobito
Code
prosím
kontaktujte
podpora.obchodnika@mopetcz.cz
s
předmětem
„mobito
code
test“
a
domluvte
se
na
detailnější
podpoře
ohledně
testování.
5. Integrace
WebServices
požadavky
na
platbu
Popis
Pokud
chcete
využít
Mobito
jako
platební
metodu
spouštěnou
jiným
způsobem
nežli
klientem
přímo
z
mobilu
(mobito
Code)
nebo
pomocí
webového
rozhraní,
je
pro
Vás
připraveno
WebServices
rozhraní.
Toto
slouží
k
zakládání
požadavků
na
platbu
(Request
for
Payment)
a
zjišťování
stavu
transakcí.
Uživatelská
zkušenost:
-­‐ Klient
–
Nákup
na
pokladně
nebo
v
systému,
který
komunikuje
s
klientem
napřímo
nebo
vzdáleně
(jakýkoliv
informační
kanál,
který
umí
zjistit
od
klienta
ID
v
systému
Mobito
aby
mu
zaslal
požadavek
na
platbu)
Scénář
platby:
1) Klient
(obecně)
–
vyjádří
přání
nakoupit
zboží
u
obchodníka
a
dokončí
objednávku
2) Obchodník
–
Vyžádá
si
od
klienta
jeho
číslo
(telefonní,
nebo
Mobito
přezdívku),
to
zadá
do
svého
systému
a) Způsob
vyžádání
je
ponechán
na
procesní
a
technické
realizaci
obchodníka
může
se
jednat
například
o:
i) Zákazník
sdělí
pokladnímu
své
číslo
ii) Číslo
může
být
navázáno
na
věrnostní
kartu,
NFC
chip,
Čárový
kód
apod.
iii) Číslo
může
být
předáno
bezdrátově
pomocí
mobilní
aplikace,
mobilního
webu
3) Mobito
systém
–
zaslání
požadavku
na
platbu
na
tel.
číslo
klienta
(nativní
notifikace,
USSD
notifikace)
4) Klient
(mobilní
telefon)
–
přijetí
a
autorizace
transakce
unikátním
PINem
5) Mobito
systém
–
ověření
transakce
a
notifikace
o
úspěšném
zaplacení
–
notifikace
klientovi
a
notifikace
webu
obchodníkovi.
MOPET
CZ,
a.
s.
Page
13
of
48
Confidential
document

14. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
sd RFP Flow Timeouts
MerchantSystem mBroker USSD GW Handset
StartRFP(validity)
RFP Notification(Info)
AcceptReject()
InsertPIN()
PIN()
Notofication()
5.1. Testování
Web
Services
Testovací
transakce
-­‐
úspěch
1) Kontaktujte
podpora.obchodnika@mopetcz.cz
a
potvrďte
si,
připravenost
pro
testy
2) Vytvořit
zkušební
transakci
–
ve
vašem
systému
vytvořte
transakci
s
consumerID
606079502 a
po
web
services
kontaktujte
server
Mobito
na
adrese
https://
testapi.imobito.cz:9916/merchant/api
3) Zjistěte,
zda
Vám
webService
potvrdila
příem
požadavku
na
platbu
4) Nechte
Váš
systém
volat
CheckPaymentStatus
5) Počkejte,
až
náš
pracovník
potvrdí
transakci
6) Potvrďte
si,
že
CheckPaymentStatus
vrátil
stav
zaplaceno
Testovací
transakce
-­‐
neúspěch
7) Vytvořit
zkušební
transakci
–
ve
vašem
systému
vytvořte
transakci
s
consumerID
libovolné
vaše
číslo
a
po
web
services
kontaktujte
server
Mobito
na
adrese
https://testapi.imobito.cz:9916/merchant/api
8) Zjistěte,
zda
Vám
webService
potvrdila
příem
požadavku
na
platbu
9) Nechte
Váš
systém
volat
CheckPaymentStatus
10) Počkejte,
až
náš
pracovník
potvrdí
transakci
11) Potvrďte
si,
že
CheckPaymentStatus
vrátil
stav
zrušeno
Testovací
transakce
–
vypršení
časového
limitu
12) Kontaktujte
podpora.obchodnika@mopetcz.cz
a
potvrďte
si,
že
chcete
testovat
vypršení
časového
limitu
13) Vytvořit
zkušební
transakci
–
ve
vašem
systému
vytvořte
transakci
s
consumerID
602
356
797
a
po
web
services
kontaktujte
server
Mobito
na
adrese
https://
testapi.imobito.cz:9916/merchant/api
a) Stanovte
validity
na
co
nejnižší
14) Zjistěte,
zda
Vám
webService
potvrdila
příem
požadavku
na
platbu
MOPET
CZ,
a.
s.
Page
14
of
48
Confidential
document

15. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
15) Nechte
Váš
systém
volat
CheckPaymentStatus
16) Počkejte,
do
času,
který
jste
si
nastavili
v
parametru
„validity“
17) Potvrďte
si,
že
CheckPaymentStatus
vrátil
stav
nepotvrzeno
6. Integrace
Notifikace
Funkcionalita
notifikace
funguje
pro
všechny
typy
integrací.
Pro
správnou
funkcionalitu
nastavte
v
portálu
pro
obchodníky
u
virtuálního
zaměstnance
„notifikační
URL“.
Na
tuto
adresu
poté
přijde
z
našeho
serveru
GET
požadavek
s
parametry
platby
a
podepsán
algoritmem
uvedeným
v
kapitole
„Ověření
klienta“.
Alternativně
je
možné
nastavit
tento
parametr
pomocí
webové
služby
„ConfigurePaymentNotification“.
7. Integrace
WebServices
-­‐
Zjištění
stavu
transakcí
Webové
služby
nabízí
funkce
pro
zjištění
stavu
transakce,
získání
více
informací
o
úspěšně
proběhlé
transakci
a
Získání
detailních
informací
o
seznamu
transakcí.
Jsou
to
následující
funkce:
• CheckPaymentStatus
o Zjištění
stavu
aktuálně
prováděné
transakce
–
pro
rychlý
processing,
jsou
zde
všechny
požadavky
na
platbu
• GetTransactionDetail
o Zjištění
detailu
o
transakci
–
zde
je
možné
dohledat
pouze
úspěšně
dokončené
transakce
• GetTransactionReport
o Získání
seznamu
transakcí,
systém
v
této
funkci
také
vrátí
časově
omezený
link
na
stažení
vygenerovaného
CSV
souboru
pro
strojové
zpracování
transakční
historie.
8. Ověření
klienta
Metody
upozornění
na
platbu
(Notification
a
přesměrování
z
platební
brány)
obsahují
kromě
údajů
o
transakci
i
podpis.
Takto
může
obchodník
jednoduše
zjistit,
že
není
daná
informace
o
transakci
podvržená
a
není
nutné
další
zjišťování
výsledku
transakce.
8.1. Bezpečnostní
kód
V
portálu
pro
obchodníky
je
vždy
v
sekci
virtual
employee
vygenerován
bezpečnostní
kód.
Jedná
se
o
20
znaků
dlouhý
text,
který
se
poté
vkládá
do
algoritmu
jako
klíč
pro
zabezpečení.
Je
velmi
důležité,
aby
tento
kód
nebyl
nikdy
znám
nikomu
jinému
nežli
důvěryhodným
osobám
obchodníka
a
aby
nebylo
možné
jej
jednoduše
zjistit
například
zobrazením
zdrojového
kódu
na
webu
obchodníka
apod.
Bezpečnostní
kód
je
v
následujícím
algoritmu
uveden
pod
názvem
„presharedSecret“.
8.2. Algoritmus
Do
zprávy
se
přidává
jako
podpis
tzv
messageDigest.
Ten
je
vytvořen
jako
SHA256
hash
z
řetězce
parametrů
na
konci
doplněných
o
bezpečnostní
kód
–
presharedSecret.
Server
vypočte
tento
podpis
a
zašle
jej
spolu
s
notifikací,
nebo
přesměrováním.
Ověření
na
straně
obchodníka
probíhá
tak,
že
obchodník
stejným
způsobem
vypočte
podpis
ze
zaslaných
parametrů
a
bezpečnostního
kódu
a
výsledný
řetězec
porovná
s
přijatým
podpisem.
Jako
výstup
se
používá
„hexadecimální“
způsob
zápisu
s
malými
písmeny
a-­‐f.
MOPET
CZ,
a.
s.
Page
15
of
48
Confidential
document

16. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
V
programovacím
jazyce
může
vypadat
zápis
například
takto:
messageDigest = makeSHA256Hash(sourceId + sourceTxnId + invoiceId + sourceAuthKey +
paymentAmount + sourceTimestamp + presharedSecret+
TxnStatus)
Zápis
se
může
lišit
dle
programovacího
jazyka,
znak
„+“
v
tomto
zápise
značí
spojení
dvou
řetězců
za
sebe.
Například
v
jazyce
PHP
se
použije
znak
„.“(tečka).
Jednotlivé
parametry
jsou
popsány
v
příloze
A.
Mezi
hodnotami
nejsou
vkládány
žádné
mezery
ani
jiné
prázdné
znaky
a
hodnoty
jsou
včetně
všech
znaků
tak
jak
byly
zadány
(je
tedy
nutné
zahrnout
i
například
počáteční
nuly
u
některých
parametrů)
Výsledek
je
v
hexadecimálním
formátu
se
znaky
a-­‐f
označenými
malými
písmeny.
Pro
vyzkoušení
je
možné
využít
online
službu
pro
vypočítání
hash
např
na:
http://hash.online-­‐convert.com/sha256-­‐generator
(výsledek
ve
verzi
hex)
9. FAQs
1. Chci
zapojit
svůj
internetový
obchod
pro
platby
pomocí
Mobito
a. Nejlepší
variantou
je
využít
platební
tlačítko
i. S
Integrací
(takřka
online
vidíte,
že
bylo
zaplaceno
a
peníze
převedeny
na
Váš
účet)
2. Chci
zapojit
možnost
darovat
pevnou
částku,
nepotřebuji
okamžitě
vědět
o
všech
platbách
a. Nejlepší
variantou
je
platební
tlačítko,
nemusíte
použít
žádné
integrace,
stačí
pouze
stáhnout
kód,
který
začleníte
do
svých
stránek,
o
příchozích
platbách
se
dozvíte
buď
po
přihlášení
do
portálu
obchodníka,
nebo
mohou
chodit
upozornění
e-­‐mailem
3. Chci
zapojit
své
kamenné
prodejny
a. Nejlepší
variantou
je
využít
integraci
pomocí
webových
služeb
4. Můj
obchodní
plán
počítá
s
oslovováním
zákazníků
na
ulici
a
placení
na
místě
a. Nejlepší
variantou
je
integrace
Mobito
Code
MOPET
CZ,
a.
s.
Page
16
of
48
Confidential
document

17. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
10. Příloha
A
Technický
popis
rozhraní
(EN)
API Specifications for
3rd Party Integration
with the MOBITO
Payment System.
Table
of
Contents
Table
of
Contents
..................................................................................................................................
17
1
Introduction
.................................................................................
Error!
Bookmark
not
defined.
1.1
Pre-requisites for SOAP API Integration
...................
Error!
Bookmark
not
defined.
1.2
SOAP Resources
.................................................................
Error!
Bookmark
not
defined.
1.3
Currency ISO Codes
.........................................................
Error!
Bookmark
not
defined.
2
SOAP API Integration
...............................................................
Error!
Bookmark
not
defined.
2.1
Basics
.....................................................................................
Error!
Bookmark
not
defined.
2.2
SubmitRequestForPayment Method
...........................
Error!
Bookmark
not
defined.
2.3
ConfigurePaymentNotification Method
......................
Error!
Bookmark
not
defined.
2.4
CheckPaymentStatus Method
.......................................
Error!
Bookmark
not
defined.
2.5
GetTransactionDetail Method
........................................
Error!
Bookmark
not
defined.
2.6
GetTransactionReport Method
......................................
Error!
Bookmark
not
defined.
2.7
IssueRefund Method
.........................................................
Error!
Bookmark
not
defined.
3
MobitoCode Integration
...........................................................
Error!
Bookmark
not
defined.
3.1
Basics
.....................................................................................
Error!
Bookmark
not
defined.
3.2
ConfigureMobitoCodeListener
.......................................
Error!
Bookmark
not
defined.
3.3
GetMobitoCodeInfo Method
...........................................
Error!
Bookmark
not
defined.
3.4
PreValidateMobitoCodeOrder Method
........................
Error!
Bookmark
not
defined.
MOPET
CZ,
a.
s.
Page
17
of
48
Confidential
document

18. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
4
MOBITO PayNow Button Integration
..................................
Error!
Bookmark
not
defined.
4.1
How Integration With PayNow Button Works
.........
Error!
Bookmark
not
defined.
5
Notifications
.................................................................................
Error!
Bookmark
not
defined.
6
WSDL
..............................................................................................
Error!
Bookmark
not
defined.
MOPET
CZ,
a.
s.
Page
18
of
48
Confidential
document

19. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
1 Introduction
This document briefly describes the API specifications (for 3rd Party Application
Integration) provided as part of the MOBITO mobile payment solution being deployed by
Mopet across the Czech Republic.
Merchants and 3rd parties can integrate with the MOBITO platform in three different ways
depending on their preferences and technical proficiencies:
I. Direct platform-to-platform integration via the SOAP API specifications.
II. MobitoCode based integration via the SOAP API specifications.
III. Web based integration via HTTPS POST (using the MOBITO PayNow button).
1.1 Pre-requisites for SOAP API Integration
• Secure IP connection to the MOBITO application server (a VPN may also be
required depending on the merchant’s volume).
• Ability to initiate SOAP calls and process the responses accordingly.
• Ability to accept SOAP calls and return the expected responses
accordingly.
1.2 SOAP Resources
More technical information on the SOAP protocol is available at:
http://ws.apache.org/axis2/
http://www.w3.org/TR/soap/
http://msdn.microsoft.com/webservices/
http://sourceforge.net/projects/gsoap2
1.2.1 SOAP
Parameter
Direction
As a matter of convention throughout this document, the direction “OUT” is used
to indicate a parameter being sent from the MOBITO system to the merchant
system and the direction “IN” is used to indicate a parameter being received
from the merchant system by the MOBITO system.
1.3 Currency ISO Codes
More information on the various currency ISO codes is available at:
http://www.oanda.com/site/help/iso_code.shtml
MOPET
CZ,
a.
s.
Page
19
of
48
Confidential
document

20. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
MOPET
CZ,
a.
s.
Page
20
of
48
Confidential
document

21. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
2 SOAP API Integration
2.1 Basics
All merchants will need to connect to the MOBITO payment service on the
designated IP and port. All requests will need to conform to the SOAP protocol
standards based on the specifications (WSDL) supplied by Mopet.
The following SOAP methods are available for merchants at this time:
• SubmitRequestForPayment
• ConfigurePaymentNotification
• CheckPaymentStatus
• GetTransactionDetail
• GetTransactionReport
• IssueRefund
Each of the above methods requires certain source parameters (detailed below).
Source IDs (which are essentially ‘virtual employee’ ids) will have to be
provisioned in the Mopet databases before they can send any transactions.
2.2 SubmitRequestForPayment Method
2.2.1 Purpose
To initiate a request for payment with a configurable time validity. This requires
the merchant to provide a notification channel for receiving the result of the
transaction upon it’s conclusion or expiry.
2.2.2 Parameters
Parameter Name Type Direction Valid Value Mandatory Description
CustomerID String In Yes Fully qualified phone number of the
beneficiary customer or nicknumber
SourceID String In Yes Source Merchant’s ID
SourceTxnID String In Yes Source Merchant’s Internal Transaction ID
SourceRefID String In No This can be used by the merchant to
send a local terminal identifier or
reference ID for reconciliation and
reporting. It will merely be stored by the
MOBITO system and is not interpreted
in any manner.
TrxCode String In Text generated No If provided by merchant, this will be
by Merchant, sent by MOBITO to the customer as a
used to validate notification upon successful completion
MOPET
CZ,
a.
s.
Page
21
of
48
Confidential
document

22. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
purchase (ie. of the transaction.
eTicket code,
download code
etc.)
InvoiceID String In Yes Source Merchant’s Invoice ID
SourceAuthKey String In Yes Authorization key assigned to the
merchant by MOBITO
PaymentAmount String In String Yes The payment amount for the
representation transaction.
in ABC.YY
Currency String In Valid ISO code Yes The ISO code of the currency in which
the amount is being sent by the source
(e.g. CZK)
Timestamp String In Yes Source’s timestamp in the format -
YYYYMMDDHH24MISS
ProductDesc String In Upto 64 chars Yes Description of service/product
purchased by consumer
Validity String In Min: 30 secs Yes The time till which the request is valid
in the timestamp format –
Max: 60 days
from initiation YYYYMMDDHH24MISS
UseNotifyURL String In Y or N or D Yes If set to Y, the MOBITO system will send a
success or failure/expiry notification
message to this URL. If set to N, the
MOBITO system will not send a notification
to the merchant and the merchant will need
to call the CheckPaymentStatus method to
get the result of the transaction. If set to D
the merchant will be informed via email or
SMS. The merchant can set up this
preference using the self care portal or use
the API method in Section 2.4
(ConfigurePaymentNotification) to set this
up
RESPONSE ON TRANSACTION RECEIPT SUCCESS
MobitoTxnID String Out Yes Transaction ID generated by the
MOBITO system
MobitoMessage String Out No Additional message from MOBITO
RESPONSE ON TRANSACTION RECEIPT FAILURE
FaultCode String Out Yes Fault error code
FaultString String Out Yes Fault error message
2.2.3 Exceptions
In cases where the transaction is not successful, the following error codes will be
applicable:
MOPET
CZ,
a.
s.
Page
22
of
48
Confidential
document

23. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
Code Description
22010 Invalid or Missing CustomerID
22020 Invalid or Missing SourceID
22021 SourceID not permitted to perform transaction
22022 Invalid or Missing SourceAuthKey
22030 Invalid or Missing SourceTxnID
22035 Missing InvoiceID
22040 Invalid or Missing PaymentAmount
22050 Invalid or Missing Currency Code
22070 Invalid or Missing Timestamp
22090 Invalid or Missing ProductDesc
22100 Invalid or Missing Validity
22110 Invalid or Missing UseNotifyURL flag
22120 Remote system error <code>
22130 Remote system is offline, not available
22210 Cannot locate home network for CustomerID
22310 Duplicate transaction detected
22410 Request timed out
22510 Declined by customer
22999 Unknown error <additional message, if any>
2.3 ConfigurePaymentNotification Method
2.3.1 Purpose
To configure a notification channel for receiving request for payment result
notifications.
2.3.2 Parameters
Parameter Name Type Direction Valid Value Mandatory Description
SourceID String In Yes Source Merchant’s ID
SourceTxnID String In No Source Merchant’s Internal
Transaction ID. This is merely for the
MOPET
CZ,
a.
s.
Page
23
of
48
Confidential
document

24. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
merchant to be able to track multiple
configuration requests and has no
bearing on the actual configuration.
SourceAuthKey String In Yes Authorization key assigned to the
merchant by MOBITO
Timestamp String In Yes Source’s timestamp in the format -
YYYYMMDDHH24MISS
NotificationChannel String In U – URL Yes The notification channel which the
merchant wishes to use for receiving
E – Email transaction notifications. If the URL
option is chosen and the URL
specified by the merchant is down
when the MOBITO system is trying to
contact it, 2 retry attempts will be
made after which the response will be
sent over the default merchant email
ID and this parameter will be changed
to E. The format of the notification
response sent to the merchant’s URL
is described in section 2.3.3 below.
ChannelValue String In Yes The URL or the email address on
which the notification must be sent.
RESPONSE ON NOTIFICATION CONFIGURATION SUCCESS
MobitoTxnID String Out Yes Transaction ID generated by the
MOBITO system for the purpose of
tracking this configuration
MobitoMessage String Out No Additional message from MOBITO
RESPONSE ON NOTIFICATION CONFIGURATION FAILURE
FaultCode String Out Yes Fault error code
FaultString String Out Yes Fault error message
2.3.3 Notification
Format
&
Handling
In cases where the merchant chooses the “URL” as the notification channel, the
MOBITO system will send the following parameters via HTTP POST to the
designated URL:
Parameter Name Type Direction Valid Value Mandatory Description
TxnStatus String Out OK or FAILED Yes Status of the transaction in the
MOBITO system
MobitoTxnID String Out Yes Original Transaction ID generated by
the MOBITO system
MOPET
CZ,
a.
s.
Page
24
of
48
Confidential
document

25. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
CompletionTS String Out Yes The timestamp of the completion of
the transaction is reported here.
Format - YYYYMMDDHH24MISS
NewBalance String Out String Yes The balance of the merchant after
representation the completion of the transaction
in ABC.YY
SourceTxnID String Out Yes Source Merchant’s Transaction ID or
Reference Number or Tracking
Number
MessageDigest String Out Yes Secure digest based on a hash plus
shared secret which is returned back
by the MOBITO system to enable the
merchants to verify the integrity of
the original request.
The merchant must acknowledge receipt of the above request via a HTTP 200 OK
response. In the absence of such a response, the MOBITO system will retry twice
after which the URL notifications will be automatically disabled and notification
format will default to “email”.
2.3.4 MessageDigest
Verification
The responsibility for verification of the message digest rests with the merchant.
The shared secret used to generate the digest is provided to the merchant by
Mopet via an offline mechanism for additional security and must be kept
confidential at all times. The algorithm used for the digest verification is as
follows:
messageDigest = makeSHA256Hash(SourceId + SourceTxnId + InvoiceId + SourceAuthKey +
PaymentAmount + SourceTimestamp + PresharedSecret + TxnStatus)
There should be no spaces or other characters between the parameters and they
must be in the order listed.
Here's an online hash calculator for testing verification
http://hash.online-convert.com/sha256-generator
(hex version in result is to be used)
MOPET
CZ,
a.
s.
Page
25
of
48
Confidential
document

26. Dokument:
Autor:
Eva
Černíková
Vytvořen:
22.3.2012
Připojení
obchodníků
do
systému
Mobito
Status:
Draft
Změněn:
22.3.2012
2.3.5 Exceptions
In cases where the notification configuration is not successful, the following error
codes will be applicable:
Code Description
23020 Invalid or Missing SourceID
23021 SourceID not permitted to perform transaction
23022 Invalid or Missing SourceAuthKey
23070 Invalid or Missing Timestamp
23112 Invalid of Missing NotificationChannel
23114 Invalid or Missing ChannelValue
23120 Remote system error <code>
23130 Remote system is offline, not available
23999 Unknown error <additional message, if any>
2.4 CheckPaymentStatus Method
2.4.1 Purpose
To check the status of a previously submitted request for payment.
2.4.2 Parameters
Parameter Name Type Direction Valid Value Mandatory Description
SourceID String In Yes Source Merchant’s ID
SourceTxnID String In Yes Source Merchant’s Original Internal
Transaction ID
InvoiceID String In Yes Original Invoice ID
SourceAuthKey String In Yes Authorization key assigned to the
merchant by MOBITO
Timestamp String In Yes Source’s current timestamp in the
format - YYYYMMDDHH24MISS
MobitoTxnID String In Yes The transaction ID sent back by the
MOBITO system when the
transaction was originally submitted.
RESPONSE ON TRANSACTION QUERY SUCCESS
MOPET
CZ,
a.
s.
Page
26
of
48
Confidential
document