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

Transkript

1 MOPET CZ a.s. Připojení obchodníka do systému Mobito Příručka pro integraci MOPET CZ a. s. Page 1 of 58

2 Změny v dokumentu Verze Datum Autor Popis Tomáš Severýn Vytvoření dokumentu Tomáš Severýn Úprava po interním kole připomínek Tomáš Severýn Úprava zabezpečovacího mechanismu (počítání HASH) 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 Lukáš Košík Přidána kapitola 3.6 Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka Tomáš Severýn Úpravy z původní verze, grafické úpravy Tomáš Severýn Prohození příloh A a B, aktualizace textů Tomáš Severýn Bez úprav Lukáš Košík Z kapitoly 4. odstraněn bod 3. Informace o pilotním provozu Tomáš Severýn Přidání slovníčku pojmů, drobné úpravy Tomáš Severýn Změna adresy Platebního tlačítka Lucia Slezáková Úprava textu kapitoly 2 manažerského shrnutí Úprava kapitoly 5, Pravidla pro integraci platební metody Mobita na webových stránkach obchodníka MOPET CZ a. s. Page 2 of 58

3 Obsah 1. Cíl dokumentu Manažerské shrnutí Představení společnosti Mopet a systému Mobito Možnosti připojení Náročnost implementace: Platební tlačítko: Mobito kód a připojení na rozhraní: K čemu slouží testovací prostředí: Testovací fáze: Poskytovaná podpora: Slovníček Pojmů... 8 Zkratky používané v dokumentu Platební tlačítko Obecné předpoklady scénářů: Mobito Platební Tlačítko (Bez Integrace) Mobito Platební Tlačítko (Integrace) Požadavky na zobrazení platebního tlačítka Testování platebního tlačítka Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka Integrace plateb spuštěných klientem (Mobito kód) Testování Mobito kódu Integrace WebServices požadavky na platbu Testování Web Services Integrace Notifikace Integrace WebServices - Zjištění stavu transakcí Stavy transakcí Ověření odpovědí ze systému Bezpečnostní kód Algoritmus FAQs Příloha A Kód platebního tlačítka MOPET CZ a. s. Page 3 of 58

4 Příloha B Technický popis rozhraní (EN) MOPET CZ a. s. Page 4 of 58

5 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. MOPET CZ a. s. Page 5 of 58

6 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 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. 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: 1. 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). 2. Mobito kód a připojení na rozhraní: MOPET CZ a. s. Page 6 of 58

7 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 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. 2.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í. 2.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. 2.6 Poskytovaná podpora: Společnost Mopet poskytuje podporu pro integraci obchodníka na mailové adrese: podpora.obchodnika@mopetcz.cz V případě jakýchkoliv problémů se můžete obrátit na tento mail. MOPET CZ a. s. Page 7 of 58

8 3. Slovníček Pojmů Český název Parametr Popis Číslo obchodníka Nebo SourceID Číslo obchodního místa Technického účtu, který je přidělen a vkládá se jako identifikace obchodníka Číslo uživatele (osobní): Autentizační klíč SourceAuthKey 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ý podpisový klíč presharedsecret Tajný klíč, který se vkládá do podpisového řetězce, aby zabezpečil validitu odpovědi Mobita obchodníkovi Technický účet Virtual Employee Úč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) Mobito číslo ConsumerID Číslo uživatele, od kterého požadujete, aby zaplatil Číslo transakce Mobito MobitoTxnID Číslo transakce přidělené Mobitem jednoznačný identifikátor Číslo transakce obchodníka SourceTxnId Čí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 Číslo faktury, číslo InvoiceID objednávky Referenční číslo SourceRefID 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 Časové razítko Timestamp 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 trvání platby 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 Zkratky používané v dokumentu Zkratka WSDL XML RFP 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 MOPET CZ a. s. Page 8 of 58

9 4. Platební tlačítko 4.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 4.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 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 u 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 MOPET CZ a. s. Page 9 of 58

10 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 nastavte , 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 4) Nastavte si v Portálu pro obchodníky notifikaci o provedené platbě, abyste měli přehled 5) SourceAuthKey Zobrazí 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 b) pro tlačítko 6) Na vaše webové stránky vložte HTML kód (viz příloha A) 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í. 4.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 10 of 58

