MOPET CZ a.s.
Připojení obchodníka do
systému Mobito
Příručka pro integraci
MOPET CZ a. s.
Page 1 of 76
v1.7
MOPET CZ a. s.
Page 2 of 76
v1.7
Obsah
1.
Manažerské shrnutí............................................................................................................. 5
1.1.
Představení společnosti Mopet a systému Mobito ............................................................ 5
1.2.
Možnosti připojení .............................................................................................................. 5
1.3.
Náročnost implementace:................................................................................................... 5
1.4.
K čemu slouží testovací prostředí: ...................................................................................... 6
1.5.
Testovací fáze: ..................................................................................................................... 6
1.6.
Poskytovaná podpora: ........................................................................................................ 6
2.
Slovníček pojmů .................................................................................................................. 7
2.1.
Používané termíny .............................................................................................................. 7
2.2.
Používané zkratky................................................................................................................ 7
3.
Platební tlačítko (nová verze).............................................................................................. 8
3.1.
Obecné předpoklady scénářů: ............................................................................................ 8
3.2.
Mobito Platební Tlačítko (Bez Integrace) ............................................................................ 8
3.3.
Mobito Platební Tlačítko (Integrace) .................................................................................. 9
3.4.
Požadavky na zobrazení platebního tlačítka ..................................................................... 13
4.
Testování platebního tlačítka ............................................................................................ 14
5.
Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka ..... 16
5.1.
Základní prvky Mobita na stránkách obchodníka ............................................................. 16
5.2.
Pravidla pro používání základních prvků ........................................................................... 16
6.
Ověření odpovědí ze systému ........................................................................................... 19
6.1.
Bezpečnostní kód .............................................................................................................. 19
6.2.
Algoritmus ......................................................................................................................... 19
7.
Integrace plateb spuštěných klientem (Mobito kód)........................................................ 20
7.1.
Testování Mobito kódu ..................................................................................................... 22
8.
Integrace WebServices požadavky na platbu ................................................................... 23
8.1.
Testování Web Services .................................................................................................... 24
9.
Integrace Notifikace .......................................................................................................... 26
10.
Integrace WebServices - Zjištění stavu transakcí ............................................................. 27
10.1. Stavy transakcí .................................................................................................................. 27
11.
Ověření odpovědí ze systému ........................................................................................... 28
11.1. Bezpečnostní kód .............................................................................................................. 28
11.2. Algoritmus ......................................................................................................................... 28
MOPET CZ a. s.
Page 3 of 76
v1.7
12.
FAQs .................................................................................................................................. 29
Příloha A Kód platebního tlačítka ................................................................................................ 30
Příloha B Technický popis rozhraní (EN)...................................................................................... 33
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.
MOPET CZ a. s.
Page 4 of 76
v1.7
1.
Manažerské shrnutí
1.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
Telefónica, T-Mobile, Vodafone, a bankovní domy Česká spořitelna, GE Money Bank, Raiffeisenbank
a UniCredit 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, jakou mají banku či
mobilního operátora. Mobitem půjde platit 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.
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
ve 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.
1.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.
1.3. Náročnost implementace:
Platební tlačítko:
Společnost MOPET CZ 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
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 osmihodinový 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
MOPET CZ a. s.
Page 5 of 76
v1.7
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 kód. 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.
1.4. K čemu slouží testovací prostředí:
Testovací prostředí poskytuje společnost MOPET CZ pro podporu integrace obchodníka na službu
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í.
1.5. Testovací fáze:
Společnost MOPET CZ standardně nabízí tří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“.
1.6. Poskytovaná podpora:
Společnost Mopet poskytuje podporu pro integraci obchodníka na mailové adrese:
[email protected] V případě jakýchkoliv problémů se můžete obrátit na tento mail.
MOPET CZ a. s.
Page 6 of 76
v1.7
2.
Slovníček pojmů
2.1. Používané termíny
Český název
Číslo obchodníka
Nebo
Číslo uživatele
(osobní):
Autentizační klíč
Parametr
SourceID
Popis
Číslo obchodního místa – Technického účtu, který je přidělen a
vkládá se jako identifikace obchodníka
SourceAuthKey
Tajný podpisový klíč
presharedSecret
Technický účet
Virtual Employee
Mobito číslo
Číslo transakce
Mobito
Číslo transakce
obchodníka
ConsumerID
MobitoTxnID
Slouží jako ověření, že můžete nakládat s daným účtem – pro
webové služby slouží v podstatě jako heslo pro požadavky a
mělo by s ním být tak nakládáno (neprozrazovat atp.) pro
Platební tlačítko se jedná pouze o verifikaci požadavku
Tajný klíč, který se vkládá do podpisového řetězce, aby
zabezpečil validitu odpovědi Mobita obchodníkovi
Účet obchodníka, který se nemůže přihlásit do portálu nebo
web terminálu, ale slouží pro integrační účely, přes tyto účty se
připojuje jak platební tlačítko, tak API integrace (viz SourceID)
Číslo uživatele, od kterého požadujete, aby zaplatil
Číslo transakce přidělené Mobitem – jednoznačný identifikátor
Číslo faktury, číslo
objednávky
Referenční číslo
InvoiceID
Časové razítko
Timestamp
Doba trvání platby
Validity
SourceTxnId
SourceRefID
Číslo transakce u obchodníka – většinou je identický s číslem
objednávky - InvoiceID, může být ale interní označení, které
slouží jen za účelem logování - například sekvence
Číslo, které slouží u obchodníka k identifikaci nákupu, slouží
jako např. variabilní symbol pro párování plateb
Referenční číslo (například číslo terminálu nebo pokladny) není
interpretováno naším systémem, slouží pouze pro reportovací
účely u obchodníka
Slouží k určení aktuálního času, aby se případně přišlo na chyby
způsobené špatným natavením času u obchodníka, nebo
rozdílné časové zóny – podle timestamp se poté určuje validity
Doba, po kterou má platnost požadavek na platbu, může být
min 30s ale také 30 dní. Do této doby má uživatel možnost
platbu potvrdit nebo zrušit, poté již nemá možnost zaplatit a
platba je považována za FAILED
2.2. Používané zkratky
Zkratka
WSDL
XML
RFP
MOPET CZ a. s.
Popis
Web Service Definition File – soubor popisující rozhraní webových služeb
Extensible Markup Language
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
Page 7 of 76
v1.7
3.
Platební tlačítko (nová verze)
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, pokud chcete jakkoliv automatizovaně reagovat na zaslanou
platbu pokračujte prosím další kapitolou.
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 telefonní čí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
MOPET CZ a. s.
Page 8 of 76
v1.7
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 v 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
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.
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 v Portálu pro obchodníky e-mail notifikaci o provedené platbě, abyste měli přehled
(příklady notifikačních emailů viz Příloha B – emailové notifikace o stavu transakce)
5) SourceAuthKey (Autentizační klíč) - obrazí se na výpisu detailů 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
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:
MOPET CZ a. s.
Page 9 of 76
v1.7
-
Klient – Nákup mobilem vzdáleně přes web nebo mobilní web obchodníka (registrovaný i
neregistrovaný klient webu)
Obchodník (e-shop) - Mobito jako platební metoda, integrace Mobito platebního tlačítko
na webu / mobilním webu obchodníka.
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 notifikuje o úspěšném zaplacení
Klient: zobrazení informace o stavu dokončení transakce a následné přesměrování na web
Obchodníka (Success/failed URL součástí, kterého je i ověřený podpis – viz kapitola 6. Ověření
odpovědí ze systému)
Obchodník:
 Zobrazení stavu dokončené transakce v Mobito portálu Obchodníka
 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“
 Mobito systém zašle z našeho serveru na vydefinovanou URL adresu obchodníka GET
požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole 6. Ověření
odpovědí ze systému1
 Mobito systém po zaplacení odešle na vydefinovaný email správu obsahující informace o
