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 76 v1.7

2 MOPET CZ a. s. Page 2 of 76 v1.7

3 Obsah 1. Manažerské shrnutí Představení společnosti Mopet a systému Mobito Možnosti připojení Náročnost implementace: K čemu slouží testovací prostředí: Testovací fáze: Poskytovaná podpora: Slovníček pojmů Používané termíny Používané zkratky Platební tlačítko (nová verze) 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 Základní prvky Mobita na stránkách obchodníka Pravidla pro používání základních prvků Ověření odpovědí ze systému Bezpečnostní kód Algoritmus 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 MOPET CZ a. s. Page 3 of 76 v1.7

4 12. FAQs Příloha A Kód platebního tlačítka Příloha B Technický popis rozhraní (EN) Cíl dokumentu Cílem tohoto dokumentu je seznámit obchodníky s možnostmi zapojení do systému Mobito a zároveň je provést procesem připojování jednotlivých kanálů. Součástí tohoto dokumentu jsou všechny informace nutné k implementaci, integraci a otestování vybrané platební metody společnosti Mopet CZ. MOPET CZ a. s. Page 4 of 76 v1.7

5 1. Manažerské shrnutí 1.1. Představení společnosti Mopet a systému Mobito Společnost MOPET CZ a.s. je akciová společnost, jejímiž spoluvlastníky jsou čeští mobilní operátoři O2 Telefónica, T-Mobile, Vodafone, a bankovní domy Česká spořitelna, GE Money Bank, Raiffeisenbank a UniCredit Bank. Základním cílem společnosti je vybudovat transakční centrum pro mobilní platby a uvést na český trh službu Mobito, umožňující platit a posílat peníze v reálném čase přes mobilní telefon tam, kde nyní zákazníci používají převážně hotovost, bez ohledu na to, jakou mají banku či mobilního operátora. Mobitem půjde platit za zboží a služby, hradit složenky a faktury, posílat si mezi sebou peníze či zaplatit mobilním telefonem nákup na internetu nebo v mobilu. Mobito je nový platební standard na českém trhu, který umožňuje zákazníkům platit prostřednictvím mobilních telefonů za zboží a služby. Hlavním prvkem Mobita je tzv. request for payment žádost k zaplacení, kterou dostává zákazník do svého mobilu a potvrzuje ji PINem. Mobito je zdarma, funguje ve všech mobilních telefonech a pro klienty všech českých bank a mobilních operátorů. Mobito má ambici stát se synonymem pro peníze v mobilu a inovativní univerzální platební metodu, která bude mít své pevné místo vedle hotovosti a platebních karet. Peníze v mobilu, jinak než je doposud znáte, to je Mobito 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 Náročnost implementace: Platební tlačítko: Společnost MOPET CZ se snaží maximálně zjednodušit přístup ke svým platebním metodám pro maximálně širokou skupinu obchodníků. Na základě této dlouhodobé vize jsme se pokusili navrhnout připojení na platební bránu v maximálně zjednodušené podobě. Předpokládána náročnost implementace základní funkčnosti by měla být do 1 MD (práce člověka za jeden osmihodinový den). Mobito kód a připojení na rozhraní: Tato funkcionalita je o něco složitější, protože vyžaduje znalosti a zkušenost s implementací webových služeb, větší znalost vnitřních procesů obchodníka a náročnější způsob připojení na MOPET CZ a. s. Page 5 of 76 v1.7

6 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 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í 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 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 6 of 76 v1.7

7 2. Slovníček pojmů 2.1. Používané termíny Č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 2.2. Používané zkratky 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 7 of 76 v1.7

8 3. Platební tlačítko (nová verze) 3.1. Obecné předpoklady scénářů: Klient Fyzická osoba zaregistrována a aktivována do služby Mobito. Klient má na účtu dostatek prostředků na zaplacení poptávané služby / vybraného zboží (klient má možnost zaplatit zboží i bez předchozí dotace účtu klient s online připojeným platebním instrumentem) Obchodník Fyzická nebo právnická osoba, se kterou je uzavřena smlouva s firmou MOPET CZ. Obchodník je zaregistrován a aktivován do služby Mobito 3.2. Mobito Platební Tlačítko (Bez Integrace) Popis Platební tlačítko bez integrace slouží například pro nadace / občanská sdružení (OS), která chtějí využít možnosti přes Mobito zaslat dar, pokud chcete jakkoliv automatizovaně reagovat na zaslanou platbu pokračujte prosím další kapitolou. Uživatelská zkušenost: - Klient chce vložit dar přes web nebo mobilní web nadace - Obchodník / OS - chce na své stránky zobrazit tlačítko darujte a není možné jakékoliv složité programování Scénář platby: - Klient (web OS) stiskne tlačítko darovat, - Web OS přesměrování klienta na platební bránu Mobito a předání údajů o platbě (částka, popis) - Klient (platební brána Mobito) zadání Mobito ID (tel. čísla / ID) a potvrzení platby. - Mobito systém zaslání požadavku na platbu na telefonní číslo klienta registrované u Mobito účtu (nativní notifikace, USSD notifikace) - Klient (mobilní telefon) přijetí a autorizace transakce unikátním PINem - Mobito systém ověření transakce a notifikace o úspěšném zaplacení notifikace klientovi a zaslání potvrzujícího 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 MOPET CZ a. s. Page 8 of 76 v1.7