11 - 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. 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 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á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 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í. 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í) MOPET CZ a. s. Page 11 of 58

12 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 ChecktPaymentStatus 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í) MOPET CZ a. s. Page 12 of 58

13 Detailní technický popis rozhraní viz Mobito API (příloha B) sd PaymentButton MerchantSystem MobitoPaymentGateway Handset POST/GET Redirect() Enter MobitoID() SendRFP() PIN() Redirect() 4.4 Požadavky na zobrazení platebního tlačítka Ve chvíli implementace požádejte na 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) 4.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 - podpora.obchodnika@mopetcz.cz s předmětem platební tlačítko - test, do kterého uveďte následující informace: 1) Kontaktní osobu 2) Předpokládaný čas možných testů 3) Název obchodníka + www stránky Testovací transakce úspěch 1) Kontaktujte podpora.obchodnika@mopetcz.cz a potvrďte si, připravenost pro testy 2) Vytvořit zkušební transakci Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 3) Stisknutí tlačítka Stisk tlačítka vyvolá přesměrování na platební bránu Mobito a) Dojde-li k přesměrování - pokračujte bodem 3) b) Pokud k přesměrování nedojde MOPET CZ a. s. Page 13 of 58

14 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 ) 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 ) Počkejte, až náš pracovník zruší transakci a) Dojde-li k přesměrování na Váš server, zkontrolujte přijetí parametrů a ověření b) Nedojde-li k přesměrování, zkontrolujte adresu, na kterou se snaží systém přesměrovat a případně ji opravte v portálu pro obchodníky Testovací transakce vypršení časového limitu 10) Kontaktujte podpora.obchodnika@mopetcz.cz a potvrďte si, že chcete testovat vypršení časového limitu 11) Vytvořit zkušební transakci Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 12) Stisknutí tlačítka Stisk tlačítka vyvolá přesměrování na platební bránu Mobito 13) Zadejte do zobrazené brány číslo ) Vyčkejte do vypršení časového limitu a) Zkontrolujte přijaté parametry MOPET CZ a. s. Page 14 of 58

15 5. Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka Základní prvky Mobita na stránkách obchodníka 1. Logo Mobita 2. Popisný text o Mobitu 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 ové adrese: podpora.obchodnika@mopetcz.cz 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. 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. MOPET CZ a. s. Page 15 of 58

16 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. MOPET CZ a. s. Page 16 of 58

17 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ý 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 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 V případě dalších dotazů prosím kontaktujte technickou podporu na ové adrese podpora.obchodnika@mopetcz.cz. MOPET CZ a. s. Page 17 of 58

18 6. 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: Scénář platby: - 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) 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 18 of 58

19 sd MobitoCo... Handset mbroker MerchantSystem GetToMobitoCodeInput() SendCode() LookupCode() GetMobitoCodeInfo() GetMobitoCodeInfo Response() DisplayChoices() Choose(Choice, Amount) validate choice and amount() PreValidateMobitoCodeOrder(choice, amount, text) PreValidateMobitoCodeOrder response() Reserve() 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 19 of 58

20 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) iii) 123auto apod. iv) Ale už ne apod. 6.1 Testování Mobito kódu Pro testování Mobito kódu prosím kontaktujte podpora.obchodnika@mopetcz.cz s předmětem mobito code test a domluvte se na detailnější podpoře ohledně testování. MOPET CZ a. s. Page 20 of 58

21 7. 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 21 of 58

22 sd RFP Flow Timeouts MerchantSystem mbroker USSD GW Handset StartRFP(validity) RFP Notification(Info) AcceptReject() InsertPIN() PIN() Notofication() 7.1 Testování Web Services Testovací transakce úspěch 1) Kontaktujte a potvrďte si, připravenost pro testy 2) Vytvořit zkušební transakci ve vašem systému vytvořte transakci s consumerid a po web services kontaktujte server Mobito na adrese 3) Zjistěte, zda Vám webservice potvrdila příjem 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 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 22 of 58

23 Testovací transakce vypršení časového limitu 12) Kontaktujte 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 a po web services kontaktujte server Mobito na adrese 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 23 of 58

24 8. 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 24 of 58

