Zapojení merchanta 0.4

Dokument: Autor: Eva Černíková Vytvořen: 22.3.2012 Připojení obchodníků do systému Mobito Status: Draft Změněn: 22.3.2012

MOPET CZ, a. s. Page 1 of 48 Confidential document

MOPET CZ, a.s.

Připojení obchodníka do systému Mobito

Příručka pro integraci



Změny v dokumentu Verze Datum Autor Popis 0.1 12.1.2012 Tomáš Severýn Vytvoření dokumentu 0.2 8.2.2012 Tomáš Severýn Úprava po interním kole připomínek 0.3 21.2.2012 Tomáš Severýn Úprava zabezpečovacího mechanismu (počítání HASH) 0.4 24.2.2012 Tomáš Severýn Úprava platebního tlačítka -‐pole timestamp včetně popisu

v příloze B, aktualizace přílohy A – formátování a číslo verze



Obsah 1. Cíl dokumentu ................................................................................................................................. 4

2. Manažerské shrnutí ......................................................................................................................... 4

2.1. Představení společnosti Mopet a systému Mobito ................................................................. 4

2.2. Možnosti připojení .................................................................................................................. 4

2.3. Náročnost implementace: ....................................................................................................... 4

Platební tlačítko: ............................................................................................................................. 4

Mobito kód a připojení na rozhraní: ............................................................................................... 5

2.4. K čemu slouží testovací prostředí: .......................................................................................... 5

2.5. Testovací fáze: ......................................................................................................................... 5

2.6. Poskytovaná podpora: ............................................................................................................ 5

Zkratky používané v dokumentu ..................................................................................................... 5

3. Platební tlačítko .............................................................................................................................. 6

3.1. Obecné předpoklady scénářů: ................................................................................................ 6

3.2. Mobito Platební Tlačítko (Bez Integrace) ................................................................................ 6

3.3. Mobito Platební Tlačítko (Integrace) ....................................................................................... 7

3.4. Požadavky na zobrazení platebního tlačítka ......................................................................... 10

3.5. Testování platebního tlačítka ................................................................................................ 10

4. Integrace plateb spuštěných klientem (Mobito Code) .................................................................. 11

4.1. Testování MobitoCode .......................................................................................................... 13

5. Integrace WebServices požadavky na platbu ................................................................................ 13

5.1. Testování Web Services ......................................................................................................... 14

6. Integrace Notifikace ...................................................................................................................... 15

7. Integrace WebServices -‐ Zjištění stavu transakcí ......................................................................... 15

8. Ověření klienta .............................................................................................................................. 15

8.1. Bezpečnostní kód .................................................................................................................. 15

8.2. Algoritmus ............................................................................................................................. 15

9. FAQs .............................................................................................................................................. 16

10. Příloha A Technický popis rozhraní (EN) ................................................................................... 17

11. Příloha B Kód platebního tlačítka .............................................................................................. 46



1. Cíl dokumentu Cílem tohoto dokumentu je seznámit obchodníky s možnostmi zapojení do systému Mobito a zároveň je provést procesem připojování jednotlivých kanálů. Součástí tohoto dokumentu jsou všechny informace nutné k implementaci, integraci a otestování vybrané platební metody společnosti Mopet CZ.

2. Manažerské shrnutí 2.1. Představení společnosti Mopet a systému Mobito

Společnost MOPET CZ, a.s. je akciová společnost, jejímiž spoluvlastníky jsou čeští mobilní operátoři O2 Telefonica, Vodafone a T-‐Mobile a bankovní domy Česká spořitelna, Raiffeisenbank, UniCredit a GE Money Bank. Základním cílem společnosti je vybudovat transakční centrum pro mobilní platby a uvést na český trh službu Mobito, umožňující platit a posílat peníze v reálném čase přes mobilní telefon tam, kde nyní zákazníci používají převážně hotovost, bez ohledu na to, které banky nebo operátora jsou klienty. Lze tak platit mobilním telefonem za zboží a služby, hradit složenky a faktury, posílat si mezi sebou peníze či zaplatit mobilním telefonem nákup na internetu nebo v mobilu. Společnost vznikla ke konci roku 2010 a její snahou je spuštění všech procesů a služeb počátkem roku 2012. Projekt přípravy služby je v plném proudu – co se IT oblasti týče, vzniká nyní i firemní infrastruktura systémů jako transakční jádro, ERP systém, napojení na banky, operátory a platební bránu a další podpůrné systémy.

Mobito je nový platební standard na českém trhu, který umožňuje zákazníkům platit prostřednictvím mobilních telefonů za zboží a služby. Hlavním prvkem Mobita je tzv. „request for payment – žádost k zaplacení“, kterou dostává zákazník do svého mobilu a potvrzuje ji PINem. Mobito je zdarma, funguje na všech mobilních telefonech a pro klienty všech českých bank a mobilních operátorů. Mobito má ambici stát se synonymem pro peníze v mobilu a inovativní univerzální platební metodu, která bude mít své pevné místo vedle hotovosti a platebních karet. Peníze v mobilu, jinak než je doposud znáte, to je Mobito.

2.2. Možnosti připojení Obchodník má 3 možnosti připojení k systému Mobito. Jsou to:

1. Platební tlačítko 2. Integrace pomocí webových služeb pro platbu 3. Integrace Mobito kód

Každá z možností bude detailněji probrána v následujících kapitolách.

2.3. Náročnost implementace:

Platební tlačítko: Společnost Mopet se snaží maximálně zjednodušit přístup ke svým platebním metodám pro maximálně širokou skupinu obchodníků. Na základě této dlouhodobé vize jsme se pokusili navrhnout