dokončených transakcích (viz Příloha B – emailové notifikace o stavu transakce) - součástí
předávané informace je i ověřený podpis – viz kapitola 7. Ověření
 API integrací je možné zavolat ChecktPaymentStatus, kde je uveden status platby (viz
kapitola 8. Integrace WebServices požadavky na platbu)
7) Klient (web obchodníka) – klientovi je zobrazena notifikace o úspěšném zaplacení zboží/služby,
poděkování případně další instrukce.
a) Obchodník - ověří platnost odpovědi brány pomocí ověření podpisu (viz kapitola 6. Ověření
odpovědí ze systému)
1
Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového
limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 1 minuta). Může tedy být drobný
časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 0:59 minut).
MOPET CZ a. s.
Page 10 of 76
v1.7
Alternativy scénáře
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
B) 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), obchodníkovi je tentostav sdělen na vydefinované
URL/email
C) Transakce dokončena, ale klient uzavřel Mobito platební bránu před přesměrováním na
web obchodníka
a. Obchodník může zjistit stav transakce v manuálně portálu pro obchodníky
b. v případě nastavení technického účtu (virtual employee), aby po zaplacení vyvolal
URL adresu obchodníka na, kterou předá informace o dokončených transakcích
(zaplaceno/selhalo s důvodem selhání) bude tato informace předána i v případě, kdy
klient uzavře webovou bránu před přesměrováním na web obchodníka
c. v případě nastavení technického účtu (virtual employee), aby po zaplacení odeslal na
vydefinovaný email správu obsahující informace o dokončených transakcích, bude
tento email zaslán i v případě, kdy klient uzavře webovou bránu před přesměrováním
na web obchodníka
d. V případě API integrace je možné zavolat ChecktPaymentStatus, kde je uveden
status platby i v případě, kdy klient uzavře webovou bránu před přesměrováním na
web obchodníka
D) Notifikace o dokončené transakce není možné na vydefinované URL doručit
Mobito systém se pokusí na vydefinované URL informaci o dokončené transakci předat
celkem 3 krát (volání po 3 sekundách). V případě že i třetí volání selže, pošle Mobito systém
informace o dokončené transakci automaticky na emailovou adresu vydefinovanou jako
kontaktní email daného technického účtu (virtual emploee)
E) Notifikace o dokončené transakce není možné na vydefinované URL doručit a technický
účet nemá vydefinovanou kontaktní emailovou adresu
V takovém případě pošle Mobito systém informace o dokončené transakci automaticky na
emailovou adresu vydefinovanou jako kontaktní email Obchodníka.
Jak to udělat / Nastavení pro platbu
MOPET CZ a. s.
Page 11 of 76
v1.7
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 obchodu – 1 Virtuálního zaměstnance přímo pod
svým účtem obchodníka nebo pod některou Vaší pobočkou
b) WWW adresu obchodu, kterou chcete, aby se zobrazila na Mobito Bráně vložte do
parametru Název Virtuálního zaměstnance
c) Při notifikaci o dokončené transakce vyvoláním URL nastavení URL notifikace (v tomto
případě vyplňte pro potřeby alternativního scénáře u daného technického účtu i pole s pro
kontaktní email)
d) Při notifikaci o dokončené transakce zasláním emailu nastavte emilovou adresu, kam budou
notifikace zasílané
3) Nastavení adres pro přesměrování na bránu
a) U Virtuální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 detailů 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í.
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í)
Schéma rozhraní
MOPET CZ a. s.
Page 12 of 76
v1.7
sd PaymentButton
MerchantSystem
MobitoPaymentGateway
Handset
POST/GET Redirect()
Enter MobitoID()
SendRFP()
PIN()
Redirect()
3.4. Požadavky na zobrazení platebního tlačítka
Ve chvíli implementace požádejte na e-mail [email protected] 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)
MOPET CZ a. s.
Page 13 of 76
v1.7
4.
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 [email protected]
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
V odpovědi obdržíte nejen datum a čas možného testování, ale také číslo klienta se kterým je možné
testovat (který Vám transakci potvrdí, zruší, či nechá vypršet)
Testovací transakce – úspěch
1) Kontaktujte [email protected] 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) Zkontrolujte, zda se Vám zobrazilo tlačítko správně (nikoliv jako kód <form…)
ii) Zkontrolujte, 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 pro potvrzení (obdržíte od společnosti MOPET CZ)
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 pro zrušení (obdržíte od společnosti MOPET CZ)
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
MOPET CZ a. s.
Page 14 of 76
v1.7
Testovací transakce – vypršení časového limitu
10) Kontaktujte [email protected] 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 pro vypršení (obdržíte od společnosti MOPET CZ)
14) Vyčkejte do vypršení časového limitu
a) Zkontrolujte přijaté parametry
MOPET CZ a. s.
Page 15 of 76
v1.7
5.
Pravidla pro integraci platební metody Mobito na
webových stránkách obchodníka
5.1. Základní prvky Mobita na stránkách obchodníka
1. Logo Mobita
2. Popisný text o Mobitu
5.2. Pravidla pro používání základních prvků
1. Logo Mobita
Formát loga
 Použití loga Mobita se vždy řídí seznamem povolených velikostí, které jsou k dispozici
v grafickém balíku. Grafický balík log je zasílaný spolu s integračním manuálem pro
obchodníka.

V případě, že z jakéhokoliv důvodu nemůžete použit ani jednu variantu, kontaktujte
technickou podporu na e-mailové adrese: [email protected]
Ukázka loga Mobita
Logo je dostupné v následujících velikostech:
86 x 26 px
112 x 34 px
132 x 40 px
154 x 46 px
176 x 54 px
Pravidla pro použití loga
 POZOR! Logo Mobita nemůže být nikdy použito jako tlačítko, které spouští akci. Při
přesměrování klienta na platební bránu Mobito se očekává použití standardního
neutrálního tlačítka, které je stejné pro všechny ostatní platební metody a vyzívá
klienta k akci. Tato tlačítka mají zpravidla název „Zaplatit, Zaplatit přes platební
bránu, Pokračovat“ a podobně. Toto tlačítko doporučujeme doplnit o průvodní text
(viz dále), který informuje zákazníka o tom, co bude následovat po kliknutí. Po
kliknutí je zákazník přesměrován na platební bránu Mobita, kde uskuteční platbu.

MOPET CZ a. s.
Při výběru Mobita, jako platební metody pro platbu, může být použité logo Mobita,
ale vždy jen v doprovodu radio buttonu, který označuje výběr platební metody.
Page 16 of 76
v1.7
V takovém případě logo nemůže být klikatelné a odkazovat například na stránky
Mobita, ale musí působit jako označení platební metody.

Výběr Mobita jako platební metody nemusí obsahovat logo a to v případě, že seznam
ostatních platebních metod neobsahuje jejich loga. V takovém případě musí být
platební metoda označena textově názvem služby s velkým začátečním písmenem
„Mobito“.

V případě, že je platební metoda doplněna o krátký popisný text, doporučujeme
následující spojení:
 Platba Mobitem
 Zaplať Mobitem
 Zaplať mobilem přes Mobito
Umístění loga
 Logo Mobita musí být uvedeno jako identifikátor platební metody u ostatních
platebních metod, které může zákazník použít na stránkách obchodníka. Zpravidla
jsou loga umístěna v zápatí stránek, které zákazník vidí na úvodní stránce webshopu
a při výběru platební metody v košíku objednávky.

V případě, že má obchodník k dispozici samostatnou stránku, která uvádí seznam
všech platebních metod, musí být Mobito identifikované na této stránce logem a
krátkým popisným textem.
Popisný text o Mobitu
Vzhledem k tomu, že Mobito je nová platební metoda na trhu, je vhodné zákazníky obeznámit
stručným popisem o této metodě. Připravili jsme pro vás 3 různé varianty popisného textu, který
MOPET CZ a. s.
Page 17 of 76
v1.7
můžete využít na svých stránkách. Krátké verze popisných textů doporučujeme použít na
místech, kde chcete jen stručně informovat zákazníka o Mobitu. Delší formát je vhodný pro popis
platební metody na stránkách, které věnujete popisu všech platebních metod.
Formáty textu:
 S – krátký formát
 M – středný formát
 L – delší formát

S – krátký formát
o Mobito – peníze v mobilu
o Mobito jsou peníze v mobilu – nová služba umožňující platit mobilem.