25 9. 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. 9.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 v době expirace Klient Zadá PIN po expiraci Sběrný proces expirovaných transakcí [NE] [bez interakce] [ANO] validace [zadá PIN] [Proběhl] [čekání ve stavu PENDING] [validace OK] [neprošlo validací] OK FAILED konec MOPET CZ a. s. Page 25 of 58

26 10. 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 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 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: (výsledek ve verzi hex) MOPET CZ a. s. Page 26 of 58

27 11. 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í em 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 27 of 58

28 Formulář standardního tlačítka: Příloha A Kód platební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="hidden" name="productdesc" value="product" /> <input type="submit" value="zaplatit" /> </form> 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 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="productdesc" value="product" /> <input type="hidden" name="currency" value="czk" /> <input type= hidden name= forcemobile value= on /> <input type="submit" value="zaplatit" /> </form> MOPET CZ a. s. Page 28 of 58

29 Vysvětlení prvků: ADRESA: nastavení adresy platebního tlačítka. Pro testy prosím nastavte 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ř NapřPro :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 29 of 58

30 <input type="hidden" name="cmd" value="_xclick" /> <input type="hidden" name="currency" value="czk" /> MOPET CZ a. s. Page 30 of 58

31 Příloha B Technický popis rozhraní (EN) API Specifications for 3 rd Party Integration with the MOBITO Payment System. Table of Contents Table of Contents Introduction Pre-requisites for SOAP API Integration SOAP Resources Currency ISO Codes SOAP API Integration Basics SubmitRequestForPayment Method ConfigurePaymentNotification Method CheckPaymentStatus Method GetTransactionDetail Method GetTransactionReport Method IssueRefund Method MobitoCode Integration Basics ConfigureMobitoCodeListener GetMobitoCodeInfo Method MOPET CZ a. s. Page 31 of 58

32 3.4 PreValidateMobitoCodeOrder Method MOBITO PayNow Button Integration How Integration With PayNow Button Works Notifications MOPET CZ a. s. Page 32 of 58

33 1 Introduction This document briefly describes the API specifications (for 3 rd Party Application Integration) provided as part of the MOBITO mobile payment solution being deployed by Mopet across the Czech Republic. Merchants and 3 rd 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: 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: MOPET CZ a. s. Page 33 of 58

34 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 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 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 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. MOPET CZ a. s. Page 34 of 58

35 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 Currency String In Valid ISO code (e.g. CZK) Yes Yes The payment amount for the transaction. 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 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 Exceptions In cases where the transaction is not successful, the following error codes will be applicable: Code Description Invalid or Missing CustomerID MOPET CZ a. s. Page 35 of 58

36 22020 Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing SourceTxnID Missing InvoiceID Invalid or Missing PaymentAmount Invalid or Missing Currency Code Invalid or Missing Timestamp Invalid or Missing ProductDesc Invalid or Missing Validity Invalid or Missing UseNotifyURL flag Remote system error <code> Remote system is offline, not available Cannot locate home network for CustomerID Duplicate transaction detected Request timed out Declined by customer Unknown error <additional message, if any> 2.3 ConfigurePaymentNotification Method Purpose To configure a notification channel for receiving request for payment result notifications Parameters Parameter Name Type Direction Valid Value Mandatory Description SourceID String In Yes Source Merchant s ID SourceTxnID String In No Source Merchant s Internal Transaction ID. This is merely for the merchant to be able to track multiple configuration requests and has no MOPET CZ a. s. Page 36 of 58

37 bearing on the actual configuration. SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s timestamp in the format - YYYYMMDDHH24MISS NotificationChannel String In U URL E 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 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 below. ChannelValue String In Yes The URL or the address on which the notification must be sent. RESPONSE ON NOTIFICATION CONFIGURATION SUCCESS MobitoTxnID String Out Yes Transaction ID generated by the MOBITO system for the purpose of tracking this configuration MobitoMessage String Out No Additional message from MOBITO RESPONSE ON NOTIFICATION CONFIGURATION FAILURE FaultCode String Out Yes Fault error code FaultString String Out Yes Fault error message Notification Format & Handling In cases where the merchant chooses the URL as the notification channel, the MOBITO system will send the following parameters via HTTP POST to the designated URL: Parameter Name Type Direction Valid Value Mandatory Description TxnStatus String Out OK or FAILED Yes Status of the transaction in the MOBITO system MobitoTxnID String Out Yes Original Transaction ID generated by the MOBITO system CompletionTS String Out Yes The timestamp of the completion of the transaction is reported here. Format - YYYYMMDDHH24MISS MOPET CZ a. s. Page 37 of 58