připojení na platební bránu v maximálně zjednodušené podobě. Předpokládána náročnost implementace základní funkčnosti by měla být do 1 MD (práce člověka za jeden 8 hodinový den)

Mobito kód a připojení na rozhraní: Tato funkcionalita je o něco složitější, protože vyžaduje znalosti a zkušenost s implementací webových služeb, větší znalost vnitřních procesů obchodníka a náročnější způsob připojení na testovací a produkční prostředí. Připojení přes tyto metody řešíme individuálně mimo standardní procesy připojení obchodníka. Tato integrace vyžaduje vlastní rozhraní na straně obchodníka, pomocí kterého je náš systém informován o nabízeném zboží/službách. Tímto umožňuje vytvořit nové obchodní kanály například z mobilního telefonu, dále integraci do stávající infrastruktury pokladních systémů a zapojení plateb do obchodních procesů. Očekávaná doba implementace by se měla pohybovat okolo 3MD připojení na rozhraní, a 5MD připojení pro Mobito code. Poté je potřeba počítat s cca 1MD na testy. Do odhadu nejsou započítány pracnosti nutné na změnu procesů ve Vašem systému případně infrastruktury.

2.4. K čemu slouží testovací prostředí: Testovací prostředí poskytuje společnost Mopet CZ pro podporu integrace obchodníka na produkt Mobito. Na tomto prostředí si obchodník ověří, že jeho systém funguje dle specifikace a Mopet CZ mu na základě tohoto testu umožní přístup na produkční prostředí. Tímto testem se obchodník nezříká zodpovědnosti za kvalitu a fungování svojí části systému v živém prostředí.

2.5. Testovací fáze: Společnost Mopet standardně nabízí 3 týdenní testovací okno. První dva týdny slouží primárně pro potřeby připojovaného obchodníka. V rámci tohoto období si obchodník může otestovat svojí část systému dle svojí potřeby. Poslední týden slouží pro provedení testů popsaných v dokumentu Popis Připojení obchodníka v příslušných kapitolách u každé platební metody. Na základě úspěšného provedení těchto testů je zahájen proces „zprovoznění obchodníka pro produkci“.

2.6. Poskytovaná podpora: Společnost Mopet poskytuje podporu pro integraci obchodníka na mailové adrese: [email protected] V případě jakýchkoliv problémů se můžete obrátit na tento mail.

Zkratky používané v dokumentu Zkratka Popis WSDL Web Service Definition File – soubor popisující rozhraní webových služeb XML Extensible Markup Language RFP Request for payment -‐ Požadavek na platbu -‐ klientovi je zaslána informace o

platbě, kterou může potvrdit, zrušit a v některých případech odložit



3. Platební tlačítko 3.1. Obecné předpoklady scénářů: • Klient – Fyzická osoba zaregistrována a aktivována do služby Mobito. Klient má na účtu

dostatek prostředků na zaplacení poptávané služby / vybraného zboží (klient má možnost zaplatit zboží i bez předchozí dotace účtu – klient s online připojeným platebním instrumentem)

• Obchodník – Fyzická, nebo právnická osoba, se kterou je uzavřena smlouva s firmou Mopet CZ. Obchodník je zaregistrován a aktivován do služby Mobito

3.2. Mobito Platební Tlačítko (Bez Integrace) Popis Platební tlačítko bez integrace slouží například pro nadace / občanská sdružení (OS), která chtějí využít možnosti přes Mobito zaslat dar. Uživatelská zkušenost:

-‐ Klient – chce vložit dar přes web nebo mobilní web nadace -‐ Obchodník / OS -‐ chce na své stránky zobrazit tlačítko „darujte“ a není možné jakékoliv složité

programování

Scénář platby:

-‐ Klient (web OS) – stiskne tlačítko „darovat“, -‐ Web OS– přesměrování klienta na platební bránu Mobito a předání údajů o platbě (částka,

popis) -‐ Klient (platební brána Mobito) – zadání Mobito ID (tel. čísla / ID) a potvrzení platby. -‐ Mobito systém – zaslání požadavku na platbu na tel. číslo klienta registrované u Mobito účtu

(nativní notifikace, USSD notifikace) -‐ Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem -‐ Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a

zaslání potvrzujícího emailu do OS. Přesměrování na web OS -‐ Klient (web obchodníka) – klientovi je zobrazena notifikace o úspěšném zaplacení na mobilu / je

možné zobrazit stránku s poděkováním

Jak to udělat:

Jak to udělat / Nastavení pro platbu

1) Přihlášení se do portálu pro obchodníky – pomocí administrátorského účtu, který obdržíte při podpisu smlouvy

2) Nastavení obchodního místa -‐ vytvoření Virtuálního zaměstnance a) Vytvořte pomocí návodu základní strukturu –jednoho Virtuálního zaměstnance přímo pod

svým účtem b) WWW adresu, kterou chcete, aby se zobrazila na Mobito Bráně vložte do parametru Název

Virtuálního zaměstnance c) Odpověď na e-‐mail – nastavte e-‐mail na který Vám budou chodit informace o platbách



3) Nastavení adres pro přesměrování na bránu a) Jako cílovou adresu pro ukončení platby nastavte odkaz na stránku na vašem serveru, kde

uživateli poděkujete za dar. Adresu pro chybu ponechte prázdnou. b) Stránku pro případ neúspěch ponechte prázdnou, v případě neúspěchu se uživateli zobrazí

automatická informace naší brány c) Adresy musí být ve tvaru https://server:port/soubor

4) Nastavte si na Portálu pro obchodníky e-‐mail notifikaci o provedené platbě, abyste měli přehled. 5) SourceAuthKey Zobrazí se na výpisu detialů Virtuálního zaměstnance