M – střední formát
Mobito jsou peníze v mobilu – nová služba umožňující platit mobilem. Mobito stačí
jednoduše připojit k běžnému účtu nebo k platební kartě. S Mobitem lze bezpečně platit za
zboží a služby, posílat peníze z jednoho mobilu na druhý nebo dobíjet kredit telefonu. Více
informací na www.mobitoplatito.cz

L – delší formát
Mobito jsou peníze v mobilu – nová služba umožňující platit mobilem. Mobito stačí
jednoduše připojit k běžnému účtu nebo k platební kartě. S Mobitem lze bezpečně platit za
zboží a služby, posílat peníze z jednoho mobilu na druhý nebo dobíjet kredit telefonu. Placení
probíhá okamžitě. Mobitem může zaplatit každý – nehledě na to, jaký typ telefonu vlastní
a jakou banku či mobilního operátora využívá. Mobito je lokální řešení pro platby mobilem.
Stojí za ním společnost MOPET CZ společně se čtyřmi bankami (Česká spořitelna, GE Money
Bank, Raiffeisenbank, UniCredit Bank) a všemi mobilními operátory (Telefónica O2, T-Mobile,
Vodafone). Registrace a více informací na www.mobitoplatito.cz

V případě dalších dotazů prosím kontaktujte technickou podporu na e-mailové adrese
[email protected]
Upozornění:
Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení
časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 1 minuta). Může
tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 0:59
minut).
MOPET CZ a. s.
Page 18 of 76
v1.7
6.
Ověření odpovědí ze systému
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.
6.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“.
6.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.
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
B.
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)
MOPET CZ a. s.
Page 19 of 76
v1.7
7.
Integrace plateb spuštěných klientem (Mobito kód)
Popis
Pokud chcete využít mobilní telefon klientů jako nákupní prostředí, je možné integrovat je pomocí
rozhraní Mobito kódu.
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 20 of 76
v1.7
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 detailů 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
MOPET CZ a. s.
Page 21 of 76
v1.7
5) Nastavení URL pro kontaktování
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.
7.1. Testování Mobito kódu
Pro testování Mobito kódu prosím kontaktujte [email protected] s předmětem
„mobito code test“ a domluvte se na detailnější podpoře ohledně testování.
MOPET CZ a. s.
Page 22 of 76
v1.7
8.
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 kód) 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.
a) Alternativně – Obchodník – dotazuje Mobito systém funkcí „CheckPaymentStatus“
MOPET CZ a. s.
Page 23 of 76
v1.7
sd RFP Flow Timeouts
MerchantSystem
mBroker
USSD GW
Handset
StartRFP(validity)
RFP Notification(Info)
AcceptReject()
InsertPIN()
PIN()
Notofication()
8.1. Testování Web Services
Testovací transakce – úspěch
1) Kontaktujte [email protected] 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
http://testapi.imobito.cz:9916/mopet/services/mobitoapi?wsdl
3)
4)
5)
6)
Zjistěte, zda Vám webService potvrdila příjem požadavku na platbu
Nechte Váš systém volat CheckPaymentStatus
Počkejte, až náš pracovník potvrdí transakci
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
http://testapi.imobito.cz:9916/mopet/services/mobitoapi?wsdl
8) Zjistěte, zda Vám webService potvrdila příjem 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
MOPET CZ a. s.
Page 24 of 76
v1.7
Testovací transakce – vypršení časového limitu
12) Kontaktujte [email protected] 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
http://testapi.imobito.cz:9916/mopet/services/mobitoapi?wsdl
a) Stanovte validity na co nejnižší
14) Zjistěte, zda Vám webService potvrdila příjem požadavku na platbu
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
MOPET CZ a. s.
Page 25 of 76
v1.7
9.
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“.
Upozornění:
Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení
časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 5 minut). Může
tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 4:59
minut).
MOPET CZ a. s.
Page 26 of 76
v1.7
10. 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.


