Połączenie Partnera z serwisem JustPay poprzez - METODĘ 2 Generowanie kodów: po stronie Partnera Weryfikacja kodów: po stronie Partnera Spis treści 1. Kolejne kroki w stworzeniu własnego serwisu 2. Jak skonfigurować i wdrożyć przykładowe lub własne skrypty 3. Sposób generacji kodów + przykłady 1. Kolejne kroki w stworzeniu własnego serwisu 1. Rejestracja w serwisie JustPay i poczekanie na maila potwierdzającego rejestrację. 2. Po zalogowaniu - zdefiniowanie komend oraz numerów SMS Premium. a. zakładka 'komendy' - przycisk 'dodaj nową komendę' b. wybrać prefiks z listy i sufiks komendy c. zatwierdzić przyciskiem 'OK' (system automatycznie przekieruje do punktu 3) 3. Dodanie numeru do komendy (link 'dodaj numer' w zakładce 'komendy') a. wybór numeru SMS Premium z listy dostępnych b. wybór metody generacji; w tym przypadku: 'Metoda 2' c. przygotowanie opisu URL zgodnie ze schematem. URL ma kierować do skryptu, znajdującego się u Partnera, generującego kody d. definicja SMS'a zwrotnego: w okienku należy wpisać treść SMS'a zwrotnego; ciąg znaków '$1' zostanie zastąpiony jednym z kodów z paczki e. zatwierdzenie numeru przyciskiem 'OK' 4. Po zdefiniowaniu wszystkich potrzebnych numerów (można ich dodać więcej niż jeden), należy zamówić aktywację komendy. 5. Po zaakceptowaniu komendy przez administratora systemu, użytkownik zostanie poinformowany e-mail'em. Podczas oczekiwania na akceptację można przystąpić do realizacji dalszych kroków przygotowanie skryptów do generacji i weryfikacji kodów. Po otrzymaniu przez system JustPay SMSa Użytkownika: 1. Justpay analizuje opis URL, generuje odpowiedni link i pobiera kod od Partnera ("puka" metodą GET w serwer Partnera). 2. Partner zwraca wygenerowany kod (ew. treść SMS-a). 3. Justpay odsyła SMS-a Użytkownikowi z dostarczonym kodem (ew. treścią). 4. Użytkownik wpisuje kod na stronie www Partnera 5. Partner sprawdza, czy kod wpisany przez klienta jest taki sam, jaki został wysłany do JustPay. 6. Jeśli kod jest prawidłowy, Partner zezwala na dostęp do chronionych treści.
2. Jak skonfigurować i wdrożyć przykładowe lub własne skrypty 1. Utworzenie skryptu generującego kody. Generacja kodów może być uzależniona od komendy, numeru SMS Premium itp. Dodatkowo do skryptu można przekazywać treść sms'a i numeryczny identyfikator wiadomości. Opis URL utworzony w punkcie 4 powinien kierować na ten właśnie skrypt i powinien dostarczać odpowiednich parametrów metodą GET. W szczególnym przypadku, można za każdym razem zwracać taką samą treść SMS'a (bez generacji kodu) - umożliwia to realizację stron typu 'płatne ogłoszenia przez SMS'. 2. Przygotowanie strony zabezpieczonej. Sposób zabezpieczenia jest w dużej mierze zależny od tego jak został zrealizowany skrypt w pkt 1 powyżej. 3. Dla metody tej przygotowano przykładowe skrypty: a. plik sms_import.php realizuje przykładowy 'generator' odpowiedzi zwrotnych b. ExampleKeyResponse.php - klasa implementująca przykładowy generator. W celu dostosowania skryptu do własnych potrzeb, wystarczy rozszerzyć klasę ExampleKeyResponse i przeciążyć odpowiednio metody getsmstext() oraz getcode(). c. Metod a validate() została rozszerzona o zapis informacji : - Numer LA numer na który został wysłany sms, - smscode kod który zwracany jest w smsie zwrotnym - msisdn numer telefonu z którego wysłany został sms - text treść smsa wysłanego przez użytkownika informacje te zapisywane są w bazie mysql w celu późniejszej weryfikacji przy logowaniu się przez użytkownika do części zamkniętej swerwisu Informacje gromadzone w trakcie rejestracji przechowywane są w tabeli o następującej strukturze: CREATE TABLE `registered` ( `id` INT(11) NOT NULL AUTO_INCREMENT, `la` VARCHAR(50) NOT NULL, `code` VARCHAR(50) NOT NULL, `msisdn` VARCHAR(14) NOT NULL, `txt` VARCHAR(50) NOT NULL, `session_start` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, `used` TINYINT(1) NOT NULL, PRIMARY KEY (`code`) ) COLLATE='utf8_general_ci' ENGINE=MyISAM ROW_FORMAT=DEFAULT
3. Sposób generacji kodów Generacja kodu (unikalnego hasła), za który użytkownik płaci jest skonstruowana w ten sposób, iż kody są pobierane każdorazowo z serwisu Partnera poprzez odpowiednio zbudowany URL. W celu uruchomienia zaawansowanego sposobu generacji kodów, należy przygotować dokument XML'owy z opisem URL'a. Dokument ten musi być zgodny ze schematem zamieszczonym pod adresem: http://data.avantis.pl/schema/urldescription.xsd Jedynymi obowiązkowymi elementami są: proto (protokół) oraz host (nazwa domenowa lub IP komputera, który generuje kody), jednakże najprawdopodobniej użytkownik będzie wypełniał element path (pełna ścieżka do skryptu), oraz listę parametrów (elementy param). Parametry Każdy parametr ma dwa obowiązkowe atrybuty: nazwę (name) oraz wartość (value - o prawidłowych wartościach niżej). Dodatkowo wartość można poddać dowolnej liczbie transformacji takich jak: - toupper: zamiana wszystkich liter na wielkie, - tolower: zamiana wszystkich liter na małe, - trim: obcięcie białych znaków przed i za tekstem - subst: zamiana ciągów znaków - transformacja z dwoma parametrami: a) regex: wyrażenie regularne (wzorzec) b) replace: wyrażenie, na którym ma zostać zastąpione wszystko co pasuje do wzorca Wartości parametrów Wiadomości przetwarzane przez serwis "widziane są" jako obiekty. Wartością może być dowolne pole dostępne w dostarczonej wiadomości. Z punktu widzenia Użytkownika najbardziej przydatne pola to: - messageid - czyli unikalny identyfikator każdej wiadomości - payload.operator.operatorcode - operator GSM - payload.text - treść wiadomości (SMS'a) - payload.sender - numer Użytkownika z którego wiadomość "przyszła" - payload.recipient - numer na który wiadomość została przysłana - payload.senddate - data wysłania SMSa Wymieniono tylko podstawowe pola, które w większości przypadków w zupełności wystarczą do prawidłowego przetworzenia wiadomości i wygenerowania kodu. W razie potrzeby dostępu do dodatkowych informacji, prosimy o kontakt.
Przykład 1 Powiedzmy, ze do generacji unikatowego hasła nie są potrzebne żadne informacje - skrypt generuje nowe kody przy każdym zapytaniu. Dodatkowo autor serwisu chce przechowywać w swojej bazie danych informacje o identyfikatorze wiadomości po stronie JustPay (na przykład dla ułatwienia obsługi reklamacji). Komunikacja ma zachodzić przy pomocy protokołu http, skrypt o nazwie generate.do jest umieszczony na komputerze przyklad1.pl. Zamierzony URL wygląda następująco: http://przyklad1.pl/generate.do?mid=xxx Gdzie XXX to identyfikator wiadomości po stronie JustPay. W celu uzyskania w/w funkcjonalności, należy przygotować następujący opis: <url xmlns="http://kody.avantis.pl/smscodes/schema/url" xsi:schemalocation="http://kody.avantis.pl/smscodes/schema/url http://data.avantis.pl/schema/urldescription.xsd"> <proto>http</proto> <host>przyklad1.pl</host> <path>/generate.do</path> <param name="mid" value="messageid"/> </url> Przykład 2 Wraz z rozwojem serwisu, Klient może potrzebować więcej danych (jak na przykład wysłana komenda, czy też numer SMS Premium, na który został przysłany SMS - numer identyfikuje cenę, więc jest to informacja istotna). Przez analogię, wymagany URL to: http://przyklad2.pl/generate.jsp?la=xxx&command=yyy Gdzie XXX to numer, a YYY to komenda. W celu uzyskania w/w funkcjonalności, należy przygotować następujący opis: <url xmlns="http://kody.avantis.pl/smscodes/schema/url" xsi:schemalocation="http://kody.avantis.pl/smscodes/schema/url http://data.avantis.pl/schema/urldescription.xsd"> <proto>http</proto> <host>przyklad1.pl</host> <path>/generate.do</path>
</url> <param name="la" value="payload.recipient"/> <param name="command" value="payload.text"> <trim/> <toupper/> </param> Użytkownik może dowolnie przekształcać za pomocą transformacji wartości przed generacją URL'a. Prawidłowa odpowiedź System po stronie Partnera powinien odpowiadać dokumentem XML zgodnym ze schematem zamieszczonym pod adresem: http://data.avantis.pl/schema/keyresponse.xsd Jedynym wymaganym elementem odpowiedzi jest wygenerowany kod. Dla przykładu, jeśli wygenerowanym kodem jest XY, to odpowiedź wyglądać powinna następująco: <keyresponse xmlns="http://kody.avantis.pl/smscodes/schema/keyresponse" xsi:schemalocation="http://kody.avantis.pl/smscodes/schema/keyresponse http://data.avantis.pl/schema/keyresponse.xsd"> <code>xy</code> </keyresponse> W przypadku niezgodności odpowiedzi ze schematem, bądź też jakichkolwiek problemów komunikacyjnych (odpowiedź serwera inna niż 200, brak odpowiedzi, timeout, itp.) wiadomość przysłana przez Użytkownika zostaje opóźniona i przetworzona w późniejszym terminie. W przypadku powtarzających się problemów, Użytkownik może zostać wpisany na "czarną listę" - komunikaty są wtedy kolejkowane (opóźniane) aż do rozwiązania problemu, przy czym kolejne próby pozyskania kodu są coraz bardziej odległe od siebie. Aplikacja justpay.pl komunikuje się z Partnerem z poniższego zakresu IP: Network: 81.210.48.32/27 HostMin: 81.210.48.33 HostMax: 81.210.48.62 W razie pytań prosimy o kontakt: justpay@avantis.pl