a) Tento klíč, stejně jako vaše Identifikační číslo (SourceID) vložte do předpřipraveného kódu b) pro tlačítko

6) Na vaše webové stránky vložte HTML kód (viz příloha B) s jednoduchým platebním tlačítkem s přednastavenou částkou (případně několik tlačítek s různými částkami nebo tlačítko s možností uživatelské editace částky). Do pole timestamp vložte aktuální datum.

7) Celou implementaci je možné provést bez programování.

3.3. Mobito Platební Tlačítko (Integrace) Popis

Platební tlačítko umožňuje začlenit Mobito jako platební metodu např. do e-‐shopu obchodníka sloužící k okamžitému zaplacení zboží.

Uživatelská zkušenost:

-‐ Klient – Nákup mobilem vzdáleně přes web nebo mobilní web obchodníka (registrovaný i neregistrovaný klient webu)

-‐ Obchodník (eShop) -‐ Mobito jako platební metoda, integrace Mobito platebního tlačítko na webu / mobilním webu obchodníka.



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 (volitelně, v případě že chcete mít transakce z tohoto obchodu na separátním účtu od ostatních transakcí)

b) WWW adresu obchodu, kterou chcete, aby se zobrazila na Mobito Bráně vložte do parametru Název Virtuálního zaměstnance

3) Nastavení adres pro přesměrování na bránu a) U Virtuáního zaměstnance nastavte adresy, na které bude zákazník přesměrován v případě

úspěchu případně neúspěchu transakce b) Tyto adresy musí být ve tvaru https://server:port/soubor

4) SourceAuthKey, SecurityToken – Zobrazí se na výpisu detialů Virtuálního zaměstnance a) SourceAuthKey se použije při odesílání požadavku na bránu a slouží namísto hesla. Generuje

systém po vytvoření Virtuálního Employee b) SecurityToken slouží pro zajištění bezpečnosti návratu, tento kód se poté použije pro podpis

a na Vaší straně pro ověření podpisu zpráv o zaplacení.

Scénář platby:

1) Klient (web obchodníka) – výběr zboží nebo služby na webu obchodníka, výběr platební metody – Mobito a potvrzení platby.

2) Web obchodníka – přesměrování klienta na platební bránu Mobito a předání údajů o platbě (částka, popis zboží / služby)

3) Klient (platební brána Mobito) – zadání Mobito ID (tel.čísla / ID) a potvrzení platby. 4) Mobito systém – zaslání požadavku na platbu na tel. číslo klienta registrované u Mobito účtu

(nativní notifikace, USSD notifikace) 5) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem 6) Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a

notifikace webu obchodníkovi. Přesměrování na web obchodníka 7) Klient (web obchodníka) – klientovi je zobrazena notifikace o úspěšném zaplacení zboží / služby

a další instrukce. a) Obchodník -‐ ověří platnost odpovědi brány pomocí ověření podpisu (viz kapitola ověření)

Alternativy scénáře -‐ obchodník:

A) Předvyplnění Mobito ID -‐ Web obchodníka předá platební bráně Mobito ID zákazníka (bude předvyplněno) – krok 2



Alternativy scénáře -‐ klient:

A) Transakce nedokončena / neautorizována -‐ V případě neúspěšného potvrzení transakce (klient neautorizoval transakci, vypršel limit) je klient přesměrován na web obchodníka (definovaná failure – chybová -‐ URL)

B) Transakce dokončena, ale klient uzavřel Mobito platební bránu před přesměrováním na web obchodníka

a. Manuálně zjistit stav transakce v portálu pro obchodníky b. Je možné nastavit systém tak, aby po zaplacení vyvolal webovou adresu obchodníka

s informacemi o zaplacení c. Je možné zavolat GetPaymentStatus metodu rozhraní API, kde je uveden status

platby

Technické požadavky integrace:

-‐ Odeslání požadavku na platbu -‐ integrace platebního tlačítka Mobito na web obchodníka (HTTP POST protokol)

-‐ Přijetí výsledku transakce – schopnost přijetí a zobrazení výsledku transakce na definovaném URL obchodníka (nastavení success / failure URL na Mobito portálu obchodníka), pokud obchodník vyžaduje ověření, schopnost vypočítat kontrolní součet (viz kapitola ověření)

Detailní technický popis rozhraní – viz Mobito API (příloha A)

sd PaymentButton

MerchantSystem HandsetMobitoPaymentGateway

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)

3.5. Testování platebního tlačítka Pro ověření funkčnosti platebního tlačítka nejprve nastavte tlačítko dle návodu v kapitolách výše. Pro testování prosím kontaktujte alespoň týden předem -‐ email [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

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) Zkontrolujtem, zda se Vám zobrazilo tlačítko správně (nikoliv jako kód <form…) ii) Zkontrolujde, zda Váš prohlížeč neotevírá jiné okno iii) Zkontrolujte, že máte správné informace ve zdrojovém kódu stránky

4) Zadejte do zobrazené brány číslo -‐ 606079502 5) Počkejte, až náš pracovník potvrdí transakci

a) Dojde li k přesměrování na Váš server, zkontrolujte přijetí parametrů a ověření (viz kapitola Bezpečnostní kód a algoritmus pro jeho vytvoření)

b) Nedojde li k přesměrování, zkontrolujte adresu, na kterou se snaží systém přesměrovat a případně ji opravte v portálu pro obchodníky

Testovací transakce -‐ neúspěch 6) Vytvořit zkušební transakci – Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo

platební tlačítko 7) Stisknutí tlačítka – Stisk tlačítka vyvolá přesměrování na platební bránu Mobito 8) Zadejte do zobrazené brány číslo – Jakékoliv vaše číslo 9) Počkejte, až náš pracovník zruší transakci

