Połączenie Partnera z serwisem JustPay poprzez

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:
<?xml version="1.0" encoding="UTF-8"?>
<url xmlns="http://kody.avantis.pl/smscodes/schema/url"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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:
<?xml version="1.0" encoding="UTF-8"?>
<url xmlns="http://kody.avantis.pl/smscodes/schema/url"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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="la" value="payload.recipient"/>
<param name="command" value="payload.text">
<trim/>
<toUpper/>
</param>
</url>
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:
<?xml version="1.0" encoding="UTF-8"?>
<keyResponse xmlns="http://kody.avantis.pl/smscodes/schema/keyResponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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: [email protected]