9 Jak to udělat / Nastavení pro platbu: 1) Přihlášení se do portálu pro obchodníky pomocí administrátorského účtu, který obdržíte při podpisu smlouvy 2) Nastavení obchodního místa vytvoření Virtuálního zaměstnance a) Vytvořte pomocí návodu základní strukturu jednoho Virtuálního zaměstnance přímo pod svým účtem b) WWW adresu, kterou chcete, aby se zobrazila v Mobito bráně vložte do parametru Název Virtuálního zaměstnance c) Odpověď na 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. 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 (příklady notifikačních ů viz Příloha B ové notifikace o stavu transakce) 5) SourceAuthKey (Autentizační klíč) - obrazí se na výpisu detailů Virtuálního zaměstnance a) Tento klíč, stejně jako vaše Identifikační číslo (SourceID) vložte do předpřipraveného kódu pro tlačítko 6) Na vaše webové stránky vložte HTML kód (viz příloha B) s jednoduchým platebním tlačítkem s přednastavenou částkou (případně několik tlačítek s různými částkami nebo tlačítko s možností uživatelské editace částky). Do pole Timestamp vložte aktuální datum. 7) Celou implementaci je možné provést bez programování. Popis 3.3. Mobito Platební Tlačítko (Integrace) Platební tlačítko umožňuje začlenit Mobito jako platební metodu např. do e-shopu obchodníka sloužící k okamžitému zaplacení zboží. Uživatelská zkušenost: MOPET CZ a. s. Page 9 of 76 v1.7

10 Scénář platby: - 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. 1) Klient (web obchodníka) výběr zboží nebo služby na webu obchodníka, výběr platební metody Mobito a potvrzení platby. 2) Web obchodníka přesměrování klienta na platební bránu Mobito a předání údajů o platbě (částka, popis zboží / služby) 3) Klient (platební brána Mobito) zadání Mobito ID (tel. čísla / ID) a potvrzení platby. 4) Mobito systém zaslání požadavku na platbu na tel. číslo klienta registrované u Mobito účtu (nativní notifikace, USSD notifikace) 5) Klient (mobilní telefon) přijetí a autorizace transakce unikátním PINem 6) Mobito systém ověření transakce a notifikuje o úspěšném zaplacení Klient: zobrazení informace o stavu dokončení transakce a následné přesměrování na web Obchodníka (Success/failed URL součástí, kterého je i ověřený podpis viz kapitola 6. Ověření odpovědí ze systému) Obchodník: Zobrazení stavu dokončené transakce v Mobito portálu Obchodníka Na tuto adresu poté přijde z našeho serveru GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole Ověření klienta Mobito systém zašle z našeho serveru na vydefinovanou URL adresu obchodníka GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole 6. Ověření odpovědí ze systému 1 Mobito systém po zaplacení odešle na vydefinovaný správu obsahující informace o dokončených transakcích (viz Příloha B ové notifikace o stavu transakce) - součástí předávané informace je i ověřený podpis viz kapitola 7. Ověření API integrací je možné zavolat ChecktPaymentStatus, kde je uveden status platby (viz kapitola 8. Integrace WebServices požadavky na platbu) 7) Klient (web obchodníka) klientovi je zobrazena notifikace o úspěšném zaplacení zboží/služby, poděkování případně další instrukce. a) Obchodník - ověří platnost odpovědi brány pomocí ověření podpisu (viz kapitola 6. Ověření odpovědí ze systému) 1 Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 1 minuta). Může tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 0:59 minut). MOPET CZ a. s. Page 10 of 76 v1.7

11 Alternativy scénáře A) Předvyplnění Mobito ID - Web obchodníka předá platební bráně Mobito ID zákazníka (bude předvyplněno) krok 2 B) Transakce nedokončena / neautorizována - V případě neúspěšného potvrzení transakce (klient neautorizoval transakci, vypršel limit) je klient přesměrován na web obchodníka (definovaná failure chybová - URL), obchodníkovi je tentostav sdělen na vydefinované URL/ C) Transakce dokončena, ale klient uzavřel Mobito platební bránu před přesměrováním na web obchodníka a. Obchodník může zjistit stav transakce v manuálně portálu pro obchodníky b. v případě nastavení technického účtu (virtual employee), aby po zaplacení vyvolal URL adresu obchodníka na, kterou předá informace o dokončených transakcích (zaplaceno/selhalo s důvodem selhání) bude tato informace předána i v případě, kdy klient uzavře webovou bránu před přesměrováním na web obchodníka c. v případě nastavení technického účtu (virtual employee), aby po zaplacení odeslal na vydefinovaný správu obsahující informace o dokončených transakcích, bude tento zaslán i v případě, kdy klient uzavře webovou bránu před přesměrováním na web obchodníka d. V případě API integrace je možné zavolat ChecktPaymentStatus, kde je uveden status platby i v případě, kdy klient uzavře webovou bránu před přesměrováním na web obchodníka D) Notifikace o dokončené transakce není možné na vydefinované URL doručit Mobito systém se pokusí na vydefinované URL informaci o dokončené transakci předat celkem 3 krát (volání po 3 sekundách). V případě že i třetí volání selže, pošle Mobito systém informace o dokončené transakci automaticky na ovou adresu vydefinovanou jako kontaktní daného technického účtu (virtual emploee) E) Notifikace o dokončené transakce není možné na vydefinované URL doručit a technický účet nemá vydefinovanou kontaktní ovou adresu V takovém případě pošle Mobito systém informace o dokončené transakci automaticky na ovou adresu vydefinovanou jako kontaktní Obchodníka. Jak to udělat / Nastavení pro platbu MOPET CZ a. s. Page 11 of 76 v1.7