a) Dojde li k přesměrování na Váš server, zkontrolujte přijetí parametrů a ověření b) Nedojde li k přesměrování, zkontrolujte adresu, na kterou se snaží systém přesměrovat a

případně ji opravte v portálu pro obchodníky Testovací transakce – vypršení časového limitu 10) Kontaktujte [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 -‐ 602 356 797



14) Vyčkejte do vypršení časového limitu a) Zkontrolujte přijaté parametry

4. Integrace plateb spuštěných klientem (Mobito Code) Popis Pokud chcete využít mobilní telefon klientů jako nákupní prostředí, je možné integrovat je pomocí rozhraní MobitoCode. Uživatelská zkušenost:

-‐ Klient – Nákup mobilem například na základě plakátu, reklamy v TV, čísla faktury apod. -‐ Obchodník -‐ Mobito jako platební metoda podpořená jinými informačními kanály

(jakýkoliv informační kanál, ze kterého si klient může kód zapamatovat)

Scénář platby:

1) Klient (mobilní telefon) – přihlásí se do Mobito aplikace a zadá kód. 2) Server obchodníka – je kontaktován pro zjištění, zda je kód ještě platný a zda obchodník

požaduje po klientovi upřesnění objednávky a) Obchodník si může vyžádat (volitelně) vyplnit od klienta:

i) Výběr z 1-‐9 voleb (volby vztahující se k danému kódu) ii) Číslo – např. počet, variabilní symbol, číselný identifikátor apod. iii) Text – upřesňující údaje k objednávce (např. SPZ, PSČ, jméno apod.) – max 120 znaků bez

diakritiky 3) Klient (mobilní telefon) – zadání požadovaných zpřesňujících údajů 4) Server obchodníka – Obdrží zpřesňující informace, a zašle celkovou částku k zaplacení

a) v případě že je to možné v tuto chvíli je nejvhodnější chvíle, kdy se provede rezervaci zboží 5) Mobito systém – zaslání požadavku na platbu na tel. číslo klienta (nativní notifikace, USSD

notifikace) 6) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem

Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a notifikace webu obchodníkovi.





2) Kontaktování Mopet Backoffice a) Nastavení Branche a virtuálního zaměstnance typu Mobito code b) Získání technických popisů služeb(wsdl) podle kterých vyvinete na Váš server služby potřebné

pro integraci 3) Zobrazení vytvořeního virtuálního zaměstnance 4) SourceAuthKey, Zobrazí se na výpisu detialů Virtuálního zaměstnance

a) SourceAuthKey se použije při odesílání požadavku na bránu a slouží namísto hesla. Generuje systém po vytvoření Virtuálního Employee

5) Nastavení URL pro kontaktování

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()



a) U virt. zaměstnance nastavte adresu, na kterou Vás bude kontaktovat náš systém v případě kódu

b) Případně zavolejte web service ConfigureMobitoCodeListener (za pomoci nastaveného sourceAuthKey – zobrazeno u virt. zaměstnance a SourceID – ID Virt. Zaměstnance.

6) Ve smlouvě vám bude přidělen kód. Podle tohoto kódu systém rozpozná, že se jedná o Vaše kódy, proto je nutné, aby všechny Vaše kódy začínali na tento kód a) Příklad – přiřazený kód je 123, zákazník je přesměrován k vám s kódy

i) 123 ii) 12300001 iii) 123auto apod. iv) Ale už ne 001123 apod.

4.1. Testování MobitoCode Pro testování Mobito Code prosím kontaktujte [email protected] s předmětem „mobito code test“ a domluvte se na detailnější podpoře ohledně testování.

5. Integrace WebServices požadavky na platbu Popis Pokud chcete využít Mobito jako platební metodu spouštěnou jiným způsobem nežli klientem přímo z mobilu (mobito Code) nebo pomocí webového rozhraní, je pro Vás připraveno WebServices rozhraní. Toto slouží k zakládání požadavků na platbu (Request for Payment) a zjišťování stavu transakcí. Uživatelská zkušenost:

-‐ Klient – Nákup na pokladně nebo v systému, který komunikuje s klientem napřímo nebo vzdáleně (jakýkoliv informační kanál, který umí zjistit od klienta ID v systému Mobito aby mu zaslal požadavek na platbu)

Scénář platby:

1) Klient (obecně) – vyjádří přání nakoupit zboží u obchodníka a dokončí objednávku 2) Obchodník – Vyžádá si od klienta jeho číslo (telefonní, nebo Mobito přezdívku), to zadá do svého

systému a) Způsob vyžádání je ponechán na procesní a technické realizaci obchodníka může se jednat

například o: i) Zákazník sdělí pokladnímu své číslo ii) Číslo může být navázáno na věrnostní kartu, NFC chip, Čárový kód apod. iii) Číslo může být předáno bezdrátově pomocí mobilní aplikace, mobilního webu

3) Mobito systém – zaslání požadavku na platbu na tel. číslo klienta (nativní notifikace, USSD notifikace)

4) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem 5) Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a

notifikace webu obchodníkovi.



5.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 https:// testapi.imobito.cz:9916/merchant/api

3) Zjistěte, zda Vám webService potvrdila příem požadavku na platbu 4) Nechte Váš systém volat CheckPaymentStatus 5) Počkejte, až náš pracovník potvrdí transakci 6) Potvrďte si, že CheckPaymentStatus vrátil stav zaplaceno

Testovací transakce -‐ neúspěch 7) Vytvořit zkušební transakci – ve vašem systému vytvořte transakci s consumerID libovolné vaše

