MOPET CZ a.s.
Připojení obchodníka do systému Mobito Příručka pro integraci
MOPET CZ a. s.
Page 1 of 76
v1.7
MOPET CZ a. s.
Page 2 of 76
v1.7
Obsah 1.
Manažerské shrnutí............................................................................................................. 5
1.1.
Představení společnosti Mopet a systému Mobito ............................................................ 5
1.2.
Možnosti připojení .............................................................................................................. 5
1.3.
Náročnost implementace:................................................................................................... 5
1.4.
K čemu slouží testovací prostředí: ...................................................................................... 6
1.5.
Testovací fáze: ..................................................................................................................... 6
1.6.
Poskytovaná podpora: ........................................................................................................ 6
2.
Slovníček pojmů .................................................................................................................. 7
2.1.
Používané termíny .............................................................................................................. 7
2.2.
Používané zkratky................................................................................................................ 7
3.
Platební tlačítko (nová verze).............................................................................................. 8
3.1.
Obecné předpoklady scénářů: ............................................................................................ 8
3.2.
Mobito Platební Tlačítko (Bez Integrace) ............................................................................ 8
3.3.
Mobito Platební Tlačítko (Integrace) .................................................................................. 9
3.4.
Požadavky na zobrazení platebního tlačítka ..................................................................... 13
4.
Testování platebního tlačítka ............................................................................................ 14
5.
Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka ..... 16
5.1.
Základní prvky Mobita na stránkách obchodníka ............................................................. 16
5.2.
Pravidla pro používání základních prvků ........................................................................... 16
6.
Ověření odpovědí ze systému ........................................................................................... 19
6.1.
Bezpečnostní kód .............................................................................................................. 19
6.2.
Algoritmus ......................................................................................................................... 19
7.
Integrace plateb spuštěných klientem (Mobito kód)........................................................ 20
7.1.
Testování Mobito kódu ..................................................................................................... 22
8.
Integrace WebServices požadavky na platbu ................................................................... 23
8.1.
Testování Web Services .................................................................................................... 24
9.
Integrace Notifikace .......................................................................................................... 26
10.
Integrace WebServices - Zjištění stavu transakcí ............................................................. 27
10.1. Stavy transakcí .................................................................................................................. 27 11.
Ověření odpovědí ze systému ........................................................................................... 28
11.1. Bezpečnostní kód .............................................................................................................. 28 11.2. Algoritmus ......................................................................................................................... 28 MOPET CZ a. s.
Page 3 of 76
v1.7
12.
FAQs .................................................................................................................................. 29
Příloha A Kód platebního tlačítka ................................................................................................ 30 Příloha B Technický popis rozhraní (EN)...................................................................................... 33 Cíl dokumentu Cílem tohoto dokumentu je seznámit obchodníky s možnostmi zapojení do systému Mobito a zároveň je provést procesem připojování jednotlivých kanálů. Součástí tohoto dokumentu jsou všechny informace nutné k implementaci, integraci a otestování vybrané platební metody společnosti Mopet CZ.
MOPET CZ a. s.
Page 4 of 76
v1.7
1.
Manažerské shrnutí
1.1. Představení společnosti Mopet a systému Mobito Společnost MOPET CZ a.s. je akciová společnost, jejímiž spoluvlastníky jsou čeští mobilní operátoři O2 Telefónica, T-Mobile, Vodafone, a bankovní domy Česká spořitelna, GE Money Bank, Raiffeisenbank a UniCredit Bank. Základním cílem společnosti je vybudovat transakční centrum pro mobilní platby a uvést na český trh službu Mobito, umožňující platit a posílat peníze v reálném čase přes mobilní telefon tam, kde nyní zákazníci používají převážně hotovost, bez ohledu na to, jakou mají banku či mobilního operátora. Mobitem půjde platit za zboží a služby, hradit složenky a faktury, posílat si mezi sebou peníze či zaplatit mobilním telefonem nákup na internetu nebo v mobilu. Mobito je nový platební standard na českém trhu, který umožňuje zákazníkům platit prostřednictvím mobilních telefonů za zboží a služby. Hlavním prvkem Mobita je tzv. „request for payment – žádost k zaplacení“, kterou dostává zákazník do svého mobilu a potvrzuje ji PINem. Mobito je zdarma, funguje ve všech mobilních telefonech a pro klienty všech českých bank a mobilních operátorů. Mobito má ambici stát se synonymem pro peníze v mobilu a inovativní univerzální platební metodu, která bude mít své pevné místo vedle hotovosti a platebních karet. Peníze v mobilu, jinak než je doposud znáte, to je Mobito.
1.2. Možnosti připojení Obchodník má 3 možnosti připojení k systému Mobito. Jsou to: 1. Platební tlačítko 2. Integrace pomocí webových služeb pro platbu 3. Integrace Mobito kód
Každá z možností bude detailněji probrána v následujících kapitolách.
1.3. Náročnost implementace: Platební tlačítko: Společnost MOPET CZ se snaží maximálně zjednodušit přístup ke svým platebním metodám pro maximálně širokou skupinu obchodníků. Na základě této dlouhodobé vize jsme se pokusili navrhnout připojení na platební bránu v maximálně zjednodušené podobě. Předpokládána náročnost implementace základní funkčnosti by měla být do 1 MD (práce člověka za jeden osmihodinový den).
Mobito kód a připojení na rozhraní: Tato funkcionalita je o něco složitější, protože vyžaduje znalosti a zkušenost s implementací webových služeb, větší znalost vnitřních procesů obchodníka a náročnější způsob připojení na MOPET CZ a. s.
Page 5 of 76
v1.7
testovací a produkční prostředí. Připojení přes tyto metody řešíme individuálně mimo standardní procesy připojení obchodníka. Tato integrace vyžaduje vlastní rozhraní na straně obchodníka, pomocí kterého je náš systém informován o nabízeném zboží/službách. Tímto umožňuje vytvořit nové obchodní kanály například z mobilního telefonu, dále integraci do stávající infrastruktury pokladních systémů a zapojení plateb do obchodních procesů. Očekávaná doba implementace by se měla pohybovat okolo 3MD připojení na rozhraní, a 5MD připojení pro Mobito kód. Poté je potřeba počítat s cca 1MD na testy. Do odhadu nejsou započítány pracnosti nutné na změnu procesů ve Vašem systému případně infrastruktury.
1.4. K čemu slouží testovací prostředí: Testovací prostředí poskytuje společnost MOPET CZ pro podporu integrace obchodníka na službu Mobito. Na tomto prostředí si obchodník ověří, že jeho systém funguje dle specifikace a MOPET CZ mu na základě tohoto testu umožní přístup na produkční prostředí. Tímto testem se obchodník nezříká zodpovědnosti za kvalitu a fungování svojí části systému v živém prostředí.
1.5. Testovací fáze: Společnost MOPET CZ standardně nabízí třítýdenní testovací okno. První dva týdny slouží primárně pro potřeby připojovaného obchodníka. V rámci tohoto období si obchodník může otestovat svojí část systému dle svojí potřeby. Poslední týden slouží pro provedení testů popsaných v dokumentu Popis Připojení obchodníka v příslušných kapitolách u každé platební metody. Na základě úspěšného provedení těchto testů je zahájen proces „zprovoznění obchodníka pro produkci“.
1.6. Poskytovaná podpora: Společnost Mopet poskytuje podporu pro integraci obchodníka na mailové adrese:
[email protected] V případě jakýchkoliv problémů se můžete obrátit na tento mail.
MOPET CZ a. s.
Page 6 of 76
v1.7
2.
Slovníček pojmů
2.1. Používané termíny Český název Číslo obchodníka Nebo Číslo uživatele (osobní): Autentizační klíč
Parametr SourceID
Popis Číslo obchodního místa – Technického účtu, který je přidělen a vkládá se jako identifikace obchodníka
SourceAuthKey
Tajný podpisový klíč
presharedSecret
Technický účet
Virtual Employee
Mobito číslo Číslo transakce Mobito Číslo transakce obchodníka
ConsumerID MobitoTxnID
Slouží jako ověření, že můžete nakládat s daným účtem – pro webové služby slouží v podstatě jako heslo pro požadavky a mělo by s ním být tak nakládáno (neprozrazovat atp.) pro Platební tlačítko se jedná pouze o verifikaci požadavku Tajný klíč, který se vkládá do podpisového řetězce, aby zabezpečil validitu odpovědi Mobita obchodníkovi Účet obchodníka, který se nemůže přihlásit do portálu nebo web terminálu, ale slouží pro integrační účely, přes tyto účty se připojuje jak platební tlačítko, tak API integrace (viz SourceID) Číslo uživatele, od kterého požadujete, aby zaplatil Číslo transakce přidělené Mobitem – jednoznačný identifikátor
Číslo faktury, číslo objednávky Referenční číslo
InvoiceID
Časové razítko
Timestamp
Doba trvání platby
Validity
SourceTxnId
SourceRefID
Číslo transakce u obchodníka – většinou je identický s číslem objednávky - InvoiceID, může být ale interní označení, které slouží jen za účelem logování - například sekvence Číslo, které slouží u obchodníka k identifikaci nákupu, slouží jako např. variabilní symbol pro párování plateb Referenční číslo (například číslo terminálu nebo pokladny) není interpretováno naším systémem, slouží pouze pro reportovací účely u obchodníka Slouží k určení aktuálního času, aby se případně přišlo na chyby způsobené špatným natavením času u obchodníka, nebo rozdílné časové zóny – podle timestamp se poté určuje validity Doba, po kterou má platnost požadavek na platbu, může být min 30s ale také 30 dní. Do této doby má uživatel možnost platbu potvrdit nebo zrušit, poté již nemá možnost zaplatit a platba je považována za FAILED
2.2. Používané zkratky Zkratka WSDL XML RFP
MOPET CZ a. s.
Popis Web Service Definition File – soubor popisující rozhraní webových služeb Extensible Markup Language Request for payment - Požadavek na platbu - klientovi je zaslána informace o platbě, kterou může potvrdit, zrušit a v některých případech odložit
Page 7 of 76
v1.7
3.
Platební tlačítko (nová verze)
3.1. Obecné předpoklady scénářů:
Klient – Fyzická osoba zaregistrována a aktivována do služby Mobito. Klient má na účtu dostatek prostředků na zaplacení poptávané služby / vybraného zboží (klient má možnost zaplatit zboží i bez předchozí dotace účtu – klient s online připojeným platebním instrumentem) Obchodník – Fyzická nebo právnická osoba, se kterou je uzavřena smlouva s firmou MOPET CZ. Obchodník je zaregistrován a aktivován do služby Mobito
3.2. Mobito Platební Tlačítko (Bez Integrace) Popis Platební tlačítko bez integrace slouží například pro nadace / občanská sdružení (OS), která chtějí využít možnosti přes Mobito zaslat dar, pokud chcete jakkoliv automatizovaně reagovat na zaslanou platbu pokračujte prosím další kapitolou. Uživatelská zkušenost: -
Klient – chce vložit dar přes web nebo mobilní web nadace Obchodník / OS - chce na své stránky zobrazit tlačítko „darujte“ a není možné jakékoliv složité programování
Scénář platby: -
Klient (web OS) – stiskne tlačítko „darovat“, Web OS – přesměrování klienta na platební bránu Mobito a předání údajů o platbě (částka, popis) Klient (platební brána Mobito) – zadání Mobito ID (tel. čísla / ID) a potvrzení platby. Mobito systém – zaslání požadavku na platbu na telefonní číslo klienta registrované u Mobito účtu (nativní notifikace, USSD notifikace) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a zaslání potvrzujícího emailu do OS. Přesměrování na web OS Klient (web obchodníka) – klientovi je zobrazena notifikace o úspěšném zaplacení na mobilu / je možné zobrazit stránku s poděkováním
MOPET CZ a. s.
Page 8 of 76
v1.7
Jak to udělat / Nastavení pro platbu: 1) Přihlášení se do portálu pro obchodníky – pomocí administrátorského účtu, který obdržíte při podpisu smlouvy 2) Nastavení obchodního místa – vytvoření Virtuálního zaměstnance a) Vytvořte pomocí návodu základní strukturu – jednoho Virtuálního zaměstnance přímo pod svým účtem b) WWW adresu, kterou chcete, aby se zobrazila v Mobito bráně vložte do parametru Název Virtuálního zaměstnance c) Odpověď na e-mail – nastavte e-mail, na který Vám budou chodit informace o platbách 3) Nastavení adres pro přesměrování na bránu a) Jako cílovou adresu pro ukončení platby nastavte odkaz na stránku na vašem serveru, kde uživateli poděkujete za dar. b) Stránku pro případ neúspěch ponechte prázdnou, v případě neúspěchu se uživateli zobrazí automatická informace naší brány c) Adresy musí být ve tvaru https://server:port/soubor 4) Nastavte si v Portálu pro obchodníky e-mail notifikaci o provedené platbě, abyste měli přehled (příklady notifikačních emailů viz Příloha B – emailové notifikace o stavu transakce) 5) SourceAuthKey (Autentizační klíč) - obrazí se na výpisu detailů Virtuálního zaměstnance a) Tento klíč, stejně jako vaše Identifikační číslo (SourceID) vložte do předpřipraveného kódu pro tlačítko 6) Na vaše webové stránky vložte HTML kód (viz příloha B) s jednoduchým platebním tlačítkem s přednastavenou částkou (případně několik tlačítek s různými částkami nebo tlačítko s možností uživatelské editace částky). Do pole Timestamp vložte aktuální datum. 7) Celou implementaci je možné provést bez programování.
3.3. Mobito Platební Tlačítko (Integrace) Popis Platební tlačítko umožňuje začlenit Mobito jako platební metodu např. do e-shopu obchodníka sloužící k okamžitému zaplacení zboží. Uživatelská zkušenost: MOPET CZ a. s.
Page 9 of 76
v1.7
-
Klient – Nákup mobilem vzdáleně přes web nebo mobilní web obchodníka (registrovaný i neregistrovaný klient webu) Obchodník (e-shop) - Mobito jako platební metoda, integrace Mobito platebního tlačítko na webu / mobilním webu obchodníka.
Scénář platby: 1) Klient (web obchodníka) – výběr zboží nebo služby na webu obchodníka, výběr platební metody – Mobito a potvrzení platby. 2) Web obchodníka – přesměrování klienta na platební bránu Mobito a předání údajů o platbě (částka, popis zboží / služby) 3) Klient (platební brána Mobito) – zadání Mobito ID (tel. čísla / ID) a potvrzení platby. 4) Mobito systém – zaslání požadavku na platbu na tel. číslo klienta registrované u Mobito účtu (nativní notifikace, USSD notifikace) 5) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem 6) Mobito systém – ověření transakce a notifikuje o úspěšném zaplacení Klient: zobrazení informace o stavu dokončení transakce a následné přesměrování na web Obchodníka (Success/failed URL součástí, kterého je i ověřený podpis – viz kapitola 6. Ověření odpovědí ze systému) Obchodník: Zobrazení stavu dokončené transakce v Mobito portálu Obchodníka Na tuto adresu poté přijde z našeho serveru GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole „Ověření klienta“ Mobito systém zašle z našeho serveru na vydefinovanou URL adresu obchodníka GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole 6. Ověření odpovědí ze systému1 Mobito systém po zaplacení odešle na vydefinovaný email správu obsahující informace o dokončených transakcích (viz Příloha B – emailové notifikace o stavu transakce) - součástí předávané informace je i ověřený podpis – viz kapitola 7. Ověření API integrací je možné zavolat ChecktPaymentStatus, kde je uveden status platby (viz kapitola 8. Integrace WebServices požadavky na platbu) 7) Klient (web obchodníka) – klientovi je zobrazena notifikace o úspěšném zaplacení zboží/služby, poděkování případně další instrukce. a) Obchodník - ověří platnost odpovědi brány pomocí ověření podpisu (viz kapitola 6. Ověření odpovědí ze systému)
1
Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 1 minuta). Může tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 0:59 minut). MOPET CZ a. s.
Page 10 of 76
v1.7
Alternativy scénáře A) Předvyplnění Mobito ID - Web obchodníka předá platební bráně Mobito ID zákazníka (bude předvyplněno) – krok 2 B) Transakce nedokončena / neautorizována - V případě neúspěšného potvrzení transakce (klient neautorizoval transakci, vypršel limit) je klient přesměrován na web obchodníka (definovaná failure – chybová - URL), obchodníkovi je tentostav sdělen na vydefinované URL/email C) Transakce dokončena, ale klient uzavřel Mobito platební bránu před přesměrováním na web obchodníka a. Obchodník může zjistit stav transakce v manuálně portálu pro obchodníky b. v případě nastavení technického účtu (virtual employee), aby po zaplacení vyvolal URL adresu obchodníka na, kterou předá informace o dokončených transakcích (zaplaceno/selhalo s důvodem selhání) bude tato informace předána i v případě, kdy klient uzavře webovou bránu před přesměrováním na web obchodníka c. v případě nastavení technického účtu (virtual employee), aby po zaplacení odeslal na vydefinovaný email správu obsahující informace o dokončených transakcích, bude tento email zaslán i v případě, kdy klient uzavře webovou bránu před přesměrováním na web obchodníka d. V případě API integrace je možné zavolat ChecktPaymentStatus, kde je uveden status platby i v případě, kdy klient uzavře webovou bránu před přesměrováním na web obchodníka D) Notifikace o dokončené transakce není možné na vydefinované URL doručit Mobito systém se pokusí na vydefinované URL informaci o dokončené transakci předat celkem 3 krát (volání po 3 sekundách). V případě že i třetí volání selže, pošle Mobito systém informace o dokončené transakci automaticky na emailovou adresu vydefinovanou jako kontaktní email daného technického účtu (virtual emploee) E) Notifikace o dokončené transakce není možné na vydefinované URL doručit a technický účet nemá vydefinovanou kontaktní emailovou adresu V takovém případě pošle Mobito systém informace o dokončené transakci automaticky na emailovou adresu vydefinovanou jako kontaktní email Obchodníka.
Jak to udělat / Nastavení pro platbu MOPET CZ a. s.
Page 11 of 76
v1.7
1) Přihlášení se do portálu pro obchodníky – pomocí administrátorského účtu, který obdržíte při podpisu smlouvy 2) Nastavení obchodního místa - vytvoření Virtuálního zaměstnance a) Vytvořte pomocí návodu základní strukturu obchodu – 1 Virtuálního zaměstnance přímo pod svým účtem obchodníka nebo pod některou Vaší pobočkou b) WWW adresu obchodu, kterou chcete, aby se zobrazila na Mobito Bráně vložte do parametru Název Virtuálního zaměstnance c) Při notifikaci o dokončené transakce vyvoláním URL nastavení URL notifikace (v tomto případě vyplňte pro potřeby alternativního scénáře u daného technického účtu i pole s pro kontaktní email) d) Při notifikaci o dokončené transakce zasláním emailu nastavte emilovou adresu, kam budou notifikace zasílané 3) Nastavení adres pro přesměrování na bránu a) U Virtuálního zaměstnance nastavte adresy, na které bude zákazník přesměrován v případě úspěchu případně neúspěchu transakce b) Tyto adresy musí být ve tvaru https://server:port/soubor 4) SourceAuthKey, SecurityToken – Zobrazí se na výpisu detailů Virtuálního zaměstnance a) SourceAuthKey se použije při odesílání požadavku na bránu a slouží namísto hesla. Generuje systém po vytvoření Virtuálního Employee b) SecurityToken slouží pro zajištění bezpečnosti návratu, tento kód se poté použije pro podpis a na Vaší straně pro ověření podpisu zpráv o zaplacení. Technické požadavky integrace: -
Odeslání požadavku na platbu - integrace platebního tlačítka Mobito na web obchodníka (HTTP POST protokol) Přijetí výsledku transakce – schopnost přijetí a zobrazení výsledku transakce na definovaném URL obchodníka (nastavení success / failure URL na Mobito portálu obchodníka), pokud obchodník vyžaduje ověření, schopnost vypočítat kontrolní součet (viz kapitola ověření)
Schéma rozhraní
MOPET CZ a. s.
Page 12 of 76
v1.7
sd PaymentButton MerchantSystem
MobitoPaymentGateway
Handset
POST/GET Redirect()
Enter MobitoID() SendRFP()
PIN()
Redirect()
3.4. Požadavky na zobrazení platebního tlačítka Ve chvíli implementace požádejte na e-mail
[email protected] o zaslání grafických podkladů. V rámci těchto grafických podkladů jsou:
Ikony, které je možné uvést v seznamu platebních metod, případně v patičce stránek Ikony, které požadujeme uvést v případě výběru platební metody Pozadí pro platební tlačítko (pokud takové využíváte)
MOPET CZ a. s.
Page 13 of 76
v1.7
4.
Testování platebního tlačítka
Pro ověření funkčnosti platebního tlačítka nejprve nastavte tlačítko dle návodu v kapitolách výše. Pro testování prosím kontaktujte alespoň týden předem - email
[email protected] s předmětem „platební tlačítko - test“, do kterého uveďte následující informace:
1) Kontaktní osobu 2) Předpokládaný čas možných testů 3) Název obchodníka + www stránky V odpovědi obdržíte nejen datum a čas možného testování, ale také číslo klienta se kterým je možné testovat (který Vám transakci potvrdí, zruší, či nechá vypršet)
Testovací transakce – úspěch 1) Kontaktujte
[email protected] a potvrďte si, připravenost pro testy 2) Vytvořit zkušební transakci – Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 3) Stisknutí tlačítka – Stisk tlačítka vyvolá přesměrování na platební bránu Mobito a) Dojde-li k přesměrování - pokračujte bodem 3) b) Pokud k přesměrování nedojde i) Zkontrolujte, zda se Vám zobrazilo tlačítko správně (nikoliv jako kód
MOPET CZ a. s.
Page 14 of 76
v1.7
Testovací transakce – vypršení časového limitu 10) Kontaktujte
[email protected] a potvrďte si, že chcete testovat vypršení časového limitu 11) Vytvořit zkušební transakci – Na vašem systému vytvořte transakci tak, aby se Vám vygenerovalo platební tlačítko 12) Stisknutí tlačítka – Stisk tlačítka vyvolá přesměrování na platební bránu Mobito 13) Zadejte do zobrazené brány číslo pro vypršení (obdržíte od společnosti MOPET CZ) 14) Vyčkejte do vypršení časového limitu a) Zkontrolujte přijaté parametry
MOPET CZ a. s.
Page 15 of 76
v1.7
5.
Pravidla pro integraci platební metody Mobito na webových stránkách obchodníka
5.1. Základní prvky Mobita na stránkách obchodníka 1. Logo Mobita 2. Popisný text o Mobitu
5.2. Pravidla pro používání základních prvků 1. Logo Mobita Formát loga Použití loga Mobita se vždy řídí seznamem povolených velikostí, které jsou k dispozici v grafickém balíku. Grafický balík log je zasílaný spolu s integračním manuálem pro obchodníka.
V případě, že z jakéhokoliv důvodu nemůžete použit ani jednu variantu, kontaktujte technickou podporu na e-mailové adrese:
[email protected]
Ukázka loga Mobita
Logo je dostupné v následujících velikostech: 86 x 26 px 112 x 34 px 132 x 40 px 154 x 46 px 176 x 54 px Pravidla pro použití loga POZOR! Logo Mobita nemůže být nikdy použito jako tlačítko, které spouští akci. Při přesměrování klienta na platební bránu Mobito se očekává použití standardního neutrálního tlačítka, které je stejné pro všechny ostatní platební metody a vyzívá klienta k akci. Tato tlačítka mají zpravidla název „Zaplatit, Zaplatit přes platební bránu, Pokračovat“ a podobně. Toto tlačítko doporučujeme doplnit o průvodní text (viz dále), který informuje zákazníka o tom, co bude následovat po kliknutí. Po kliknutí je zákazník přesměrován na platební bránu Mobita, kde uskuteční platbu.
MOPET CZ a. s.
Při výběru Mobita, jako platební metody pro platbu, může být použité logo Mobita, ale vždy jen v doprovodu radio buttonu, který označuje výběr platební metody. Page 16 of 76
v1.7
V takovém případě logo nemůže být klikatelné a odkazovat například na stránky Mobita, ale musí působit jako označení platební metody.
Výběr Mobita jako platební metody nemusí obsahovat logo a to v případě, že seznam ostatních platebních metod neobsahuje jejich loga. V takovém případě musí být platební metoda označena textově názvem služby s velkým začátečním písmenem „Mobito“.
V případě, že je platební metoda doplněna o krátký popisný text, doporučujeme následující spojení: Platba Mobitem Zaplať Mobitem Zaplať mobilem přes Mobito
Umístění loga Logo Mobita musí být uvedeno jako identifikátor platební metody u ostatních platebních metod, které může zákazník použít na stránkách obchodníka. Zpravidla jsou loga umístěna v zápatí stránek, které zákazník vidí na úvodní stránce webshopu a při výběru platební metody v košíku objednávky.
V případě, že má obchodník k dispozici samostatnou stránku, která uvádí seznam všech platebních metod, musí být Mobito identifikované na této stránce logem a krátkým popisným textem.
Popisný text o Mobitu Vzhledem k tomu, že Mobito je nová platební metoda na trhu, je vhodné zákazníky obeznámit stručným popisem o této metodě. Připravili jsme pro vás 3 různé varianty popisného textu, který MOPET CZ a. s.
Page 17 of 76
v1.7
můžete využít na svých stránkách. Krátké verze popisných textů doporučujeme použít na místech, kde chcete jen stručně informovat zákazníka o Mobitu. Delší formát je vhodný pro popis platební metody na stránkách, které věnujete popisu všech platebních metod. Formáty textu: S – krátký formát M – středný formát L – delší formát
S – krátký formát o Mobito – peníze v mobilu o Mobito jsou peníze v mobilu – nová služba umožňující platit mobilem.
M – střední formát Mobito jsou peníze v mobilu – nová služba umožňující platit mobilem. Mobito stačí jednoduše připojit k běžnému účtu nebo k platební kartě. S Mobitem lze bezpečně platit za zboží a služby, posílat peníze z jednoho mobilu na druhý nebo dobíjet kredit telefonu. Více informací na www.mobitoplatito.cz
L – delší formát Mobito jsou peníze v mobilu – nová služba umožňující platit mobilem. Mobito stačí jednoduše připojit k běžnému účtu nebo k platební kartě. S Mobitem lze bezpečně platit za zboží a služby, posílat peníze z jednoho mobilu na druhý nebo dobíjet kredit telefonu. Placení probíhá okamžitě. Mobitem může zaplatit každý – nehledě na to, jaký typ telefonu vlastní a jakou banku či mobilního operátora využívá. Mobito je lokální řešení pro platby mobilem. Stojí za ním společnost MOPET CZ společně se čtyřmi bankami (Česká spořitelna, GE Money Bank, Raiffeisenbank, UniCredit Bank) a všemi mobilními operátory (Telefónica O2, T-Mobile, Vodafone). Registrace a více informací na www.mobitoplatito.cz
V případě dalších dotazů prosím kontaktujte technickou podporu na e-mailové adrese
[email protected]. Upozornění: Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 1 minuta). Může tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 0:59 minut).
MOPET CZ a. s.
Page 18 of 76
v1.7
6.
Ověření odpovědí ze systému
Metody upozornění na platbu (Notification a přesměrování z platební brány) obsahují kromě údajů o transakci i podpis. Takto může obchodník jednoduše zjistit, že není daná informace o transakci podvržená a není nutné další zjišťování výsledku transakce.
6.1. Bezpečnostní kód V portálu pro obchodníky je vždy v sekci virtual employee vygenerován bezpečnostní kód. Jedná se o 20 znaků dlouhý text, který se poté vkládá do algoritmu jako klíč pro zabezpečení. Je velmi důležité, aby tento kód nebyl nikdy znám nikomu jinému nežli důvěryhodným osobám obchodníka a aby nebylo možné jej jednoduše zjistit například zobrazením zdrojového kódu na webu obchodníka apod. Bezpečnostní kód je v následujícím algoritmu uveden pod názvem „presharedSecret“.
6.2. Algoritmus Do zprávy se přidává jako podpis tzv. messageDigest. Ten je vytvořen jako SHA256 hash z řetězce parametrů na konci doplněných o bezpečnostní kód – presharedSecret. Server vypočte tento podpis a zašle jej spolu s notifikací, nebo přesměrováním. Ověření na straně obchodníka probíhá tak, že obchodník stejným způsobem vypočte podpis ze zaslaných parametrů a bezpečnostního kódu a výsledný řetězec porovná s přijatým podpisem. Jako výstup se používá „hexadecimální“ způsob zápisu s malými písmeny a-f. V programovacím jazyce může vypadat zápis například takto:
messageDigest = makeSHA256Hash(sourceId + sourceTxnId + invoiceId + sourceAuthKey + paymentAmount + sourceTimestamp + presharedSecret+ TxnStatus)
Zápis se může lišit dle programovacího jazyka, znak „+“ v tomto zápise značí spojení dvou řetězců za sebe. Například v jazyce PHP se použije znak „.“(tečka). Jednotlivé parametry jsou popsány v příloze B. Mezi hodnotami nejsou vkládány žádné mezery ani jiné prázdné znaky a hodnoty jsou včetně všech znaků tak jak byly zadány (je tedy nutné zahrnout i například počáteční nuly u některých parametrů) Výsledek je v hexadecimálním formátu se znaky a-f označenými malými písmeny. Pro vyzkoušení je možné využít online službu pro vypočítání hash např. na: http://hash.online-convert.com/sha256-generator (výsledek ve verzi hex)
MOPET CZ a. s.
Page 19 of 76
v1.7
7.
Integrace plateb spuštěných klientem (Mobito kód)
Popis Pokud chcete využít mobilní telefon klientů jako nákupní prostředí, je možné integrovat je pomocí rozhraní Mobito kódu. Uživatelská zkušenost: -
Klient – Nákup mobilem například na základě plakátu, reklamy v TV, čísla faktury apod. Obchodník - Mobito jako platební metoda podpořená jinými informačními kanály (jakýkoliv informační kanál, ze kterého si klient může kód zapamatovat)
Scénář platby: 1) Klient (mobilní telefon) – přihlásí se do Mobito aplikace a zadá kód. 2) Server obchodníka – je kontaktován pro zjištění, zda je kód ještě platný a zda obchodník požaduje po klientovi upřesnění objednávky a) Obchodník si může vyžádat (volitelně) vyplnit od klienta: i) Výběr z 1-9 voleb (volby vztahující se k danému kódu) ii) Číslo – např. počet, variabilní symbol, číselný identifikátor apod. iii) Text – upřesňující údaje k objednávce (např. SPZ, PSČ, jméno apod.) – max. 120 znaků bez diakritiky 3) Klient (mobilní telefon) – zadání požadovaných zpřesňujících údajů 4) Server obchodníka – Obdrží zpřesňující informace, a zašle celkovou částku k zaplacení a) v případě že je to možné v tuto chvíli je nejvhodnější chvíle, kdy se provede rezervaci zboží 5) Mobito systém – zaslání požadavku na platbu na tel. číslo klienta (nativní notifikace, USSD notifikace) 6) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a notifikace webu obchodníkovi.
MOPET CZ a. s.
Page 20 of 76
v1.7
sd MobitoCo... Handset
mBroker
MerchantSystem
GetToMobitoCodeInput() SendCode()
LookupCode() GetMobitoCodeInfo()
GetMobitoCodeInfo Response()
DisplayChoices()
Choose(Choice, Amount)
validate choice and amount() PreValidateMobitoCodeOrder(choice, amount, text)
Reserve() PreValidateMobitoCodeOrder response()
GenerateRequestForPayment() RequestForPayment()
Authorisation() RequestForPaymentConfirmation()
Confirmation()
PutReservedAsSold()
Jak to udělat / Nastavení pro platbu 1) Přihlášení se do portálu pro obchodníky – pomocí administrátorského účtu, který obdržíte při podpisu smlouvy 2) Kontaktování Mopet Backoffice a) Nastavení Branche a virtuálního zaměstnance typu Mobito code b) Získání technických popisů služeb (wsdl) podle kterých vyvinete na Váš server služby potřebné pro integraci 3) Zobrazení vytvořeného virtuálního zaměstnance 4) SourceAuthKey, Zobrazí se na výpisu detailů Virtuálního zaměstnance a) SourceAuthKey se použije při odesílání požadavku na bránu a slouží namísto hesla. Generuje systém po vytvoření Virtuálního Employee MOPET CZ a. s.
Page 21 of 76
v1.7
5) Nastavení URL pro kontaktování a) U virt. zaměstnance nastavte adresu, na kterou Vás bude kontaktovat náš systém v případě kódu b) Případně zavolejte web service ConfigureMobitoCodeListener (za pomoci nastaveného sourceAuthKey – zobrazeno u virt. zaměstnance a SourceID – ID Virt. Zaměstnance. 6) Ve smlouvě vám bude přidělen kód. Podle tohoto kódu systém rozpozná, že se jedná o Vaše kódy, proto je nutné, aby všechny Vaše kódy začínali na tento kód a) Příklad – přiřazený kód je 123, zákazník je přesměrován k vám s kódy i) 123 ii) 12300001 iii) 123auto apod. iv) Ale už ne 001123 apod.
7.1. Testování Mobito kódu Pro testování Mobito kódu prosím kontaktujte
[email protected] s předmětem „mobito code test“ a domluvte se na detailnější podpoře ohledně testování.
MOPET CZ a. s.
Page 22 of 76
v1.7
8.
Integrace WebServices požadavky na platbu
Popis Pokud chcete využít Mobito jako platební metodu spouštěnou jiným způsobem nežli klientem přímo z mobilu (Mobito kód) nebo pomocí webového rozhraní, je pro Vás připraveno WebServices rozhraní. Toto slouží k zakládání požadavků na platbu (Request for Payment) a zjišťování stavu transakcí. Uživatelská zkušenost: -
Klient – Nákup na pokladně nebo v systému, který komunikuje s klientem napřímo nebo vzdáleně (jakýkoliv informační kanál, který umí zjistit od klienta ID v systému Mobito aby mu zaslal požadavek na platbu)
Scénář platby: 1) Klient (obecně) – vyjádří přání nakoupit zboží u obchodníka a dokončí objednávku 2) Obchodník – Vyžádá si od klienta jeho číslo (telefonní, nebo Mobito přezdívku), to zadá do svého systému a) Způsob vyžádání je ponechán na procesní a technické realizaci obchodníka může se jednat například o: i) Zákazník sdělí pokladnímu své číslo ii) Číslo může být navázáno na věrnostní kartu, NFC chip, Čárový kód apod. iii) Číslo může být předáno bezdrátově pomocí mobilní aplikace, mobilního webu 3) Mobito systém – zaslání požadavku na platbu na tel. číslo klienta (nativní notifikace, USSD notifikace) 4) Klient (mobilní telefon) – přijetí a autorizace transakce unikátním PINem 5) Mobito systém – ověření transakce a notifikace o úspěšném zaplacení – notifikace klientovi a notifikace webu obchodníkovi. a) Alternativně – Obchodník – dotazuje Mobito systém funkcí „CheckPaymentStatus“
MOPET CZ a. s.
Page 23 of 76
v1.7
sd RFP Flow Timeouts MerchantSystem
mBroker
USSD GW
Handset
StartRFP(validity) RFP Notification(Info)
AcceptReject()
InsertPIN()
PIN() Notofication()
8.1. Testování Web Services Testovací transakce – úspěch 1) Kontaktujte
[email protected] a potvrďte si, připravenost pro testy 2) Vytvořit zkušební transakci – ve vašem systému vytvořte transakci s consumerID 606079502 a po web services kontaktujte server Mobito na adrese http://testapi.imobito.cz:9916/mopet/services/mobitoapi?wsdl 3) 4) 5) 6)
Zjistěte, zda Vám webService potvrdila příjem požadavku na platbu Nechte Váš systém volat CheckPaymentStatus Počkejte, až náš pracovník potvrdí transakci Potvrďte si, že CheckPaymentStatus vrátil stav zaplaceno
Testovací transakce – neúspěch 7) Vytvořit zkušební transakci – ve vašem systému vytvořte transakci s consumerID libovolné vaše číslo a po web services kontaktujte server Mobito na adrese http://testapi.imobito.cz:9916/mopet/services/mobitoapi?wsdl 8) Zjistěte, zda Vám webService potvrdila příjem požadavku na platbu 9) Nechte Váš systém volat CheckPaymentStatus 10) Počkejte, až náš pracovník potvrdí transakci 11) Potvrďte si, že CheckPaymentStatus vrátil stav zrušeno MOPET CZ a. s.
Page 24 of 76
v1.7
Testovací transakce – vypršení časového limitu 12) Kontaktujte
[email protected] a potvrďte si, že chcete testovat vypršení časového limitu 13) Vytvořit zkušební transakci – ve vašem systému vytvořte transakci s consumerID 602 356 797 a po web services kontaktujte server Mobito na adrese http://testapi.imobito.cz:9916/mopet/services/mobitoapi?wsdl a) Stanovte validity na co nejnižší 14) Zjistěte, zda Vám webService potvrdila příjem požadavku na platbu 15) Nechte Váš systém volat CheckPaymentStatus 16) Počkejte, do času, který jste si nastavili v parametru „validity“ 17) Potvrďte si, že CheckPaymentStatus vrátil stav nepotvrzeno
MOPET CZ a. s.
Page 25 of 76
v1.7
9.
Integrace Notifikace
Funkcionalita notifikace funguje pro všechny typy integrací. Pro správnou funkcionalitu nastavte v portálu pro obchodníky u virtuálního zaměstnance „notifikační URL“. Na tuto adresu poté přijde z našeho serveru GET požadavek s parametry platby a podepsán algoritmem uvedeným v kapitole „Ověření klienta“. Alternativně je možné nastavit tento parametr pomocí webové služby „ConfigurePaymentNotification“. Upozornění: Notifikace je posílána po úspěšném, nebo neúspěšném zaplacení okamžitě. V případě vypršení časového limitu jsou notifikace posílány hromadně na základě časovače (aktuálně 5 minut). Může tedy být drobný časový rozdíl u vypršené transakce mezi vypršením a zasláním notifikace (až 4:59 minut).
MOPET CZ a. s.
Page 26 of 76
v1.7
10. Integrace WebServices - Zjištění stavu transakcí Webové služby nabízí funkce pro zjištění stavu transakce, získání více informací o úspěšně proběhlé transakci a Získání detailních informací o seznamu transakcí. Jsou to následující funkce:
CheckPaymentStatus o Zjištění stavu aktuálně prováděné transakce – pro rychlý processing, jsou zde všechny požadavky na platbu GetTransactionDetail o Zjištění detailu o transakci – zde je možné dohledat pouze úspěšně dokončené transakce GetTransactionReport o Získání seznamu transakcí, systém v této funkci také vrátí časově omezený link na stažení vygenerovaného CSV souboru pro strojové zpracování transakční historie.
10.1.
Stavy transakcí
Transakce může za dobu svého života nabývat několika stavů, pro Obchodníka jsou viditelné tyto: o PENDING – transakce čeká na zpracování o OK – transakce je v pořádku zaplacena o FAILED – transakce zamítnuta, či končící chybou Zaslání Platebního požadavku
PENDING
Klient Zadá PIN po expiraci
klient zadá PIN v době expirace [NE]
Sběrný proces expirovaných transakcí
[bez interakce]
[ANO]
[č ekání ve stavu PENDING] [zadá PIN]
validace
[validace OK]
[Proběhl]
[neprošlo validací]
OK
FAILED
konec
MOPET CZ a. s.
Page 27 of 76
v1.7
11. Ověření odpovědí ze systému Metody upozornění na platbu (Notification a přesměrování z platební brány) obsahují kromě údajů o transakci i podpis. Takto může obchodník jednoduše zjistit, že není daná informace o transakci podvržená a není nutné další zjišťování výsledku transakce.
11.1.
Bezpečnostní kód
V portálu pro obchodníky je vždy v sekci virtual employee vygenerován bezpečnostní kód. Jedná se o 20 znaků dlouhý text, který se poté vkládá do algoritmu jako klíč pro zabezpečení. Je velmi důležité, aby tento kód nebyl nikdy znám nikomu jinému nežli důvěryhodným osobám obchodníka a aby nebylo možné jej jednoduše zjistit například zobrazením zdrojového kódu na webu obchodníka apod. Bezpečnostní kód je v následujícím algoritmu uveden pod názvem „presharedSecret“.
11.2.
Algoritmus
Do zprávy se přidává jako podpis tzv. messageDigest. Ten je vytvořen jako SHA256 hash z řetězce parametrů na konci doplněných o bezpečnostní kód – presharedSecret. Server vypočte tento podpis a zašle jej spolu s notifikací, nebo přesměrováním. Ověření na straně obchodníka probíhá tak, že obchodník stejným způsobem vypočte podpis ze zaslaných parametrů a bezpečnostního kódu a výsledný řetězec porovná s přijatým podpisem. Jako výstup se používá „hexadecimální“ způsob zápisu s malými písmeny a-f. V programovacím jazyce může vypadat zápis například takto: messageDigest = makeSHA256Hash(sourceId + sourceTxnId + invoiceId + sourceAuthKey + paymentAmount + sourceTimestamp + presharedSecret+ TxnStatus) Zápis se může lišit dle programovacího jazyka, znak „+“ v tomto zápise značí spojení dvou řetězců za sebe. Například v jazyce PHP se použije znak „.“(tečka). Jednotlivé parametry jsou popsány v příloze B. Mezi hodnotami nejsou vkládány žádné mezery ani jiné prázdné znaky a hodnoty jsou včetně všech znaků tak jak byly zadány (je tedy nutné zahrnout i například počáteční nuly u některých parametrů) Výsledek je v hexadecimálním formátu se znaky a-f označenými malými písmeny. Pro vyzkoušení je možné využít online službu pro vypočítání hash např. na: http://hash.online-convert.com/sha256-generator (výsledek ve verzi hex)
MOPET CZ a. s.
Page 28 of 76
v1.7
12. FAQs 1. Chci zapojit svůj internetový obchod pro platby pomocí Mobito a. Nejlepší variantou je využít platební tlačítko i. S Integrací (takřka online vidíte, že bylo zaplaceno a peníze převedeny na Váš účet) 2. Chci zapojit možnost darovat pevnou částku, nepotřebuji okamžitě vědět o všech platbách a. Nejlepší variantou je platební tlačítko, nemusíte použít žádné integrace, stačí pouze stáhnout kód, který začleníte do svých stránek, o příchozích platbách se dozvíte buď po přihlášení do portálu obchodníka, nebo mohou chodit upozornění e-mailem 3. Chci zapojit své kamenné prodejny a. Nejlepší variantou je využít integraci pomocí webových služeb 4. Můj obchodní plán počítá s oslovováním zákazníků na ulici a placení na místě a. Nejlepší variantou je integrace Mobito Code
MOPET CZ a. s.
Page 29 of 76
v1.7
Příloha A Kód platebního tlačítka Formulář standardního tlačítka: Do svých stránek zkopírujte následující kód a vyplňte žluté prvky. Jejich význam je popsán níže.