38 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 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 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 (hex version in result is to be used) Exceptions In cases where the notification configuration is not successful, the following error codes will be applicable: Code Description Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing Timestamp MOPET CZ a. s. Page 38 of 58

39 23112 Invalid of Missing NotificationChannel Invalid or Missing ChannelValue Remote system error <code> Remote system is offline, not available Unknown error <additional message, if any> 2.4 CheckPaymentStatus Method Purpose To check the status of a previously submitted request for payment Parameters Parameter Name Type Direction Valid Value Mandatory Description SourceID String In Yes Source Merchant s ID SourceTxnID String In Yes Source Merchant s Original Internal Transaction ID InvoiceID String In Yes Original Invoice ID SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s current timestamp in the format - YYYYMMDDHH24MISS MobitoTxnID String In Yes The transaction ID sent back by the MOBITO system when the transaction was originally submitted. RESPONSE ON TRANSACTION QUERY SUCCESS TxnStatus String Out OK or FAILED or PENDING Yes Status of the transaction in the MOBITO system MobitoTxnID String Out Yes Original Transaction ID generated by 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 NewBalance String Out String representation No The balance of the merchant after the completion of the transaction MOPET CZ a. s. Page 39 of 58

40 in ABC.YY 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 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 Exceptions In cases where the call to CheckPaymentStatus is not successful, the following error codes will be applicable: Code Description Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing SourceTxnID Missing InvoiceID Invalid or Missing Timestamp Missing MobitoTxnID Transaction not found in MOBITO database Remote system error <code> Remote system is offline, not available Unknown error <additional message, if any> MOPET CZ a. s. Page 40 of 58

41 2.5 GetTransactionDetail Method Purpose To get the full details of a request for payment transaction which was previously successful Parameters Parameter Name Type Direction Valid Value Mandatory Description SourceID String In Yes Source Merchant s ID SourceTxnID String In Yes Source Merchant s Original Internal Transaction ID InvoiceID String In Yes Original Invoice ID SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s current timestamp in the format - YYYYMMDDHH24MISS MobitoTxnID String In Yes The transaction ID sent back by the MOBITO system when the transaction was originally submitted. RESPONSE ON TRANSACTION QUERY SUCCESS 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) Fee String Out String representation in ABC.YY Yes Yes Yes The payment amount for the transaction. The ISO code of the currency in which the amount was sent 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 NewBalance String Out String representation Yes The balance of the merchant after the completion of the transaction MOPET CZ a. s. Page 41 of 58

42 in ABC.YY 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 RESPONSE ON TRANSACTION QUERY FAILURE 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 Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing SourceTxnID Missing InvoiceID Invalid or Missing Timestamp Missing MobitoTxnID Transaction not found in MOBITO database Transaction failed due to error <code> Transaction is still pending customer confirmation Remote system error <code> Remote system is offline, not available Unknown error <additional message, if any> 2.6 GetTransactionReport Method Purpose To download a transaction report in.csv format based on a simple parameterized query. MOPET CZ a. s. Page 42 of 58

43 2.6.2 Parameters Parameter Name Type Direction Valid Value Mandatory Description SourceID String In Yes Source Merchant s ID SourceTxnID String In No Source Merchant s Internal Transaction ID. This is merely for the merchant to be able to track multiple report requests and has no bearing on the actual report. SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s current timestamp in the format - YYYYMMDDHH24MISS 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: RESPONSE ON TRANSACTION QUERY SUCCESS F Fund outs I Incoming payments S Sales R - Refunds MobitoTxnID String Out Yes Original Transaction ID generated by the MOBITO system TotalAmount String Out String representation in ABC.YY TotalFees String Out String representation in ABC.YY Yes Yes Total transaction amount applicable for the transactions included in the report. 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. MOPET CZ a. s. Page 43 of 58