číslo a po web services kontaktujte server Mobito na adrese https://testapi.imobito.cz:9916/merchant/api

8) Zjistěte, zda Vám webService potvrdila příem požadavku na platbu 9) Nechte Váš systém volat CheckPaymentStatus 10) Počkejte, až náš pracovník potvrdí transakci 11) Potvrďte si, že CheckPaymentStatus vrátil stav zrušeno Testovací transakce – vypršení časového limitu 12) Kontaktujte [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 https:// testapi.imobito.cz:9916/merchant/api a) Stanovte validity na co nejnižší

14) Zjistěte, zda Vám webService potvrdila příem požadavku na platbu

sd RFP Flow Timeouts

HandsetMerchantSystem mBroker USSD GW

StartRFP(validity)

RFP Notification(Info)

AcceptReject()

InsertPIN()

PIN()

Notofication()



15) Nechte Váš systém volat CheckPaymentStatus 16) Počkejte, do času, který jste si nastavili v parametru „validity“ 17) Potvrďte si, že CheckPaymentStatus vrátil stav nepotvrzeno

6. Integrace Notifikace Funkcionalita notifikace funguje pro všechny typy integrací. Pro správnou funkcionalitu nastavte v portálu pro obchodníky u virtuálního zaměstnance „notifikační URL“. Na tuto adresu poté přijde z našeho serveru GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole „Ověření klienta“. Alternativně je možné nastavit tento parametr pomocí webové služby „ConfigurePaymentNotification“.

7. Integrace WebServices -‐ Zjištění stavu transakcí Webové služby nabízí funkce pro zjištění stavu transakce, získání více informací o úspěšně proběhlé transakci a Získání detailních informací o seznamu transakcí. Jsou to následující funkce:

• CheckPaymentStatus o Zjištění stavu aktuálně prováděné transakce – pro rychlý processing, jsou zde

všechny požadavky na platbu • GetTransactionDetail

o Zjištění detailu o transakci – zde je možné dohledat pouze úspěšně dokončené transakce

• GetTransactionReport o Získání seznamu transakcí, systém v této funkci také vrátí časově omezený link na

stažení vygenerovaného CSV souboru pro strojové zpracování transakční historie.

8. Ověření klienta Metody upozornění na platbu (Notification a přesměrování z platební brány) obsahují kromě údajů o transakci i podpis. Takto může obchodník jednoduše zjistit, že není daná informace o transakci podvržená a není nutné další zjišťování výsledku transakce.

8.1. Bezpečnostní kód V portálu pro obchodníky je vždy v sekci virtual employee vygenerován bezpečnostní kód. Jedná se o 20 znaků dlouhý text, který se poté vkládá do algoritmu jako klíč pro zabezpečení. Je velmi důležité, aby tento kód nebyl nikdy znám nikomu jinému nežli důvěryhodným osobám obchodníka a aby nebylo možné jej jednoduše zjistit například zobrazením zdrojového kódu na webu obchodníka apod. Bezpečnostní kód je v následujícím algoritmu uveden pod názvem „presharedSecret“.

8.2. Algoritmus Do zprávy se přidává jako podpis tzv messageDigest. Ten je vytvořen jako SHA256 hash z řetězce parametrů na konci doplněných o bezpečnostní kód – presharedSecret. Server vypočte tento podpis a zašle jej spolu s notifikací, nebo přesměrováním. Ověření na straně obchodníka probíhá tak, že obchodník stejným způsobem vypočte podpis ze zaslaných parametrů a bezpečnostního kódu a výsledný řetězec porovná s přijatým podpisem. Jako výstup se používá „hexadecimální“ způsob zápisu s malými písmeny a-‐f.



V programovacím jazyce může vypadat zápis například takto: messageDigest = makeSHA256Hash(sourceId + sourceTxnId + invoiceId + sourceAuthKey + paymentAmount + sourceTimestamp + presharedSecret+ TxnStatus) Zápis se může lišit dle programovacího jazyka, znak „+“ v tomto zápise značí spojení dvou řetězců za sebe. Například v jazyce PHP se použije znak „.“(tečka). Jednotlivé parametry jsou popsány v příloze A. Mezi hodnotami nejsou vkládány žádné mezery ani jiné prázdné znaky a hodnoty jsou včetně všech znaků tak jak byly zadány (je tedy nutné zahrnout i například počáteční nuly u některých parametrů) Výsledek je v hexadecimálním formátu se znaky a-‐f označenými malými písmeny. Pro vyzkoušení je možné využít online službu pro vypočítání hash např na: http://hash.online-‐convert.com/sha256-‐generator (výsledek ve verzi hex)

9. FAQs 1. Chci zapojit svůj internetový obchod pro platby pomocí Mobito

a. Nejlepší variantou je využít platební tlačítko i. S Integrací (takřka online vidíte, že bylo zaplaceno a peníze převedeny na Váš

účet) 2. Chci zapojit možnost darovat pevnou částku, nepotřebuji okamžitě vědět o všech platbách

a. Nejlepší variantou je platební tlačítko, nemusíte použít žádné integrace, stačí pouze stáhnout kód, který začleníte do svých stránek, o příchozích platbách se dozvíte buď po přihlášení do portálu obchodníka, nebo mohou chodit upozornění e-‐mailem

3. Chci zapojit své kamenné prodejny a. Nejlepší variantou je využít integraci pomocí webových služeb

4. Můj obchodní plán počítá s oslovováním zákazníků na ulici a placení na místě a. Nejlepší variantou je integrace Mobito Code



10. Příloha A Technický popis rozhraní (EN)

API Specifications for 3rd Party Integration with the MOBITO Payment System.

Table of Contents Table of Contents .................................................................................................................................. 17