12 1) Přihlášení se do portálu pro obchodníky pomocí administrátorského účtu, který obdržíte při podpisu smlouvy 2) Nastavení obchodního místa - vytvoření Virtuálního zaměstnance a) Vytvořte pomocí návodu základní strukturu obchodu 1 Virtuálního zaměstnance přímo pod svým účtem obchodníka nebo pod některou Vaší pobočkou b) WWW adresu obchodu, kterou chcete, aby se zobrazila na Mobito Bráně vložte do parametru Název Virtuálního zaměstnance c) Při notifikaci o dokončené transakce vyvoláním URL nastavení URL notifikace (v tomto případě vyplňte pro potřeby alternativního scénáře u daného technického účtu i pole s pro kontaktní ) d) Při notifikaci o dokončené transakce zasláním u nastavte emilovou adresu, kam budou notifikace zasílané 3) Nastavení adres pro přesměrování na bránu a) U Virtuálního zaměstnance nastavte adresy, na které bude zákazník přesměrován v případě úspěchu případně neúspěchu transakce b) Tyto adresy musí být ve tvaru 4) SourceAuthKey, SecurityToken Zobrazí se na výpisu detailů Virtuálního zaměstnance a) SourceAuthKey se použije při odesílání požadavku na bránu a slouží namísto hesla. Generuje systém po vytvoření Virtuálního Employee b) SecurityToken slouží pro zajištění bezpečnosti návratu, tento kód se poté použije pro podpis a na Vaší straně pro ověření podpisu zpráv o zaplacení. Technické požadavky integrace: - Odeslání požadavku na platbu - integrace platebního tlačítka Mobito na web obchodníka (HTTP POST protokol) - Přijetí výsledku transakce schopnost přijetí a zobrazení výsledku transakce na definovaném URL obchodníka (nastavení success / failure URL na Mobito portálu obchodníka), pokud obchodník vyžaduje ověření, schopnost vypočítat kontrolní součet (viz kapitola ověření) Schéma rozhraní MOPET CZ a. s. Page 12 of 76 v1.7

13 sd PaymentButton MerchantSystem MobitoPaymentGateway Handset POST/GET Redirect() Enter MobitoID() SendRFP() PIN() Redirect() 3.4. Požadavky na zobrazení platebního tlačítka Ve chvíli implementace požádejte na o zaslání grafických podkladů. V rámci těchto grafických podkladů jsou: Ikony, které je možné uvést v seznamu platebních metod, případně v patičce stránek Ikony, které požadujeme uvést v případě výběru platební metody Pozadí pro platební tlačítko (pokud takové využíváte) MOPET CZ a. s. Page 13 of 76 v1.7

14 4. Testování platebního tlačítka Pro ověření funkčnosti platebního tlačítka nejprve nastavte tlačítko dle návodu v kapitolách výše. Pro testování prosím kontaktujte alespoň týden předem - 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 V odpovědi obdržíte nejen datum a čas možného testování, ale také číslo klienta se kterým je možné testovat (který Vám transakci potvrdí, zruší, či nechá vypršet) Testovací transakce úspěch 1) Kontaktujte podpora.obchodnika@mopetcz.cz a potvrďte si, připravenost pro testy 2) Vytvořit zkušební transakci Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 3) Stisknutí tlačítka Stisk tlačítka vyvolá přesměrování na platební bránu Mobito a) Dojde-li k přesměrování - pokračujte bodem 3) b) Pokud k přesměrování nedojde i) Zkontrolujte, zda se Vám zobrazilo tlačítko správně (nikoliv jako kód <form ) ii) Zkontrolujte, zda Váš prohlížeč neotevírá jiné okno iii) Zkontrolujte, že máte správné informace ve zdrojovém kódu stránky 4) Zadejte do zobrazené brány číslo pro potvrzení (obdržíte od společnosti MOPET CZ) 5) Počkejte, až náš pracovník potvrdí transakci a) Dojde-li k přesměrování na Váš server, zkontrolujte přijetí parametrů a ověření (viz kapitola Bezpečnostní kód a algoritmus pro jeho vytvoření) b) Nedojde-li k přesměrování, zkontrolujte adresu, na kterou se snaží systém přesměrovat a případně ji opravte v portálu pro obchodníky Testovací transakce neúspěch 6) Vytvořit zkušební transakci Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 7) Stisknutí tlačítka Stisk tlačítka vyvolá přesměrování na platební bránu Mobito 8) Zadejte do zobrazené brány číslo pro zrušení (obdržíte od společnosti MOPET CZ) 9) Počkejte, až náš pracovník zruší transakci a) Dojde-li k přesměrování na Váš server, zkontrolujte přijetí parametrů a ověření b) Nedojde-li k přesměrování, zkontrolujte adresu, na kterou se snaží systém přesměrovat a případně ji opravte v portálu pro obchodníky MOPET CZ a. s. Page 14 of 76 v1.7