10.1.
Stavy transakcí
Transakce může za dobu svého života nabývat několika stavů, pro Obchodníka jsou viditelné tyto:
o PENDING – transakce čeká na zpracování
o OK – transakce je v pořádku zaplacena
o FAILED – transakce zamítnuta, či končící chybou
Zaslání Platebního požadavku
PENDING
Klient Zadá PIN po expiraci
klient zadá PIN v době expirace
[NE]
Sběrný proces expirovaných transakcí
[bez interakce]
[ANO]
[č ekání ve stavu
PENDING]
[zadá PIN]
validace
[validace OK]
[Proběhl]
[neprošlo validací]
OK
FAILED
konec
MOPET CZ a. s.
Page 27 of 76
v1.7
11. Ověření odpovědí ze systému
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.
11.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“.
11.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.
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
B.
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)
MOPET CZ a. s.
Page 28 of 76
v1.7
12. 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 29 of 76
v1.7
Příloha A Kód platebního tlačítka
Formulář standardního tlačítka:
Do svých stránek zkopírujte následující kód a vyplňte žluté prvky. Jejich význam je popsán níže.
<form action="ADRESA" method="post">
<input
<input
<input
<input
TRANSAKCE"
<input
REFERENCI”
<input
<input
KEY" />
<input
<input
<input
<input
<input
</form>
type="hidden"
type="hidden"
type="hidden"
type="hidden"
/>
type=”hidden”
/>
type="hidden"
type="hidden"
name="cmd" value="_xclick" />
name="CustomerID" value="ČÍSLO KLIENTA" />
name="SourceID" value="VAŠE MERCHANT ID" />
name="SourceTxnID" value="VAŠE ČÍSLO
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type="submit"
name="PaymentAmount" value="ČÁSTKA" />
name="Currency" value="CZK" />
name="Timestamp" value="TIMESTAMP" />
name="ProductDesc" value="PRODUCT" />
value="Zaplatit" />
name=”SourceRefID” value=”VAŠE ČÍSLO PRO
name="InvoiceID" value="ČÍSLO FAKTURY" />
name="SourceAuthKey" value="SOURCE AUTH
Formulář tlačítka na mobilním webu
Platební brána má vlastní metodu rozpoznání, zda k ní uživatel přistupuje z mobilního zařízení, nebo
ze zařízení s větší obrazovkou. Přesto pokud chcete vynutit zobrazení mobilní části stránky, nastavte
kód - viz níže (změna oproti standardnímu je v zelené části):
<form action="ADRESA" method="post">
<input
<input
<input
<input
TRANSAKCE"
<input
REFERENCI”
<input
<input
KEY" />
<input
<input
<input
<input
<input
<input
</form>
MOPET CZ a. s.
type="hidden"
type="hidden"
type="hidden"
type="hidden"
/>
type=”hidden”
/>
type="hidden"
type="hidden"
name="cmd" value="_xclick" />
name="CustomerID" value="ČÍSLO KLIENTA" />
name="SourceID" value="VAŠE MERCHANT ID" />
name="SourceTxnID" value="VAŠE ČÍSLO
name="InvoiceID" value="ČÍSLO FAKTURY" />
name="SourceAuthKey" value="SOURCE AUTH
type="hidden"
type="hidden"
type="hidden"
type="hidden"
type=”hidden”
type="submit"
name="PaymentAmount" value="ČÁSTKA" />
name="Timestamp" value="TIMESTAMP" />
name="ProductDesc" value="PRODUCT" />
name="Currency" value="CZK" />
name=”forceMobile” value=”on”/>
value="Zaplatit" />
name=”SourceRefID” value=”VAŠE ČÍSLO PRO
Page 30 of 76
v1.7
Vysvětlení prvků:
ADRESA: nastavení adresy platebního tlačítka.
Pro testy prosím nastavte
https://platba-mopet.moremagic.com/cui/mwallet/paymentButton
Pro produkční prostředí prosím nastavte:
https://platba.mobitoplatito.cz/cui/mwallet/paymentButton
ČÍSLO KLIENTA – pokud znáte mobil na klienta, můžete mu jej vložit do tohoto prvku, na bráně se
toto číslo předvyplní. Starndarně nechte prázdné
VAŠE MERCHANT ID – číslo uvedené v portálu pro obchodníky jako číslo zaměstnance u Virtuálního
zaměstnance kterého jste si vytvořili
VAŠE ČÍSLO TRANSAKCE – číslo vaší transakce, nejlépe pokud je to sekvenční číslo, ale pokud
nepotřebujete párovat platby, pak může zůstat stejné
VAŠE ČÍSLO PRO REFERENCI – například číslo objednávky, systém si udržuje pro Vás toto číslo a
poskytne vám jej v detailu transakce, nijak s ním dále nenakládá
ČÍSLO FAKTURY – vaše číslo faktury klientovi, ponechává se pro referenci a dohledání transakci – je
zobrazeno klientovi v jeho výpise
SOURCE AUTH KEY – bezpečnostní kód, naleznete na stejném místě u Virutálního zaměstnance jako
Merchant ID
ČÁSTKA – částka ke stržení klientovi
TIMESTAMP – aktuální čas ve formátu YYYYMMDDHH24MISS – např 20111002122555
NapřPro 2.11.2011 12:25:55 hodin – všechny časy jsou ve 24hodinovém formátu, všechny čísla jsou
doplňovaná 0 pokud jsou pouze jednociferná.
Tato timestamp se použije pro počítání zabezpečeného podpisu a provaší referenci, náš systém ji
neinterpretuje. Pokud Váš systém neumí generovat takovéto timestamp, můžete použít statickou
hodnotu nastavenou např na den spuštění (vhodné např. pro tlačítka staticky vložená do stránek
obchodních sdružení apod.)
PRODUCT – název který se zobrazí v transakční historii – pokud nemůžete automaticky generovat
názvy, nastavte pevny text například název obchodu nebo „Nakup <název obchodu>“
Tlačítko
<input type="submit" value="Zaplatit" />
Název tlačítka můžete měnit změnou textu v prvku „value“
Ponechte následující prvky, tak jak jsou
MOPET CZ a. s.
Page 31 of 76
v1.7
<input type="hidden" name="cmd" value="_xclick" />
<input type="hidden" name="Currency" value="CZK" />
MOPET CZ a. s.
Page 32 of 76
v1.7
Příloha B Technický popis rozhraní (EN)
API Specifications for
3rd Party Integration
with the MOBITO
Payment System.
Table of Contents
Table of Contents ........................................................................................................................ 33
1
Introduction ...................................................................................................................... 35
1.1
Pre-requisites for SOAP API Integration............................................................................ 35
1.2
SOAP Resources ................................................................................................................ 35
MOPET CZ a. s.
Page 33 of 76
v1.7
1.3
Currency ISO Codes ........................................................................................................... 36
2
SOAP API Integration......................................................................................................... 37
2.1
Basics ................................................................................................................................. 37
2.2
SubmitRequestForPayment Method ................................................................................ 37
2.3
ConfigurePaymentNotification Method ........................................................................... 42
2.4
CheckPaymentStatus Method........................................................................................... 45
2.5
GetTransactionDetail Method .......................................................................................... 49
2.6
GetTransactionReport Method ......................................................................................... 52
2.7
IssueRefund Method ......................................................................................................... 55
3
MobitoCode Integration ................................................................................................... 58
3.1
Basics ................................................................................................................................. 60
3.2
ConfigureMobitoCodeListener.......................................................................................... 60
3.3
GetMobitoCodeInfo Method ............................................................................................ 63
3.4
PreValidateMobitoCodeOrder Method ............................................................................ 66
4
MOBITO PayNow Button Integration................................................................................ 69
4.1
How Integration With PayNow Button Works .................................................................. 69
5
Notifications ...................................................................................................................... 76
MOPET CZ a. s.
Page 34 of 76
v1.7
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.
II.
III.
Direct platform-to-platform integration via the SOAP API specifications.
MobitoCode based integration via the SOAP API specifications.
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.
MOPET CZ a. s.
Page 35 of 76
v1.7
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 36 of 76
v1.7
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
CustomerID
String
In
MOPET CZ a. s.
Valid Value
Page 37 of 76
Mandatory
Description
Popis
Yes
Fully qualified phone number of the
beneficiary customer or nicknumber
Číslo, které zadal pokladní do pokladního
systému (9 místné telefonní číslo nebo
Mobito číslo)
v1.7
SourceID
String
In
Yes
Source Merchant’s ID
Identifikátor technického účtu, které Vám
přidělí Mobito (lze zjistit v portálu
obchodníka), typicky je přiděleno jedno
číslo pro jednu integraci obchodníka (např.
na jednu síť prodejen, případně pro jednu
pobočkovou síť).
SourceTxnID
String
In
Yes
Source Merchant’s Internal Transaction ID
Zde uveďte Vaše číslo transakce. Může být
spjato s objednávkou
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.
Zde uveďte číslo pokladny – pro pozdější
identifikaci místa prodeje a pro pokladní
uzávěrku. Toto číslo může být například
složeno následovně:
TrxCode
String
In
No
If provided by merchant, this will be
sent by MOBITO to the customer as a
notification upon successful completion
of the transaction.
Textem v tomto určujete, co je posláno
klientovi po úspěšném zaplacení.
InvoiceID
String
In
Yes
Source Merchant’s Invoice ID
Zde uveďte Vaše číslo transakce,
objednávky nebo číslo dokladu (dodatečný
identifikátor). Může být plněno stejně jako
SourceTxnID.
SourceAuthKey
String
In
Yes
Authorization key assigned to the
merchant by MOBITO
Zde uveďte autentizační klíč, který Vám
přidělí Mopet po registraci technického
účtu. Autentizační klíč je přidělen ke
každému účtu se SourceID.
MOPET CZ a. s.
Text generated
by Merchant,
used to validate
purchase (ie.
eTicket code,
download code
etc.)
Page 38 of 76
v1.7
PaymentAmount
String
In
String
representation
in ABC,YY
Yes
The payment amount for the
transaction.
Částka transakce včetně DPH, nemůže
překročit limit pro jednu transakci (10000
Kč)
Currency
String
In
Valid ISO code
Yes
The ISO code of the currency in which
the amount is being sent by the source
Plňte konstantu CZK
Yes
Source’s timestamp in the format YYYYMMDDHH24MISS
Uveďte Váš aktuální systémový čas / čas
pokladny od kterého se má počítat
expirace transakce.
Yes
Description of service/product
purchased by consumer
Tento údaj je zobrazen klientovi v detailu
po přijetí platby. Doporučujeme uvádět
prodejní místo - název pobočky, kde klient
platí, např. Praha 9 – Vysočany, Brno atd.
(e.g. CZK)
Timestamp
String
In
ProductDesc
String
In
Upto 64 chars
Pozn: název obchodníka, u kterého se platí
je klientovi zobrazen vždy, není nutné ho
zde uvádět
Validity
String
In
Min: 30 secs
Yes
Max: 60 days
from initiation
The time till which the request is valid
in the timestamp format –
YYYYMMDDHH24MISS
Uveďte zde čas, kdy má platba vypršet (a
nebude možné ji poté zaplatit). K Vašemu
aktuálnímu systémovému času přičtěte
např. 2 minuty a vypočtěte Validity
timestamp.
Doporučení pro čas expirace pro pokladny:
2 minuty, pro restaurace 5 minut, pro taxi
služby 5 minut, pro platbu faktur 14 dní.
UseNotifyURL
MOPET CZ a. s.
String
In
Y or N or D
Page 39 of 76
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
v1.7
Nastavte na N - , notifikace bude řešena
voláním ChekPaymentStatus.
Pokud nastavíte na Y, je nutné nastavit
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
Notifikační URL.
Mopet vrátí jako odpověď ID
vygenerované transakce v Mobitu.
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
2.2.3
FaultCode
String
Out
Yes
Fault error code
Kód chyby – viz níže
FaultString
String
Out
Yes
Fault error message
Text doplňující chybu – odpovídá
sloupci Description v následující
kapitole
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
Vysvětlení
22010
Invalid or Missing CustomerID
Takový zákazník nemá Mobito – základní rozpoznání zda lze
poslat na klienta účet k zaplacení
22020
Invalid or Missing SourceID
Není vyplněnou číslo technického účtu
22021
SourceID not permitted to perform transaction
Tento technický účet nemůže vkládat účty k zaplacení
MOPET CZ a. s.
Page 40 of 76
v1.7
22022
Invalid or Missing SourceAuthKey
Chybí povinné pole SourceAuthKey
22030
Invalid or Missing SourceTxnID
Chybí povinné pole SourceTxnId
22035
Missing InvoiceID
Chybí pole InvoiceID – nepoužívá se
22040
Invalid or Missing PaymentAmount
Chybí povinné pole Částka, nebo je ve špatném formátu
(nejčastější chyba - desetinná tečka)
22050
Invalid or Missing Currency Code
Chybí kód měny (CZK)
22070
Invalid or Missing Timestamp
Chybí povinné pole čas na serveru obchoníka
22090
Invalid or Missing ProductDesc
Chybí pole ProductDesc – nepoužívá se
22100
Invalid or Missing Validity
Chybí povinné pole Validity, nebo je v minulosti, nebo je
moc krátké
22110
Invalid or Missing UseNotifyURL flag
Chybí povinné pole „používat notifikační URL“
22120
Remote system error <code>
Obecná chyba v systému, nejčastěji špatná kombinace
SourceID/SourceAuthKey
22130
Remote system is offline, not available
Interní chyba systému
22210
Cannot locate home network for CustomerID
Interní chyba systému – uživateli nelze přiřadit operátora
(přenositelnost čísel)
22310
Duplicate transaction detected
Interní chyba systému, duplicitně zadaná transakce
22410
Request timed out
Interní chyba systému – požadavek vypršel
22510
Declined by customer
22999
Unknown error <additional message, if any>
MOPET CZ a. s.
Page 41 of 76
Neznámá chyba, nejčastěji pokud jsou z XML vypštěny
nepovinné parametry úplně (prvek musí v požadavku být,
ale může nabývat prázdných hodnot)
v1.7
2.3
2.3.1
ConfigurePaymentNotification Method
Purpose
To configure a notification channel for receiving request for payment result notifications.
2.3.2
Parameters
Parameter Name
Type
Direction
SourceID
String
SourceTxnID
Valid Value
Mandatory
Description
In
Yes
Source Merchant’s ID
String
In
No
Source Merchant’s Internal
Transaction ID. This is merely for the
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
Yes
The notification channel which the
merchant wishes to use for receiving
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
U – URL
E – Email
MOPET CZ a. s.
Page 42 of 76
v1.7
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
2.3.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
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:
MOPET CZ a. s.
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
CompletionTS
String
Out
Yes
The timestamp of the completion of
the transaction is reported here.
Page 43 of 76
v1.7
Format - YYYYMMDDHH24MISS
NewBalance
String
Out
SourceTxnID
String
MessageDigest
String
String
representation
in ABC.YY
Yes
The balance of the merchant after
the completion of the transaction
Out
Yes
Source Merchant’s Transaction ID or
Reference Number or Tracking
Number
Out
Yes
Secure digest based on a hash plus
presharedSecret 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
MOPET CZ a. s.
Page 44 of 76
v1.7
(hex version in result is to be used)
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
2.4.1
CheckPaymentStatus Method
Purpose
To check the status of a previously submitted request for payment.
MOPET CZ a. s.
Page 45 of 76
v1.7
2.4.2
Parameters
Parameter Name
Type
Direction
SourceID
String
SourceTxnID
Mandatory
Description
Popis
In
Yes
Source Merchant’s ID
Identifikátor technického účtu, který
Vám přidělí Mobito (lze zjistit v portálu
obchodníka), typicky je přiděleno jedno
číslo pro jednu integraci obchodníka
(např. na jednu síť prodejen).
String
In
Yes
Source Merchant’s Original Internal
Transaction ID
Identifikace transakce – identické
SourceTxnID jako bylo použito při volání
SubmiRequestForPayment.
InvoiceID
String
In
Yes
Original Invoice ID
Identifikace transakce – identické
InvoiceID jako bylo použito při volání
SubmiRequestForPayment.
SourceAuthKey
String
In
Yes
Authorization key assigned to the
merchant by MOBITO
Zde uveďte autentizační klíč, který Vám
přidělí Mopet po registraci technického
účtu. Autentizační klíč je přidělen ke
každému účtu se SourceID.
Timestamp
String
In
Yes
Source’s current timestamp in the
format - YYYYMMDDHH24MISS
Uveďte Váš aktuální systémový čas.
MobitoTxnID
String
In
Yes
The transaction ID sent back by the
MOBITO system when the
transaction was originally submitted.
Uveďte číslo transakce, které Mopet
vrátil jako odpověď na volání
SubmitRequestForPayment
Can be set to a case sensitive value
of “NOTAVAILABLE” by PayNow
Button merchants when they don’t
have the transaction id available
(e.g. user closed the browser, etc).
Pokud nemáte k dispozici MobitoTxnId
(platební tlačítko ve stavu kdy se
uživatel nevrátí) je možné zavolat
s hodnotou NOTAVAILABLE a transakce
se dohledá pomocí SourceTxnId (je
nutné, aby SourceTxnId bylo v daném
MOPET CZ a. s.
Valid Value
Page 46 of 76
v1.7
dni jednoznačné, jinak funkce vrátí
chybu)
RESPONSE ON TRANSACTION QUERY SUCCESS
TxnStatus
String
Out
OK or FAILED
or PENDING
Yes
Status of the transaction in the
MOBITO system
Odpověd – aktuální stav transakce:
-
-
-
OK – transakce zaplacena
klientem. Lze vytisknout
doklad a předat zboží / službu
FAILED – trasnakce selhala
(vypršela nebo byla
odmítnuta)
PENDING – transakce čeká na
zaplacení
Pozn: Expirované transakce jsou
označovány hromadně systému pouze
každou 1 minutu, Pokud chcete platbu
ukončit ihned po expiraci, pak je možné
expiraci provést na základě dosažení
času uvedeného v atributu Validity.
MobitoTxnID
String
Out
Yes
Original Transaction ID generated by
the MOBITO system
Odpověď – číslo Mobito transakce
CompletionTS
String
Out
No
If the TxnStatus is OK or FAILED,
then the timestamp of the completion
of the transaction is reported here.
Format - YYYYMMDDHH24MISS
Odpověď – čas uzavření transakce
v Mobito systému (pouze v případě OK a
FAILED)
NewBalance
String
Out
No
The balance of the merchant after
the completion of the transaction
Odpověď – stav účtu po ukončení
transakce
SourceTxnID
String
Out
Yes
Source Merchant’s Original Internal
Odpověď – Vaše číslo transakce
MOPET CZ a. s.
String
representation
in ABC.YY
Page 47 of 76
v1.7
Transaction ID
SourceRefID
String
Out
No
If sent by the merchant in the original
request, this will be returned as is.
Odpověď – číslo pokladny
RESPONSE ON TRANSACTION QUERY FAILURE
2.4.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Note to statuses
Status returned can be OK or FAILED or PENDING. In case of expired transaction system is processing every 5 minutes (subject to change in future) all expired
transactions. In this case the transaction can return status PENDING even though the validity has expired. The status will return FAILED after the above mentioned processing.
If the consumer tries to pay after expiration the transaction is declined and call to this function returns FAILED right away.
2.4.4
Exceptions
In cases where the call to CheckPaymentStatus is not successful, the following error codes will be applicable:
Code
Description
Popis chyby
24020
Invalid or Missing SourceID
Není zadané SourceID, nebo tento účet není technický účet
24021
SourceID not permitted to perform transaction
Nemáte právo provést tuto operaci (např:jiný typ
technického účtu)
24022
Invalid or Missing SourceAuthKey
Špatný Autorizační klíč
24030
Invalid or Missing SourceTxnID
Nezadaný povinný prvek SourceTxnId
24035
Missing InvoiceID
Nezadaný povinný prvek InvoiceID
MOPET CZ a. s.
Page 48 of 76
v1.7
24070
Invalid or Missing Timestamp
Nezadaný povinný prvek Timestamp
24080
Missing MobitoTxnID
Nezadaný povinný prvek MobitoTxnId
24085
Transaction not found in MOBITO database
Buď transakce neexistuje, nebo se jedná transakci
realizovanou jiným uživatelem, ne které nemá tento
uživatel právo
24120
Remote system error <code>
Nejčastěji nastává pokud chybí některé povinné prvky,
nebo je špatná kombinace SourceAuthKey/SourceID
24130
Remote system is offline, not available
Interní chyba
24999
Unknown error <additional message, if any>
Interní chyba, nastává také pokud jsou zapomenuty
některé prvky (i když jsou nepovinné musí být v XML
s prázdným textem uvnitř)
2.5
2.5.1
GetTransactionDetail Method
Purpose
To get the full details of a request for payment transaction which was previously successful.
2.5.2
Parameters
MOPET CZ a. s.
Parameter Name
Type
Direction
SourceID
String
SourceTxnID
String
Mandatory
Description
In
Yes
Source Merchant’s ID
In
Yes
Source Merchant’s Original Internal
Transaction ID
Page 49 of 76
Valid Value
v1.7
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.
Yes
Fully qualified phone number of the
beneficiary customer or nicknumber
RESPONSE ON TRANSACTION QUERY SUCCESS
CustomerID
String
Out
PaymentAmount
String
Out
String
representation
in ABC.YY
Yes
The payment amount for the
transaction.
Currency
String
Out
Valid ISO code
Yes
The ISO code of the currency in
which the amount was sent
(e.g. CZK)
MOPET CZ a. s.
Fee
String
Out
String
representation
in ABC.YY
Yes
The fee charged by MOBITO to the
merchant’s account
ProductDesc
String
Out
Upto 64 chars
Yes
Description of service/product
purchased by consumer
MobitoTxnID
String
Out
Yes
Original Transaction ID generated by
the MOBITO system
CompletionTS
String
Out
Yes
The timestamp of the completion of
the transaction is reported here.
Format - YYYYMMDDHH24MISS
Page 50 of 76
v1.7
NewBalance
String
Out
SourceTxnID
String
SourceRefID
String
String
representation
in ABC.YY
Yes
The balance of the merchant after
the completion of the transaction
Out
Yes
Source Merchant’s Original Internal
Transaction ID
Out
No
If sent by the merchant in the original
request, it will be returned as is
RESPONSE ON TRANSACTION QUERY FAILURE
2.5.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
25020
Invalid or Missing SourceID
25021
SourceID not permitted to perform transaction
25022
Invalid or Missing SourceAuthKey
25030
Invalid or Missing SourceTxnID
25035
Missing InvoiceID
25070
Invalid or Missing Timestamp
25080
Missing MobitoTxnID
MOPET CZ a. s.
Page 51 of 76
v1.7
25085
Transaction not found in MOBITO database
25086
Transaction failed due to error <code>
25087
Transaction is still pending customer confirmation
25120
Remote system error <code>
25130
Remote system is offline, not available
25999
Unknown error <additional message, if any>
2.6 GetTransactionReport Method
2.6.1
Purpose
To download a transaction report in .csv format based on a simple parameterized query.
2.6.2
Parameters
Parameter Name
Type
Direction
SourceID
String
In
Valid Value
Mandatory
Description
Popis
Yes
Source Merchant’s ID
Identifikátor technického účtu, který
Vám přidělí Mobito (lze zjistit v portálu
obchodníka), typicky je přiděleno jedno
číslo pro jednu integraci obchodníka
(např. na jednu síť prodejen).
Report bude obsahovat transakce
realizované pouze tímto technickým
MOPET CZ a. s.
Page 52 of 76
v1.7
účtem. V případě, že transakce bude
realizována např. manuálně uživatelem
přes Mobito portál obchodníka, pak
nebude obsažena v tomto reportu.
SourceTxnID
String
In
No
Source Merchant’s Internal
Transaction ID. This is merely for the
merchant to be able to track multiple
report requests and has no bearing
on the actual report.
Transakční číslo obchodníka (slouží pro
případné dohledávání v systémovém
logu v případě problémů, nevztahuje se
l žádné finanční transakci)
SourceAuthKey
String
In
Yes
Authorization key assigned to the
merchant by MOBITO
Zde uveďte autentizační klíč, který Vám
přidělí Mopet po registraci technického
účtu. Autentizační klíč je přidělen ke
každému účtu se SourceID.
Timestamp
String
In
Yes
Source’s current timestamp in the
format - YYYYMMDDHH24MISS
Uveďte Váš aktuální systémový čas.
StartDate
String
In
Yes
Start date of the intended report
Uveďte datum a čas, od kterého chcete
získat report transakcí
format - YYYYMMDDHH24MISS
EndDate
String
In
Yes
End date of the intended report
Uveďte datum a čas, do kterého chcete
získat report transakcí
format - YYYYMMDDHH24MISS
QueryType
String
In
F or I or S or R
Yes
The type of transactions which
should be summed for the report:
F – Fund outs
-
I – Incoming payments
S – Sales
Page 53 of 76
S – report všech zaplacených
plateb od klientů, které byly
vygenerované tímto
technickým účtem
R – report všech refundací
realizovaných tímto technickým účtem
R - Refunds
MOPET CZ a. s.
Uveďte typ reportu. Relevantní reporty
jsou:
v1.7
voláním metody IssueRefund
RESPONSE ON TRANSACTION QUERY SUCCESS
MobitoTxnID
String
Out
Yes
Original Transaction ID generated by
the MOBITO system
TotalAmount
String
Out
String
representation
in ABC.YY
Yes
Total transaction amount applicable
for the transactions included in the
report.
Celková suma transakcí obsažených
v reportu (jedná se o sumu ve sloupci
Amount)
TotalFees
String
Out
String
representation
in ABC.YY
Yes
Total fees applicable for the
transactions included in the report.
Celková suma poplatků obsažených
v reportu (jedná se o sumu ve sloupci
Fees)
TotalCount
String
Out
Yes
Total number of transactions
included in the report.
Celkový počet transakcí obsažených
v reportu
ReportURL
String
Out
Yes
The URL from which the merchant
report can be downloaded. This is
time limited and valid only for 5
minutes from the time of generation.
URL adresa, ze které je možné stáhnout
detailní CSV report transakcí. Formát
reportu jeuveden výše v kapitole
Reporting Mobito plateb.
RESPONSE ON TRANSACTION QUERY FAILURE
2.6.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
MOPET CZ a. s.
Page 54 of 76
v1.7
Code
Description
26020
Invalid or Missing SourceID
26021
SourceID not permitted to perform transaction
26022
Invalid or Missing SourceAuthKey
26070
Invalid or Missing Timestamp
26072
Invalid or Missing StartDate
26074
Invalid or Missing EndDate
26086
Invalid or Missing QueryType
26120
Remote system error <code>
26130
Remote system is offline, not available
26999
Unknown error <additional message, if any>
2.7 IssueRefund Method
2.7.1
Purpose
To issue a refund to a customer for a previously successful payment.
2.7.2
Parameters
MOPET CZ a. s.
Parameter Name
Type
Direction
SourceID
String
In
Page 55 of 76
Valid Value
Mandatory
Description
Yes
Source Merchant’s ID
v1.7
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.
PaymentAmount
String
In
String
representation
in ABC,YY
Yes
Original amount for the transaction to
be refunded. This must match the
amount in the original transaction.
Currency
String
In
Valid ISO code
Yes
The ISO code of the currency in
which the original transaction was
processed.
No
Default is 0. The merchant can use
this to deduct a fee from the amount
refunded in case applicable.
Yes
Transaction ID generated by the
MOBITO system for the refund.
Yes
The balance of the merchant after
the completion of the refund
transaction.
Yes
The original MOBITO transaction id
for reference.
(e.g. CZK)
RefundFee
String
In
String
representation
in ABC,YY
RESPONSE ON TRANSACTION REFUND SUCCESS
MOPET CZ a. s.
RefundTxnID
String
Out
NewBalance
String
Out
MobitoTxnID
String
Out
Page 56 of 76
String
representation
in ABC,YY
v1.7
RESPONSE ON TRANSACTION REFUND FAILURE
2.7.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
27020
Invalid or Missing SourceID
27021
SourceID not permitted to perform transaction
27022
Invalid or Missing SourceAuthKey
27030
Invalid or Missing SourceTxnID
27035
Missing InvoiceID
27040
Invalid or Missing PaymentAmount
27050
Invalid or Missing Currency Code
27070
Invalid or Missing Timestamp
27080
Missing MobitoTxnID
27085
Transaction not found in MOBITO database
27120
Remote system error <code>
27130
Remote system is offline, not available
MOPET CZ a. s.
Page 57 of 76
v1.7
27999
Unknown error <additional message, if any>
2.8 CancelRequestForPayment Method
2.8.1
Purpose
To cancel a previously submitted payment which is still pending.
2.8.2
Parameters
Parameter Name
Type
Direction
SourceID
String
SourceTxnID
Valid Value
Mandatory
Description
In
Yes
Source Merchant’s ID
String
In
Yes
Source Merchant’s Original Internal
Transaction 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.
CancelReason
String
In
No
Short description indicating reason
for cancelation. Not stored or used
for reporting at this time.
Yes
The original MOBITO transaction id
for reference.
RESPONSE ON TRANSACTION CANCEL SUCCESS
MobitoTxnID
MOPET CZ a. s.
String
Out
Page 58 of 76
v1.7
MobitoMessage
String
Out
No
Additional message from MOBITO
RESPONSE ON TRANSACTION CANCEL FAILURE
2.8.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
28020
Invalid or Missing SourceID
28021
SourceID not permitted to perform transaction
28022
Invalid or Missing SourceAuthKey
28030
Invalid or Missing SourceTxnID
28070
Invalid or Missing Timestamp
28080
Missing MobitoTxnID
28085
Transaction not found in MOBITO database
28120
Remote system error <code>
28130
Remote system is offline, not available
28636
Transaction cannot be canceled
28999
Unknown error <additional message, if any>
MOPET CZ a. s.
Page 59 of 76
v1.7
3
MobitoCode Integration
3.1 Basics
The MobitoCode concept is essentially a flexible way to generate request for payments based on user input. This type of integration is intended for impulse
buying scenarios and requires the participating merchants to implement a few client side and a few server side SOAP methods so that the MOBITO system
can retrieve or verify the MobitoCode information prior to presenting any choices or options to the customer as well as for product reservations (timelimited) prior to initiating the request for payment on behalf of the participating merchant.
Client-side SOAP methods to be implemented by the merchants at this time:


ConfigurePaymentNotification (refer to Section 2.3 for full details)
ConfigureMobitoCodeListener
Server-side SOAP methods to be implemented by the merchants at this time:


GetMobitoCodeInfo
PreValidateMobitoCodeOrder
All MobitoCodes are issued by Mopet directly to a participating merchant based on a specific business and commercial criteria. Each MobitoCode is unique
and non-transferrable from one merchant to another.
3.2 ConfigureMobitoCodeListener
3.2.1
Purpose
To configure a listener URL for receiving MobitoCode related requests from the MOBITO system. This URL can also be configured manually via the Merchant
Self Care portal.
MOPET CZ a. s.
Page 60 of 76
v1.7
3.2.2
Parameters
Parameter Name
Type
Direction
SourceID
String
SourceTxnID
Valid Value
Mandatory
Description
In
Yes
Source Merchant’s ID
String
In
No
Source Merchant’s Internal
Transaction ID. This is merely for the
merchant to be able to track multiple
configuration requests (if applicable)
and has no bearing on the actual URL
configuration.
SourceAuthKey
String
In
Yes
Authorization key assigned to the
merchant by MOBITO
Timestamp
String
In
Yes
Source’s timestamp in the format YYYYMMDDHH24MISS
ListenerURL
String
In
Yes
The URL on which the merchant will
be listening for MobitoCode requests.
URL
RESPONSE ON NOTIFICATION CONFIGURATION SUCCESS
MobitoTxnID
String
Out
Yes
Transaction ID generated by the
MOBITO system
MobitoMessage
String
Out
No
Additional message from MOBITO
RESPONSE ON NOTIFICATION CONFIGURATION FAILURE
MOPET CZ a. s.
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Page 61 of 76
v1.7
3.2.3
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
32020
Invalid or Missing SourceID
32021
SourceID not permitted to perform transaction
32022
Invalid or Missing SourceAuthKey
32070
Invalid or Missing Timestamp
32112
Invalid of Missing ListenerURL
32120
Remote system error <code>
MOPET CZ a. s.
Page 62 of 76
v1.7
3.3 GetMobitoCodeInfo Method
3.3.1
Purpose
The MOBITO system will use this method to query the MobitoCode status on the merchant’s system and to retrieve any
options/choices/limits associated with it (if applicable).
3.3.2
Parameters
Parameter Name
Type
Direction
MobitoCode
String
MobitoTxnID
String
Valid Value
Mandatory
Description
Out
Yes
Fully qualified phone number of the
beneficiary customer or nicknumber
Out
Yes
Transaction ID generated by the
MOBITO system. This is used by the
MOBITO system internally for
tracking MobitoCode query requests
and has no bearing on a particular
MobitoCode transaction itself.
Yes
Number of choices the merchant
wishes to offer for the products,
services linked to the MobitoCode. If
0, the customer will not be asked any
questions and the system will go to
the PrevalidateMobitoCodeOrder
method directly. If 1, no choice is
presented and the customer is asked
to indicate a ‘Number’ or ‘Text’
depending on the ParamFormat
value below. Note that the behaviour
in case of 0 and 1 is the same if
ParamFormat is set to only ‘C’.
RESPONSE ON CODE QUERY SUCCESS
ChoiceCount
MOPET CZ a. s.
String
In
Page 63 of 76
0 to 9
v1.7
ParamFormat
String
In
ChoiceDetail
String
SourceTxnID
String
C or CN or CF
or CNF
Yes
Indicates the type of parameters
included with each choice.
In
Yes
This must be as per the format
described in the section 3.3.3 below.
In
No
Merchant’s internal transaction id for
this query transaction in case the
merchant wishes to track such
responses.
RESPONSE ON CODE QUERY FAILURE
3.3.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
ChoiceDetail Format For MobitoCode
In cases where the ChoiceCount is non zero, the merchant must return a multipart string in the following format with the pipe “|” as the record separator;
(a) If ParamFormat is “C”,
Choice1|Choice2|……………………Choice9
(b) If ParamFormat is “CN”,
Choice1,Number1|Choice2,Number2|……………………Choice9,Number9
(c) If ParamFormat is “CF”,
Choice1,Text1|Choice2,Text2|……………………Choice9,Text9
MOPET CZ a. s.
Page 64 of 76
v1.7
(d) If ParamFormat is “CNF”
Choice1,Number1,Text1|Choice2,Number2,Text2|……………………Choice9,Number9,Text3
where;
C indicates that a ‘Choice’ name is present,
N indicates a ‘Number’ (either quantity or variable symbol) is to be collected,
F indicates a ‘FreeText’ (any random string such as address or email) is to be collected
C -> can be a string upto 12 characters long
N -> can be NX where X indicates maximum quantity available for purchase or NV which
indicates that the user must type in a variable symbol
F -> can be any string upto 12 characters long
Example:
Movie1,N4,Type Email|Movie2,N3,Type Email|……………………
Would trigger a choice of movies with Movie1 having a limit of max. 4 tickets plus an optional email input request for the customer and Movie2 having a
limit of max. 3 tickets with a similar email input request for the customer.
MOPET CZ a. s.
Page 65 of 76
v1.7
3.3.4
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
33210
Invalid or Missing MobitoCode
33230
MobitoCode Linked Product/Service Sold Out
33240
MobitoCode Linked Product/Service No Longer Available
33130
Merchant system is offline, not available
33999
Unknown error <additional message, if any>
3.4 PreValidateMobitoCodeOrder Method
3.4.1
Purpose
The MOBITO system will use this method to prevalidate a product/service purchase at the merchant’s end based on the choice inputs received from a
customer. The decision whether or not to provisionally reserve the product/service at this stage rests with the merchant.
3.4.2
Parameters
MOPET CZ a. s.
Parameter Name
Type
Direction
Choice
String
Number
FreeText
Mandatory
Description
Out
Yes
Choice selected by customer
String
Out
No
Quantity or variable symbol chosen by
the customer
String
Out
No
String input by the customer (e.g.
address or email)
Page 66 of 76
Valid Value
v1.7
Timestamp
String
Out
Yes
Source’s timestamp in the format YYYYMMDDHH24MISS
MobitoTxnID
String
Out
Yes
Transaction ID generated by the
MOBITO system
Yes
Merchant’s internal transaction id for
this transaction
Yes
The time till which the reservation or
prevalidation is valid in the timestamp
format –
RESPONSE ON ORDER VALIDATION SUCCESS
SourceTxnID
String
In
Validity
String
In
Min: 30 secs
Max: 60 days
from initiation
YYYYMMDDHH24MISS
SourceAuthKey
String
In
Yes
Authorization key assigned to the
merchant by MOBITO
CustomerMessage
String
In
No
Additional message to display to the
customer during the RfP confirmation
process.
PaymentAmount
String
In
Yes
The total amount payable by the
customer (for the generation of the
RfP)
TrxCode
String
In
No
If provided by merchant, this will be
sent by MOBITO to the customer as a
notification upon successful
completion of the transaction.
Text generated
by Merchant,
used to validate
purchase (ie.
eTicket code,
download code
etc.)
RESPONSE ON NOTIFICATION CONFIGURATION FAILURE
MOPET CZ a. s.
Page 67 of 76
v1.7
3.4.3
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable:
Code
Description
34010
Invalid or Missing Choice
34020
Invalid Number
34022
Invalid FreeText
34030
Missing MobitoTxnID
34070
Invalid or Missing Timestamp
34112
Merchant cannot accept payment at this time
34130
Remote system is offline, not available
34999
Unknown error <additional message, if any>
MOPET CZ a. s.
Page 68 of 76
v1.7
4
MOBITO PayNow Button Integration
This approach uses HTML buttons and forms on the merchant websites to redirect the buyer to MOBITO in order to make the payment. Buyers may return
to the merchant website after completing their transactions using MOBITO.
4.1
How Integration With PayNow Button Works
The basic sequence for PayNow button integration requires buyers to have a MOBITO account and their registered mobile phone in close proximity before
they can complete their payments.
4.1.1
Communication Via HTTPS POST
In order to accept payments over the web via the PayNow button, the merchant website will need to interface with the MOBITO servers via the HTTPS POST
protocol. The parameters below need to be supplied for initiating a request for payment from a prospective customer. The customer gets automatically
redirected to the MOBITO payment portal about submission of the web form.
MOPET CZ a. s.
Page 69 of 76
v1.7
Parameter Name
Type
Direction
CustomerID
String
SourceID
Valid Value
Mandatory
Description
In
No
Fully qualified phone number of the
beneficiary customer or nicknumber if
available
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 site identifier or reference
ID for reconciliation and reporting. It
will merely be stored by the MOBITO
system and is not interpreted in any
manner.
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
representation
with in ABC,YY
Yes
The payment amount for the
transaction.
Currency
String
In
Valid ISO code
Yes
The ISO code of the currency in which
the amount is being sent
Yes
Source’s timestamp in the format YYYYMMDDHH24MISS
Yes
Description of service/product
purchased by consumer
(e.g. CZK)
MOPET CZ a. s.
Timestamp
String
In
ProductDesc
String
In
Page 70 of 76
Upto 64 chars
v1.7
Merchants may use the mock HTML <form> code for the MOBITO payment button indicated below to help speed up the implementation of the payment
button on their website. The timestamp parameter is purely informational and doesn’t impact the actual RfP or flows in any way. It is not validated by the
server, and is merely intended to assist the merchants to track their requests.
Sample HTML code for the form is indicated below:
<form action="https://platba-mopet.moremagic.com/cui/mwallet/paymentButton" method="post">
<input type="hidden" name="cmd" value="_xclick" />
<input type="hidden" name="CustomerID" value="" />
<input type="hidden" name="SourceID" value="89891989" />
<input type="hidden" name="SourceTxnID" value="1234" />
<input type=”hidden” name=”SourceRefID” value=”ezbaycz” />
<input type="hidden" name="InvoiceID" value="ABININ10" />
<input type="hidden" name="SourceAuthKey" value="aioeiooq8989100jkkjie10" />
<input type="hidden" name="PaymentAmount" value="10.00" />
<input type="hidden" name="Currency" value="CZK" />
<input type="hidden" name="Timestamp" value="20111113232029" />
<input type="hidden" name="ProductDesc" value="eCommerce Shop Purchase" />
<input type="submit" value="PayNow!" />
</form>
MOPET CZ a. s.
Page 71 of 76
v1.7
4.1.2
Response Format & Redirection Parameters
If the transaction is successful, the following parameters are returned back to the merchant as part of the parameter list sent to the ‘SuccessURL’ specified
earlier.
https://MerchantURL?MobitoTxnID=182989201&TxnStatus=OK……….
RESPONSE ON TRANSACTION SUCCESS/FAILURE
TxnStatus
String
Out
MobitoTxnID
String
CompletionTS
OK or FAILED
Yes
Status of the transaction in the
MOBITO system
Out
Yes
Original Transaction ID generated by
the MOBITO system
String
Out
Yes
The timestamp of the completion of
the transaction is reported here.
Format - YYYYMMDDHH24MISS
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 response
RESPONSE PARAMETERS ADDED ON TRANSACTION FAILURE
MOPET CZ a. s.
FaultCode
String
Out
Yes
Fault error code
FaultString
String
Out
Yes
Fault error message
Page 72 of 76
v1.7
4.1.3
Exceptions
In cases where the transaction is not successful, the following error codes will be applicable and will be returned as part of the parameter list sent to the
‘CancelURL’ specified earlier.
Code
Description
41010
Invalid CustomerID
41020
Invalid or Missing SourceID
41021
SourceID not permitted to perform transaction
41022
Invalid or Missing SourceAuthKey
41030
Invalid or Missing SourceTxnID
41035
Missing InvoiceID
41040
Invalid or Missing PaymentAmount
41050
Invalid or Missing Currency Code
41070
Invalid or Missing Timestamp
41090
Invalid or Missing ProductDesc
41100
Invalid SuccessURL
41110
Invalid CancelURL
41120
Remote system error <code>
MOPET CZ a. s.
Page 73 of 76
v1.7
41130
Remote system is offline, not available
41210
Cannot locate home network for CustomerID
41310
Duplicate transaction detected
41410
Request timed out
41510
Rejected by customer
41999
Unknown error <additional message, if any>
4.1.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 74 of 76
v1.7
4.1.5
Configuring Return URLs Via Merchant Self Care Portal
To configure URLs to which the customer must be redirected to at the end of the transaction:
1. Login to the merchant self care portal account at https://www.mobito.biz
2. Click on the “API Access” link, choose “PayNow Button” and then the “Configure” option
3. Enter the details of the URLs:
a. SuccessURL – type the URL to which the buyer’s browser should be redirected after the successful completion of the payment via MOBITO.
b. CancelURL - type the URL to which the buyer’s browser should be redirected after the cancelation of the payment or if an error occurs.
MOPET CZ a. s.
Page 75 of 76
v1.7
5
Notifications
Merchants and 3rd parties can be notified of payment results via various channels:
1. Notification URL – this can be configured via the merchant self care portal and requires the merchant to conform to the specifications indicated in
Section 2.4 of this document.
2. Email – this can be configured via the merchant self care portal.
3. Downloadable History – this can be downloaded from the merchant self care portal.
4. MOBITO Inbox – this is the local messaging service available on the self care portal as well as via USSD and the Android/IOS merchant applications.
MOPET CZ a. s.
Page 76 of 76
v1.7
Download

Připojení obchodníka do systému Mobito – příručka pro integraci