1 Introduction ................................................................................. Error! Bookmark not defined.

1.1 Pre-requisites for SOAP API Integration ................... Error! Bookmark not defined.

1.2 SOAP Resources ................................................................. Error! Bookmark not defined.

1.3 Currency ISO Codes ......................................................... Error! Bookmark not defined.

2 SOAP API Integration ............................................................... Error! Bookmark not defined.

2.1 Basics ..................................................................................... Error! Bookmark not defined.

2.2 SubmitRequestForPayment Method ........................... Error! Bookmark not defined.

2.3 ConfigurePaymentNotification Method ...................... Error! Bookmark not defined.

2.4 CheckPaymentStatus Method ....................................... Error! Bookmark not defined.

2.5 GetTransactionDetail Method ........................................ Error! Bookmark not defined.

2.6 GetTransactionReport Method ...................................... Error! Bookmark not defined.

2.7 IssueRefund Method ......................................................... Error! Bookmark not defined.

3 MobitoCode Integration ........................................................... Error! Bookmark not defined.

3.1 Basics ..................................................................................... Error! Bookmark not defined.

3.2 ConfigureMobitoCodeListener ....................................... Error! Bookmark not defined.

3.3 GetMobitoCodeInfo Method ........................................... Error! Bookmark not defined.

3.4 PreValidateMobitoCodeOrder Method ........................ Error! Bookmark not defined.



4 MOBITO PayNow Button Integration .................................. Error! Bookmark not defined.

4.1 How Integration With PayNow Button Works ......... Error! Bookmark not defined.

5 Notifications ................................................................................. Error! Bookmark not defined.

6 WSDL .............................................................................................. Error! Bookmark not defined.



1 Introduction This document briefly describes the API specifications (for 3rd Party Application Integration) provided as part of the MOBITO mobile payment solution being deployed by Mopet across the Czech Republic. Merchants and 3rd parties can integrate with the MOBITO platform in three different ways depending on their preferences and technical proficiencies:

I. Direct platform-to-platform integration via the SOAP API specifications. II. MobitoCode based integration via the SOAP API specifications.

III. Web based integration via HTTPS POST (using the MOBITO PayNow button).

1.1 Pre-requisites for SOAP API Integration

• Secure IP connection to the MOBITO application server (a VPN may also be required depending on the merchant’s volume).

• Ability to initiate SOAP calls and process the responses accordingly. • Ability to accept SOAP calls and return the expected responses

accordingly.

1.2 SOAP Resources

More technical information on the SOAP protocol is available at:

http://ws.apache.org/axis2/

http://www.w3.org/TR/soap/

http://msdn.microsoft.com/webservices/

http://sourceforge.net/projects/gsoap2

1.2.1 SOAP Parameter Direction

As a matter of convention throughout this document, the direction “OUT” is used to indicate a parameter being sent from the MOBITO system to the merchant system and the direction “IN” is used to indicate a parameter being received from the merchant system by the MOBITO system.

1.3 Currency ISO Codes

More information on the various currency ISO codes is available at:

http://www.oanda.com/site/help/iso_code.shtml





2 SOAP API Integration

2.1 Basics All merchants will need to connect to the MOBITO payment service on the designated IP and port. All requests will need to conform to the SOAP protocol standards based on the specifications (WSDL) supplied by Mopet.

The following SOAP methods are available for merchants at this time:

• SubmitRequestForPayment • ConfigurePaymentNotification • CheckPaymentStatus • GetTransactionDetail • GetTransactionReport • IssueRefund

Each of the above methods requires certain source parameters (detailed below). Source IDs (which are essentially ‘virtual employee’ ids) will have to be provisioned in the Mopet databases before they can send any transactions.

2.2 SubmitRequestForPayment Method 2.2.1 Purpose

To initiate a request for payment with a configurable time validity. This requires the merchant to provide a notification channel for receiving the result of the transaction upon it’s conclusion or expiry.

2.2.2 Parameters

Parameter Name Type Direction Valid Value Mandatory Description

CustomerID String In Yes Fully qualified phone number of the beneficiary customer or nicknumber

SourceID String In Yes Source Merchant’s ID

SourceTxnID String In Yes Source Merchant’s Internal Transaction ID

SourceRefID String In No This can be used by the merchant to send a local terminal identifier or reference ID for reconciliation and reporting. It will merely be stored by the MOBITO system and is not interpreted in any manner.

TrxCode String In Text generated by Merchant, used to validate

No If provided by merchant, this will be sent by MOBITO to the customer as a notification upon successful completion



purchase (ie. eTicket code, download code etc.)

of the transaction.

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 in ABC.YY

Yes The payment amount for the transaction.

Currency String In Valid ISO code

(e.g. CZK)

Yes The ISO code of the currency in which the amount is being sent by the source

Timestamp String In Yes Source’s timestamp in the format - YYYYMMDDHH24MISS

ProductDesc String In Upto 64 chars Yes Description of service/product purchased by consumer

Validity String In Min: 30 secs

Max: 60 days from initiation

Yes The time till which the request is valid in the timestamp format –

YYYYMMDDHH24MISS

UseNotifyURL String In Y or N or D Yes If set to Y, the MOBITO system will send a success or failure/expiry notification message to this URL. If set to N, the MOBITO system will not send a notification to the merchant and the merchant will need to call the CheckPaymentStatus method to get the result of the transaction. If set to D the merchant will be informed via email or SMS. The merchant can set up this preference using the self care portal or use the API method in Section 2.4 (ConfigurePaymentNotification) to set this up

RESPONSE ON TRANSACTION RECEIPT SUCCESS

MobitoTxnID String Out Yes Transaction ID generated by the MOBITO system