15 Testovací transakce vypršení časového limitu 10) Kontaktujte a potvrďte si, že chcete testovat vypršení časového limitu 11) Vytvořit zkušební transakci Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 12) Stisknutí tlačítka Stisk tlačítka vyvolá přesměrování na platební bránu Mobito 13) Zadejte do zobrazené brány číslo pro vypršení (obdržíte od společnosti MOPET CZ) 14) Vyčkejte do vypršení časového limitu a) Zkontrolujte přijaté parametry MOPET CZ a. s. Page 15 of 76 v1.7

16 5. Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka 5.1. Základní prvky Mobita na stránkách obchodníka 1. Logo Mobita 2. Popisný text o Mobitu 5.2. Pravidla pro používání základních prvků 1. Logo Mobita Formát loga Použití loga Mobita se vždy řídí seznamem povolených velikostí, které jsou k dispozici v grafickém balíku. Grafický balík log je zasílaný spolu s integračním manuálem pro obchodníka. V případě, že z jakéhokoliv důvodu nemůžete použit ani jednu variantu, kontaktujte technickou podporu na 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 16 of 76 v1.7

17 V takovém případě logo nemůže být klikatelné a odkazovat například na stránky Mobita, ale musí působit jako označení platební metody. Výběr Mobita jako platební metody nemusí obsahovat logo a to v případě, že seznam ostatních platebních metod neobsahuje jejich loga. V takovém případě musí být platební metoda označena textově názvem služby s velkým začátečním písmenem Mobito. V případě, že je platební metoda doplněna o krátký popisný text, doporučujeme následující spojení: Platba Mobitem Zaplať Mobitem Zaplať mobilem přes Mobito Umístění loga Logo Mobita musí být uvedeno jako identifikátor platební metody u ostatních platebních metod, které může zákazník použít na stránkách obchodníka. Zpravidla jsou loga umístěna v zápatí stránek, které zákazník vidí na úvodní stránce webshopu a při výběru platební metody v košíku objednávky. V případě, že má obchodník k dispozici samostatnou stránku, která uvádí seznam všech platebních metod, musí být Mobito identifikované na této stránce logem a krátkým popisným textem. Popisný text o Mobitu Vzhledem k tomu, že Mobito je nová platební metoda na trhu, je vhodné zákazníky obeznámit stručným popisem o této metodě. Připravili jsme pro vás 3 různé varianty popisného textu, který MOPET CZ a. s. Page 17 of 76 v1.7

18 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. Upozornění: Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 1 minuta). Může tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 0:59 minut). MOPET CZ a. s. Page 18 of 76 v1.7

19 6. Ověření odpovědí ze systému Metody upozornění na platbu (Notification a přesměrování z platební brány) obsahují kromě údajů o transakci i podpis. Takto může obchodník jednoduše zjistit, že není daná informace o transakci podvržená a není nutné další zjišťování výsledku transakce 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 19 of 76 v1.7

20 7. Integrace plateb spuštěných klientem (Mobito kód) Popis Pokud chcete využít mobilní telefon klientů jako nákupní prostředí, je možné integrovat je pomocí rozhraní Mobito kódu. Uživatelská zkušenost: 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 20 of 76 v1.7

21 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 21 of 76 v1.7

22 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 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 22 of 76 v1.7

23 8. Integrace WebServices požadavky na platbu Popis Pokud chcete využít Mobito jako platební metodu spouštěnou jiným způsobem nežli klientem přímo z mobilu (Mobito kód) nebo pomocí webového rozhraní, je pro Vás připraveno WebServices rozhraní. Toto slouží k zakládání požadavků na platbu (Request for Payment) a zjišťování stavu transakcí. Uživatelská zkušenost: - Klient Nákup na pokladně nebo v systému, který komunikuje s klientem napřímo nebo vzdáleně (jakýkoliv informační kanál, který umí zjistit od klienta ID v systému Mobito aby mu zaslal požadavek na platbu) Scénář platby: 1) Klient (obecně) vyjádří přání nakoupit zboží u obchodníka a dokončí objednávku 2) Obchodník Vyžádá si od klienta jeho číslo (telefonní, nebo Mobito přezdívku), to zadá do svého systému a) Způsob vyžádání je ponechán na procesní a technické realizaci obchodníka může se jednat například o: i) Zákazník sdělí pokladnímu své číslo ii) Číslo může být navázáno na věrnostní kartu, NFC chip, Čárový kód apod. iii) Číslo může být předáno bezdrátově pomocí mobilní aplikace, mobilního webu 3) Mobito systém zaslání požadavku na platbu na tel. číslo klienta (nativní notifikace, USSD notifikace) 4) Klient (mobilní telefon) přijetí a autorizace transakce unikátním PINem 5) Mobito systém ověření transakce a notifikace o úspěšném zaplacení notifikace klientovi a notifikace webu obchodníkovi. a) Alternativně Obchodník dotazuje Mobito systém funkcí CheckPaymentStatus MOPET CZ a. s. Page 23 of 76 v1.7