44 RESPONSE ON TRANSACTION QUERY FAILURE 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 Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing Timestamp Invalid or Missing StartDate Invalid or Missing EndDate Invalid or Missing QueryType Remote system error <code> Remote system is offline, not available Unknown error <additional message, if any> 2.7 IssueRefund Method Purpose To issue a refund to a customer for a previously successful payment Parameters Parameter Name Type Direction Valid Value Mandatory Description SourceID String In Yes Source Merchant s ID SourceTxnID String In Yes Source Merchant s Original Internal Transaction ID InvoiceID String In Yes Original Invoice ID SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO MOPET CZ a. s. Page 44 of 58

45 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 Currency String In Valid ISO code (e.g. CZK) RefundFee String In String representation in ABC,YY RESPONSE ON TRANSACTION REFUND SUCCESS Yes Yes No Original amount for the transaction to be refunded. This must match the amount in the original transaction. The ISO code of the currency in which the original transaction was processed. Default is 0. The merchant can use this to deduct a fee from the amount refunded in case applicable. RefundTxnID String Out Yes Transaction ID generated by the MOBITO system for the refund. NewBalance String Out String representation in ABC,YY 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 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 Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing SourceTxnID Missing InvoiceID Invalid or Missing PaymentAmount Invalid or Missing Currency Code MOPET CZ a. s. Page 45 of 58

46 27070 Invalid or Missing Timestamp Missing MobitoTxnID Transaction not found in MOBITO database Remote system error <code> Remote system is offline, not available Unknown error <additional message, if any> MOPET CZ a. s. Page 46 of 58

47 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 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 Parameters Parameter Name Type Direction Valid Value Mandatory Description SourceID String In Yes Source Merchant s ID SourceTxnID String In No Source Merchant s Internal Transaction ID. This is merely for the 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 MOPET CZ a. s. Page 47 of 58

48 Timestamp String In Yes Source s timestamp in the format - YYYYMMDDHH24MISS ListenerURL String In URL Yes The URL on which the merchant will be listening for MobitoCode requests. 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 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 Invalid or Missing SourceID SourceID not permitted to perform transaction Invalid or Missing SourceAuthKey Invalid or Missing Timestamp Invalid of Missing ListenerURL Remote system error <code> MOPET CZ a. s. Page 48 of 58

49 3.3 GetMobitoCodeInfo Method 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) Parameters Parameter Name Type Direction Valid Value Mandatory Description 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 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 FaultCode String Out Yes Fault error code FaultString String Out Yes Fault error message MOPET CZ a. s. Page 49 of 58

50 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 ) 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 Movie2,N3,Type Would trigger a choice of movies with Movie1 having a limit of max. 4 tickets plus an optional input request for the customer and Movie2 having a limit of max. 3 tickets with a similar input request for the customer. MOPET CZ a. s. Page 50 of 58

51 3.3.4 Exceptions Dokument: Vlastník: Tomáš Severýn Vytvořen: In cases where the transaction is not successful, the following error codes will be applicable: Code Description Invalid or Missing MobitoCode MobitoCode Linked Product/Service Sold Out MobitoCode Linked Product/Service No Longer Available Merchant system is offline, not available Unknown error <additional message, if any> 3.4 PreValidateMobitoCodeOrder Method 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 Parameters Parameter Name Type Direction Valid Value Mandatory Description 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 ) Timestamp String Out Yes Source s timestamp in the format - YYYYMMDDHH24MISS MobitoTxnID String Out Yes Transaction ID generated by the MOBITO system 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 SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO MOPET CZ a. s. Page 51 of 58

52 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.) RESPONSE ON NOTIFICATION CONFIGURATION FAILURE No If provided by merchant, this will be sent by MOBITO to the customer as a notification upon successful completion of the transaction. 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 Invalid or Missing Choice Invalid Number Invalid FreeText Missing MobitoTxnID Invalid or Missing Timestamp Merchant cannot accept payment at this time Remote system is offline, not available Unknown error <additional message, if any> MOPET CZ a. s. Page 52 of 58

53 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 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. Parameter Name Type Direction Valid Value Mandatory Description CustomerID String In No Fully qualified phone number of the beneficiary customer or nicknumber if available 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 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 MOPET CZ a. s. Page 53 of 58