MobitoMessage String Out No Additional message from MOBITO

RESPONSE ON TRANSACTION RECEIPT FAILURE

FaultCode String Out Yes Fault error code

FaultString String Out Yes Fault error message

2.2.3 Exceptions

In cases where the transaction is not successful, the following error codes will be applicable:



Code Description

22010 Invalid or Missing CustomerID

22020 Invalid or Missing SourceID

22021 SourceID not permitted to perform transaction

22022 Invalid or Missing SourceAuthKey

22030 Invalid or Missing SourceTxnID

22035 Missing InvoiceID

22040 Invalid or Missing PaymentAmount

22050 Invalid or Missing Currency Code

22070 Invalid or Missing Timestamp

22090 Invalid or Missing ProductDesc

22100 Invalid or Missing Validity

22110 Invalid or Missing UseNotifyURL flag

22120 Remote system error <code>

22130 Remote system is offline, not available

22210 Cannot locate home network for CustomerID

22310 Duplicate transaction detected

22410 Request timed out

22510 Declined by customer

22999 Unknown error <additional message, if any>

2.3 ConfigurePaymentNotification Method 2.3.1 Purpose

To configure a notification channel for receiving request for payment result notifications.

2.3.2 Parameters



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



NotificationChannel String In U – URL

E – Email

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


RESPONSE ON NOTIFICATION CONFIGURATION FAILURE



2.3.3 Notification Format & Handling

In cases where the merchant chooses the “URL” as the notification channel, the MOBITO system will send the following parameters via HTTP POST to the designated URL:


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. Format - YYYYMMDDHH24MISS

NewBalance String Out String representation in ABC.YY

Yes The balance of the merchant after the completion of the transaction

SourceTxnID String Out Yes Source Merchant’s Transaction ID or Reference Number or Tracking Number

MessageDigest String Out Yes Secure digest based on a hash plus shared secret which is returned back by the MOBITO system to enable the merchants to verify the integrity of the original request.

The merchant must acknowledge receipt of the above request via a HTTP 200 OK response. In the absence of such a response, the MOBITO system will retry twice after which the URL notifications will be automatically disabled and notification format will default to “email”.

2.3.4 MessageDigest Verification

The responsibility for verification of the message digest rests with the merchant. The shared secret used to generate the digest is provided to the merchant by Mopet via an offline mechanism for additional security and must be kept confidential at all times. The algorithm used for the digest verification is as follows:

messageDigest = makeSHA256Hash(SourceId + SourceTxnId + InvoiceId + SourceAuthKey + PaymentAmount + SourceTimestamp + PresharedSecret + TxnStatus)

There should be no spaces or other characters between the parameters and they must be in the order listed.

Here's an online hash calculator for testing verification

http://hash.online-convert.com/sha256-generator

(hex version in result is to be used)



2.3.5 Exceptions

In cases where the notification configuration is not successful, the following error codes will be applicable:

Code Description





23112 Invalid of Missing NotificationChannel

23114 Invalid or Missing ChannelValue




2.4 CheckPaymentStatus Method 2.4.1 Purpose

To check the status of a previously submitted request for payment.

2.4.2 Parameters



SourceTxnID String In Yes Source Merchant’s Original Internal Transaction ID

InvoiceID String In Yes Original Invoice ID


Timestamp String In Yes Source’s current timestamp in the format - YYYYMMDDHH24MISS

MobitoTxnID String In Yes The transaction ID sent back by the MOBITO system when the transaction was originally submitted.

RESPONSE ON TRANSACTION QUERY SUCCESS



TxnStatus String Out OK or FAILED or PENDING

Yes Status of the transaction in the MOBITO system


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


No The balance of the merchant after the completion of the transaction

SourceTxnID String Out Yes Source Merchant’s Original Internal Transaction ID

SourceRefID String Out No If sent by the merchant in the original request, this will be returned as is.

RESPONSE ON TRANSACTION QUERY FAILURE



2.4.3 Exceptions


Code Description







24080 Missing MobitoTxnID

24085 Transaction not found in MOBITO database






24150 Declined by customer


2.5 GetTransactionDetail Method 2.5.1 Purpose

To get the full details of a request for payment transaction which was previously successful.

2.5.2 Parameters



SourceTxnID String In Yes Source Merchant’s Original Internal Transaction ID






CustomerID String Out Yes Fully qualified phone number of the beneficiary customer or nicknumber

PaymentAmount String Out String representation in ABC.YY


Currency String Out Valid ISO code

(e.g. CZK)

Yes The ISO code of the currency in which the amount was sent

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






Yes The balance of the merchant after the completion of the transaction

SourceTxnID String Out Yes Source Merchant’s Original Internal Transaction ID

SourceRefID String Out No If sent by the merchant in the original request, it will be returned as is




2.5.3 Exceptions


Code Description









25086 Transaction failed due to error <code>

25087 Transaction is still pending customer confirmation






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



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.



StartDate String In Yes Start date of the intended report

format - YYYYMMDDHH24MISS

EndDate String In Yes End date of the intended report

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

R - Refunds



TotalAmount String Out String representation in ABC.YY

Yes Total transaction amount applicable for the transactions included in the report.

TotalFees String Out String representation in ABC.YY

Yes Total fees applicable for the transactions included in the report.

TotalCount String Out Yes Total number of transactions



included in the report.

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.




2.6.3 Exceptions


Code Description





26072 Invalid or Missing StartDate

26074 Invalid or Missing EndDate

26086 Invalid or Missing QueryType




2.7 IssueRefund Method 2.7.1 Purpose

To issue a refund to a customer for a previously successful payment.

2.7.2 Parameters