24 sd RFP Flow Timeouts MerchantSystem mbroker USSD GW Handset StartRFP(validity) RFP Notification(Info) AcceptReject() InsertPIN() PIN() Notofication() 8.1. Testování Web Services Testovací transakce úspěch 1) Kontaktujte 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 24 of 76 v1.7

25 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 25 of 76 v1.7

26 9. Integrace Notifikace Funkcionalita notifikace funguje pro všechny typy integrací. Pro správnou funkcionalitu nastavte v portálu pro obchodníky u virtuálního zaměstnance notifikační URL. Na tuto adresu poté přijde z našeho serveru GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole Ověření klienta. Alternativně je možné nastavit tento parametr pomocí webové služby ConfigurePaymentNotification. Upozornění: Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 5 minut). Může tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 4:59 minut). MOPET CZ a. s. Page 26 of 76 v1.7

27 10. Integrace WebServices - Zjištění stavu transakcí Webové služby nabízí funkce pro zjištění stavu transakce, získání více informací o úspěšně proběhlé transakci a Získání detailních informací o seznamu transakcí. Jsou to následující funkce: CheckPaymentStatus o Zjištění stavu aktuálně prováděné transakce pro rychlý processing, jsou zde všechny požadavky na platbu GetTransactionDetail o Zjištění detailu o transakci zde je možné dohledat pouze úspěšně dokončené transakce GetTransactionReport o Získání seznamu transakcí, systém v této funkci také vrátí časově omezený link na stažení vygenerovaného CSV souboru pro strojové zpracování transakční historie 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 27 of 76 v1.7

28 11. Ověření odpovědí ze systému Metody upozornění na platbu (Notification a přesměrování z platební brány) obsahují kromě údajů o transakci i podpis. Takto může obchodník jednoduše zjistit, že není daná informace o transakci podvržená a není nutné další zjišťování výsledku transakce 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 28 of 76 v1.7

29 12. FAQs 1. Chci zapojit svůj internetový obchod pro platby pomocí Mobito a. Nejlepší variantou je využít platební tlačítko i. S Integrací (takřka online vidíte, že bylo zaplaceno a peníze převedeny na Váš účet) 2. Chci zapojit možnost darovat pevnou částku, nepotřebuji okamžitě vědět o všech platbách a. Nejlepší variantou je platební tlačítko, nemusíte použít žádné integrace, stačí pouze stáhnout kód, který začleníte do svých stránek, o příchozích platbách se dozvíte buď po přihlášení do portálu obchodníka, nebo mohou chodit upozornění 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 29 of 76 v1.7

30 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 30 of 76 v1.7

31 Vysvětlení prvků: ADRESA: nastavení adresy platebního tlačítka. Pro testy prosím nastavte Pro produkční prostředí prosím nastavte: ČÍ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 31 of 76 v1.7

32 <input type="hidden" name="cmd" value="_xclick" /> <input type="hidden" name="currency" value="czk" /> MOPET CZ a. s. Page 32 of 76 v1.7

33 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 MOPET CZ a. s. Page 33 of 76 v1.7

34 1.3 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 PreValidateMobitoCodeOrder Method MOBITO PayNow Button Integration How Integration With PayNow Button Works Notifications MOPET CZ a. s. Page 34 of 76 v1.7

35 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. MOPET CZ a. s. Page 35 of 76 v1.7

36 1.3 Currency ISO Codes More information on the various currency ISO codes is available at: MOPET CZ a. s. Page 36 of 76 v1.7

37 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 Popis CustomerID String In Yes Fully qualified phone number of the beneficiary customer or nicknumber Číslo, které zadal pokladní do pokladního systému (9 místné telefonní číslo nebo Mobito číslo) MOPET CZ a. s. Page 37 of 76 v1.7

38 SourceID String In Yes Source Merchant s ID Identifikátor technického účtu, které Vám přidělí Mobito (lze zjistit v portálu obchodníka), typicky je přiděleno jedno číslo pro jednu integraci obchodníka (např. na jednu síť prodejen, případně pro jednu pobočkovou síť). SourceTxnID String In Yes Source Merchant s Internal Transaction ID Zde uveďte Vaše číslo transakce. Může být spjato s objednávkou SourceRefID String In No This can be used by the merchant to send a local terminal identifier or reference ID for reconciliation and reporting. It will merely be stored by the MOBITO system and is not interpreted in any manner. Zde uveďte číslo pokladny pro pozdější identifikaci místa prodeje a pro pokladní uzávěrku. Toto číslo může být například složeno následovně: TrxCode String In 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. Textem v tomto určujete, co je posláno klientovi po úspěšném zaplacení. InvoiceID String In Yes Source Merchant s Invoice ID Zde uveďte Vaše číslo transakce, objednávky nebo číslo dokladu (dodatečný identifikátor). Může být plněno stejně jako SourceTxnID. SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Zde uveďte autentizační klíč, který Vám přidělí Mopet po registraci technického účtu. Autentizační klíč je přidělen ke každému účtu se SourceID. MOPET CZ a. s. Page 38 of 76 v1.7