SourceTxnID String In Yes Source Merchant’s Original Internal



Transaction ID





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.


(e.g. CZK)

Yes The ISO code of the currency in which the original transaction was processed.

RefundFee String In String representation in ABC.YY

No Default is 0. The merchant can use this to deduct a fee from the amount refunded in case applicable.

RESPONSE ON TRANSACTION REFUND SUCCESS

RefundTxnID String Out Yes Transaction ID generated by the MOBITO system for the refund.


Yes The balance of the merchant after the completion of the refund transaction.

MobitoTxnID String Out Yes The original MOBITO transaction id for reference.

RESPONSE ON TRANSACTION REFUND FAILURE



2.7.3 Exceptions


Code Description


















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 (time-limited) 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.

3.2.2 Parameters



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





ListenerURL String In URL Yes The URL on which the merchant will be listening for MobitoCode requests.

RESPONSE ON NOTIFICATION CONFIGURATION SUCCESS






3.2.3 Exceptions


Code Description





32112 Invalid of Missing ListenerURL


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


MobitoCode String Out Yes Fully qualified phone number of the beneficiary customer or nicknumber

MobitoTxnID String 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.

RESPONSE ON CODE QUERY SUCCESS

ChoiceCount String In 0 to 9 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’.

ParamFormat String In C or CN or CF or CNF

Yes Indicates the type of parameters included with each choice.

ChoiceDetail String In Yes This must be as per the format described in the section 3.3.3 below.

SourceTxnID String 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 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

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

3.3.4 Exceptions


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


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


Choice String Out Yes Choice selected by customer

Number String Out No Quantity or variable symbol chosen by the customer

FreeText String Out No String input by the customer (e.g. address or email)

Timestamp String Out Yes Source’s timestamp in the format - YYYYMMDDHH24MISS


RESPONSE ON ORDER VALIDATION SUCCESS

SourceTxnID String In Yes Merchant’s internal transaction id for this transaction

Validity String In Min: 30 secs

Max: 60 days from initiation

Yes The time till which the reservation or prevalidation is valid in the timestamp format –

YYYYMMDDHH24MISS


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 Text generated by Merchant, used to validate purchase (ie. eTicket code, download code etc.)

No If provided by merchant, this will be sent by MOBITO to the customer as a notification upon successful completion of the transaction.




3.4.3 Exceptions


Code Description

34010 Invalid or Missing Choice

34020 Invalid Number

34022 Invalid FreeText



34112 Merchant cannot accept payment at this time





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.


CustomerID String In No Fully qualified phone number of the beneficiary customer or nicknumber if available


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



(e.g. CZK)

Yes The ISO code of the currency in which the amount is being sent


ProductDesc String In Upto 64 chars Yes Description of service/product purchased by consumer

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://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>

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 OK or FAILED Yes Status of the transaction in the MOBITO system



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



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











41090 Invalid or Missing ProductDesc

41100 Invalid SuccessURL

41110 Invalid CancelURL



41210 Cannot locate home network for CustomerID

41310 Duplicate transaction detected


41510 Rejected by customer


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)

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.



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.



6 WSDL

Please contact your Mopet Business Manager for additional information about the integration process. You may contact MoreMagic Solutions via [email protected] for additional information regarding the WSDL, test accounts and any questions regarding the API or PayNow Button integration.

11. Příloha B 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 type="hidden" name="cmd" value="_xclick" /> <input type="hidden" name="CustomerID" value="ČÍSLO KLIENTA" /> <input type="hidden" name="SourceID" value="VAŠE MERCHANT ID" /> <input type="hidden" name="SourceTxnID" value="VAŠE ČÍSLO TRANSAKCE" /> <input type=”hidden” name=”SourceRefID” value=”VAŠE ČÍSLO PRO REFERENCI” /> <input type="hidden" name="InvoiceID" value="ČÍSLO FAKTURY" /> <input type="hidden" name="SourceAuthKey" value="SOURCE AUTH KEY" /> <input type="hidden" name="PaymentAmount" value="ČÁSTKA" /> <input type="hidden" name="Currency" value="CZK" /> <input type="hidden" name="Timestamp" value="TIMESTAMP" /> <input type="submit" value="Zaplatit" /> </form>

Formulář tlačítka na mobilním webu

(změna oproti standardnímu je v zelené části)

<form action="ADRESA" method="post"> <input type="hidden" name="cmd" value="_xclick" /> <input type="hidden" name="CustomerID" value="ČÍSLO KLIENTA" /> <input type="hidden" name="SourceID" value="VAŠE MERCHANT ID" /> <input type="hidden" name="SourceTxnID" value="VAŠE ČÍSLO TRANSAKCE" /> <input type=”hidden” name=”SourceRefID” value=”VAŠE ČÍSLO PRO REFERENCI” /> <input type="hidden" name="InvoiceID" value="ČÍSLO FAKTURY" /> <input type="hidden" name="SourceAuthKey" value="SOURCE AUTH KEY" /> <input type="hidden" name="PaymentAmount" value="ČÁSTKA" /> <input type="hidden" name="Timestamp" value="TIMESTAMP" />



<input type="hidden" name="Currency" value="CZK" /> <input type="submit" value="Zaplatit" /> </form>

Vysvětlení prvků:

ADRESA: nastavení adresy platebního tlačítka.

Pro testy prosím nastavte https://mopet.moremagic.com/cui/mwallet/paymentButton

Pro produkční prostředí bude adresa sdělena po podpisu smlouvy a úspěšných testech.

ČÍ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.)

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



<input type="hidden" name="cmd" value="_xclick" />

<input type="hidden" name="Currency" value="CZK" />

Documents

Zapojení merchanta 0.4