39 PaymentAmount String In String representation in ABC,YY Yes The payment amount for the transaction. Částka transakce včetně DPH, nemůže překročit limit pro jednu transakci (10000 Kč) Currency String In Valid ISO code (e.g. CZK) Yes The ISO code of the currency in which the amount is being sent by the source Plňte konstantu CZK Timestamp String In Yes Source s timestamp in the format - YYYYMMDDHH24MISS ProductDesc String In Upto 64 chars Yes Description of service/product purchased by consumer Uveďte Váš aktuální systémový čas / čas pokladny od kterého se má počítat expirace transakce. Tento údaj je zobrazen klientovi v detailu po přijetí platby. Doporučujeme uvádět prodejní místo - název pobočky, kde klient platí, např. Praha 9 Vysočany, Brno atd. Pozn: název obchodníka, u kterého se platí je klientovi zobrazen vždy, není nutné ho zde uvádět Validity String In Min: 30 secs Max: 60 days from initiation Yes The time till which the request is valid in the timestamp format YYYYMMDDHH24MISS Uveďte zde čas, kdy má platba vypršet (a nebude možné ji poté zaplatit). K Vašemu aktuálnímu systémovému času přičtěte např. 2 minuty a vypočtěte Validity timestamp. Doporučení pro čas expirace pro pokladny: 2 minuty, pro restaurace 5 minut, pro taxi služby 5 minut, pro platbu faktur 14 dní. UseNotifyURL 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 Nastavte na N -, notifikace bude řešena voláním ChekPaymentStatus. Pokud nastavíte na Y, je nutné nastavit MOPET CZ a. s. Page 39 of 76 v1.7

40 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 Notifikační URL. RESPONSE ON TRANSACTION RECEIPT SUCCESS MobitoTxnID String Out Yes Transaction ID generated by the MOBITO system Mopet vrátí jako odpověď ID vygenerované transakce v Mobitu. MobitoMessage String Out No Additional message from MOBITO RESPONSE ON TRANSACTION RECEIPT FAILURE FaultCode String Out Yes Fault error code Kód chyby viz níže FaultString String Out Yes Fault error message Text doplňující chybu odpovídá sloupci Description v následující kapitole Exceptions In cases where the transaction is not successful, the following error codes will be applicable: Code Description Vysvětlení Invalid or Missing CustomerID Takový zákazník nemá Mobito základní rozpoznání zda lze poslat na klienta účet k zaplacení Invalid or Missing SourceID Není vyplněnou číslo technického účtu SourceID not permitted to perform transaction Tento technický účet nemůže vkládat účty k zaplacení MOPET CZ a. s. Page 40 of 76 v1.7

41 22022 Invalid or Missing SourceAuthKey Chybí povinné pole SourceAuthKey Invalid or Missing SourceTxnID Chybí povinné pole SourceTxnId Missing InvoiceID Chybí pole InvoiceID nepoužívá se Invalid or Missing PaymentAmount Chybí povinné pole Částka, nebo je ve špatném formátu (nejčastější chyba - desetinná tečka) Invalid or Missing Currency Code Chybí kód měny (CZK) Invalid or Missing Timestamp Chybí povinné pole čas na serveru obchoníka Invalid or Missing ProductDesc Chybí pole ProductDesc nepoužívá se Invalid or Missing Validity Chybí povinné pole Validity, nebo je v minulosti, nebo je moc krátké Invalid or Missing UseNotifyURL flag Chybí povinné pole používat notifikační URL Remote system error <code> Obecná chyba v systému, nejčastěji špatná kombinace SourceID/SourceAuthKey Remote system is offline, not available Interní chyba systému Cannot locate home network for CustomerID Interní chyba systému uživateli nelze přiřadit operátora (přenositelnost čísel) Duplicate transaction detected Interní chyba systému, duplicitně zadaná transakce Request timed out Interní chyba systému požadavek vypršel Declined by customer Unknown error <additional message, if any> Neznámá chyba, nejčastěji pokud jsou z XML vypštěny nepovinné parametry úplně (prvek musí v požadavku být, ale může nabývat prázdných hodnot) MOPET CZ a. s. Page 41 of 76 v1.7

42 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 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 MOPET CZ a. s. Page 42 of 76 v1.7 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

43 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. MOPET CZ a. s. Page 43 of 76 v1.7

44 NewBalance String Out String representation in ABC.YY Yes Format - YYYYMMDDHH24MISS 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 MOPET CZ a. s. Page 44 of 76 v1.7

45 (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 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. MOPET CZ a. s. Page 45 of 76 v1.7

46 2.4.2 Parameters Parameter Name Type Direction Valid Value Mandatory Description Popis SourceID String In Yes Source Merchant s ID Identifikátor technického účtu, který Vám přidělí Mobito (lze zjistit v portálu obchodníka), typicky je přiděleno jedno číslo pro jednu integraci obchodníka (např. na jednu síť prodejen). SourceTxnID String In Yes Source Merchant s Original Internal Transaction ID Identifikace transakce identické SourceTxnID jako bylo použito při volání SubmiRequestForPayment. InvoiceID String In Yes Original Invoice ID Identifikace transakce identické InvoiceID jako bylo použito při volání SubmiRequestForPayment. SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO 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. Can be set to a case sensitive value of NOTAVAILABLE by PayNow Button merchants when they don t have the transaction id available (e.g. user closed the browser, etc). Zde uveďte autentizační klíč, který Vám přidělí Mopet po registraci technického účtu. Autentizační klíč je přidělen ke každému účtu se SourceID. Uveďte Váš aktuální systémový čas. Uveďte číslo transakce, které Mopet vrátil jako odpověď na volání SubmitRequestForPayment Pokud nemáte k dispozici MobitoTxnId (platební tlačítko ve stavu kdy se uživatel nevrátí) je možné zavolat s hodnotou NOTAVAILABLE a transakce se dohledá pomocí SourceTxnId (je nutné, aby SourceTxnId bylo v daném MOPET CZ a. s. Page 46 of 76 v1.7

47 dni jednoznačné, jinak funkce vrátí chybu) RESPONSE ON TRANSACTION QUERY SUCCESS TxnStatus String Out OK or FAILED or PENDING Yes Status of the transaction in the MOBITO system Odpověd aktuální stav transakce: - OK transakce zaplacena klientem. Lze vytisknout doklad a předat zboží / službu - FAILED trasnakce selhala (vypršela nebo byla odmítnuta) - PENDING transakce čeká na zaplacení Pozn: Expirované transakce jsou označovány hromadně systému pouze každou 1 minutu, Pokud chcete platbu ukončit ihned po expiraci, pak je možné expiraci provést na základě dosažení času uvedeného v atributu Validity. MobitoTxnID String Out Yes Original Transaction ID generated by the MOBITO system CompletionTS String Out No If the TxnStatus is OK or FAILED, then the timestamp of the completion of the transaction is reported here. Format - YYYYMMDDHH24MISS Odpověď číslo Mobito transakce Odpověď čas uzavření transakce v Mobito systému (pouze v případě OK a FAILED) NewBalance String Out String representation in ABC.YY No The balance of the merchant after the completion of the transaction Odpověď stav účtu po ukončení transakce SourceTxnID String Out Yes Source Merchant s Original Internal Odpověď Vaše číslo transakce MOPET CZ a. s. Page 47 of 76 v1.7

48 Transaction ID SourceRefID String Out No If sent by the merchant in the original request, this will be returned as is. Odpověď číslo pokladny RESPONSE ON TRANSACTION QUERY FAILURE 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 Popis chyby Invalid or Missing SourceID Není zadané SourceID, nebo tento účet není technický účet SourceID not permitted to perform transaction Nemáte právo provést tuto operaci (např:jiný typ technického účtu) Invalid or Missing SourceAuthKey Špatný Autorizační klíč Invalid or Missing SourceTxnID Nezadaný povinný prvek SourceTxnId Missing InvoiceID Nezadaný povinný prvek InvoiceID MOPET CZ a. s. Page 48 of 76 v1.7

49 24070 Invalid or Missing Timestamp Nezadaný povinný prvek Timestamp Missing MobitoTxnID Nezadaný povinný prvek MobitoTxnId Transaction not found in MOBITO database Buď transakce neexistuje, nebo se jedná transakci realizovanou jiným uživatelem, ne které nemá tento uživatel právo Remote system error <code> Nejčastěji nastává pokud chybí některé povinné prvky, nebo je špatná kombinace SourceAuthKey/SourceID Remote system is offline, not available Interní chyba Unknown error <additional message, if any> Interní chyba, nastává také pokud jsou zapomenuty některé prvky (i když jsou nepovinné musí být v XML s prázdným textem uvnitř) 2.5 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 MOPET CZ a. s. Page 49 of 76 v1.7

50 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 MOPET CZ a. s. Page 50 of 76 v1.7

51 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 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 MOPET CZ a. s. Page 51 of 76 v1.7

52 25085 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 Parameters Parameter Name Type Direction Valid Value Mandatory Description Popis SourceID String In Yes Source Merchant s ID Identifikátor technického účtu, který Vám přidělí Mobito (lze zjistit v portálu obchodníka), typicky je přiděleno jedno číslo pro jednu integraci obchodníka (např. na jednu síť prodejen). MOPET CZ a. s. Page 52 of 76 v1.7 Report bude obsahovat transakce realizované pouze tímto technickým

53 účtem. V případě, že transakce bude realizována např. manuálně uživatelem přes Mobito portál obchodníka, pak nebude obsažena v tomto reportu. SourceTxnID String In No Source Merchant s Internal Transaction ID. This is merely for the merchant to be able to track multiple report requests and has no bearing on the actual report. 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: F Fund outs I Incoming payments S Sales R - Refunds Transakční číslo obchodníka (slouží pro případné dohledávání v systémovém logu v případě problémů, nevztahuje se l žádné finanční transakci) Zde uveďte autentizační klíč, který Vám přidělí Mopet po registraci technického účtu. Autentizační klíč je přidělen ke každému účtu se SourceID. Uveďte Váš aktuální systémový čas. Uveďte datum a čas, od kterého chcete získat report transakcí Uveďte datum a čas, do kterého chcete získat report transakcí Uveďte typ reportu. Relevantní reporty jsou: - S report všech zaplacených plateb od klientů, které byly vygenerované tímto technickým účtem R report všech refundací realizovaných tímto technickým účtem MOPET CZ a. s. Page 53 of 76 v1.7

54 voláním metody IssueRefund RESPONSE ON TRANSACTION QUERY SUCCESS MobitoTxnID String Out Yes Original Transaction ID generated by the MOBITO system TotalAmount String Out String representation in ABC.YY Yes Total transaction amount applicable for the transactions included in the report. Celková suma transakcí obsažených v reportu (jedná se o sumu ve sloupci Amount) TotalFees String Out String representation in ABC.YY Yes Total fees applicable for the transactions included in the report. Celková suma poplatků obsažených v reportu (jedná se o sumu ve sloupci Fees) TotalCount String Out Yes Total number of transactions included in the report. 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. Celkový počet transakcí obsažených v reportu URL adresa, ze které je možné stáhnout detailní CSV report transakcí. Formát reportu jeuveden výše v kapitole Reporting Mobito plateb. RESPONSE ON TRANSACTION QUERY FAILURE FaultCode String Out Yes Fault error code FaultString String Out Yes Fault error message Exceptions In cases where the transaction is not successful, the following error codes will be applicable: MOPET CZ a. s. Page 54 of 76 v1.7

55 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 MOPET CZ a. s. Page 55 of 76 v1.7

56 SourceTxnID String In Yes Source Merchant s Original Internal Transaction ID InvoiceID String In Yes Original Invoice ID SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s current timestamp in the format - YYYYMMDDHH24MISS MobitoTxnID String In Yes The transaction ID sent back by the MOBITO system when the transaction was originally submitted. PaymentAmount String In String representation in ABC,YY 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. MOPET CZ a. s. Page 56 of 76 v1.7

57 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 Invalid or Missing Timestamp Missing MobitoTxnID Transaction not found in MOBITO database Remote system error <code> Remote system is offline, not available MOPET CZ a. s. Page 57 of 76 v1.7

58 27999 Unknown error <additional message, if any> 2.8 CancelRequestForPayment Method Purpose To cancel a previously submitted payment which is still pending 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 SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s current timestamp in the format - YYYYMMDDHH24MISS MobitoTxnID String In Yes The transaction ID sent back by the MOBITO system when the transaction was originally submitted. CancelReason String In No Short description indicating reason for cancelation. Not stored or used for reporting at this time. RESPONSE ON TRANSACTION CANCEL SUCCESS MobitoTxnID String Out Yes The original MOBITO transaction id for reference. MOPET CZ a. s. Page 58 of 76 v1.7

59 MobitoMessage String Out No Additional message from MOBITO RESPONSE ON TRANSACTION CANCEL 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 Invalid or Missing Timestamp Missing MobitoTxnID Transaction not found in MOBITO database Remote system error <code> Remote system is offline, not available Transaction cannot be canceled Unknown error <additional message, if any> MOPET CZ a. s. Page 59 of 76 v1.7

60 3 MobitoCode Integration 3.1 Basics The MobitoCode concept is essentially a flexible way to generate request for payments based on user input. This type of integration is intended for impulse buying scenarios and requires the participating merchants to implement a few client side and a few server side SOAP methods so that the MOBITO system can retrieve or verify the MobitoCode information prior to presenting any choices or options to the customer as well as for product reservations (timelimited) prior to initiating the request for payment on behalf of the participating merchant. Client-side SOAP methods to be implemented by the merchants at this time: ConfigurePaymentNotification (refer to Section 2.3 for full details) ConfigureMobitoCodeListener Server-side SOAP methods to be implemented by the merchants at this time: GetMobitoCodeInfo PreValidateMobitoCodeOrder All MobitoCodes are issued by Mopet directly to a participating merchant based on a specific business and commercial criteria. Each MobitoCode is unique and non-transferrable from one merchant to another. 3.2 ConfigureMobitoCodeListener Purpose To configure a listener URL for receiving MobitoCode related requests from the MOBITO system. This URL can also be configured manually via the Merchant Self Care portal. MOPET CZ a. s. Page 60 of 76 v1.7

61 3.2.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 configuration requests (if applicable) and has no bearing on the actual URL configuration. SourceAuthKey String In Yes Authorization key assigned to the merchant by MOBITO Timestamp String In Yes Source s timestamp in the format - YYYYMMDDHH24MISS ListenerURL String In 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 MOPET CZ a. s. Page 61 of 76 v1.7

62 3.2.3 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 62 of 76 v1.7

63 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. MOPET CZ a. s. Page 63 of 76 v1.7

64 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 ChoiceDetail Format For MobitoCode In cases where the ChoiceCount is non zero, the merchant must return a multipart string in the following format with the pipe as the record separator; (a) If ParamFormat is C, Choice1 Choice2 Choice9 (b) If ParamFormat is CN, Choice1,Number1 Choice2,Number2 Choice9,Number9 (c) If ParamFormat is CF, Choice1,Text1 Choice2,Text2 Choice9,Text9 MOPET CZ a. s. Page 64 of 76 v1.7

65 (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 65 of 76 v1.7

66 3.3.4 Exceptions 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 ) MOPET CZ a. s. Page 66 of 76 v1.7

67 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 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. MOPET CZ a. s. Page 67 of 76 v1.7

68 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 68 of 76 v1.7

69 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. MOPET CZ a. s. Page 69 of 76 v1.7