Subskrypcje MT (płatność za otrzymany SMS)

Subskrypcje MT
(płatność za otrzymany SMS)
Uruchomienie subskrypcji umożliwia tworzenie serwisów, gdzie Użytkownik płaci za każdy odebrany
SMS. Każdy serwis ma zdefiniowany wcześniej dni i godziny kiedy realizowane są wysyłki do
Użytkowników. Strona www wyświetlająca informacje dla Użytkownika o możliwości zapisaniu się
do danej subskrypcji i niezbędnych informacjach z tym związanych – jest automatycznie generowana
przez serwis Justpay (po wcześniejszym wpisaniu numeru telefonu przez Użytkownika na stronie
Partnera serwisu).
Spis treści
1. Zdefiniowanie własnej subskrypcji
2. Rejestracja Użytkownika
a. Rejestracja z wykorzystaniem API (Użytkownik nie opuszcza www Partnera) lub
b. Rejestracja przez przejściówkę (przekierowanie na stronę www Justpay)
3. Weryfikacja pobrania opłaty od Użytkownika
4. Proces korzystania z subskrypcji przez Użytkownika
5. Jak skonfigurować i wdrożyć przykładowe lub własne skrypty
6. Przykład zabezpieczonej strony
1. Zdefiniowanie własnej subskrypcji
1. Rejestracja w serwisie JustPay (po otrzymaniu e-maila potwierdzającego rejestrację).
2. Po zalogowaniu na swoje konto - zdefiniowanie pierwszej subskrypcji.
a. zakładka 'Subskrypcje' - przycisk 'dodaj nową komendę'
b. określenie parametrów nowej subskrypcji i odpowiednich pól:
• czy serwis ma być przeznaczony tylko dla osób dorosłych,
• jaką kwotą i jak często użytkownik ma być obciążany,
• czy subskrypcja ma być czasowa (pobranie opłaty przedłuża subskrypcję i dostęp do
serwisu o określoną liczbę godzin bądź dni), czy też zliczeniowa: pobranie opłaty zasila
konto określoną liczbę tokenów (tzn. Użytkownik może wejść na serwis określona ilość
razy). Jest to konfiguracja podobna do metody 3.
3. Znaczenie poszczególnych pól w formularzu dodawania/edycji subskrypcji:
Rodzaj i typ subskrypcji:
a. "Serwis tylko dla osób +18": należy zaznaczyć w przypadku serwisu dla dorosłych,
b. "Cena": pole wyboru: kwota, jaką będzie obciążony użytkownik,
c. "Okres": dni oraz godzina wysyłki smsów bilujących,
d. "Prefix": nazwa serwisu
Dane techniczne:
e. "Id": unikalny numer ID Partnera, nadawany przez system JustPay
f. "Rejestracja www (tylko sieć Orange)": zaznaczamy w przypadku, jeśli Partner chce w
sieci Orange mieć rejestrację poprzez WWW (po wpisaniu numeru telefonu na stronie,
przychodzi na telefon unikalny TOKEN. Po wpisaniu go na stronie, Użytkownik zapisuje
się do serwisu (nie ma potrzeby wysyłania SMSa o treści np. START PAY na 60255)
g. "Adres www w przypadku poprawnej weryfikacji": adres, na który Użytkownik będzie
przekierowany po prawidłowym zakończeniu rejestracji z wykorzystaniem 'przejściówki',
h. "Adres www w przypadku błędnej weryfikacji": adres, na który Użytkownik będzie
przekierowany w przypadku wystąpienia błędu podczas próby rejestracji do serwisu (w
przypadku wykorzystania „przejściówki”),
i. "Max liczba użyć tego samego kodu": liczba tokenów przydzielanych Użytkownikowi
po każdym obciążeniu (tzn. Użytkownik może wejść na serwis określona ilość razy).
j. "Czas ważności dostępu": o tyle godzin bądź dni będzie przedłużona ważność dostępu w
przypadku subskrypcji czasowej.
Opis wykorzystania subskrypcji:
k. "Opis serwisu": krótki opis serwisu Partnera, na czym polega, zasady, itp.
l. "Opis promocji serwisu i przewidywany miesięczny ruch SMS": serwisy tego typu
uruchamiamy tylko w wypadku średnich i dużych serwisów
m. "Link do serwisu": adres www serwisu Partnera
n. "Link do regulaminu serwisu": bezpośredni adres www regulaminu serwisu Partnera
7. Po zatwierdzeniu formularza można powrócić do edycji subskrypcji używając linku "zmień"
w odpowiednim wierszu w zakładce "Subskrypcje". W celu uruchomienia serwisu, należy
zamknąć edycję przez naciśnięcie "OK". Subskrypcja jest ostatecznie aktywowana przez
administratora justpay po zweryfikowaniu wprowadzonych danych.
UWAGA! Po zamknięciu edycji nie jest możliwa zmiana pól: "Serwis tylko dla osób +18",
"Cena", "Okres" oraz "Prefiks".
2. Rejestracja Użytkownika
Po zaakceptowaniu subskrypcji przez administratora użytkownicy serwisu Partnera mogą się do niej
rejestrować. Rejestracja Użytkownika może przebiegać na dwa sposoby.
•
•
poprzez udostępnione API: wszystkie operacje z punktu widzenia użytkownika
przeprowadzane są bez opuszczania serwisu Partnera,
poprzez 'przejściówkę': użytkownik przekierowany jest na stronę specjalną stronę serwisu
justpay, gdzie następuje finalizacja rejestracji, po czym wraca z powrotem na stronę Partnera.
W obu przypadkach Partner musi dostarczyć następujące informacje dotyczące rejestrowanego
użytkownika:
•
•
•
•
a)
numer telefonu użytkownika,
nazwa operatora telefonii komórkowej, której abonentem jest użytkownik (jest to informacja
konieczna ze względu na możliwość przenoszenia numerów do innych operatorów),
nazwa subskrypcji (wybierana podczas tworzenia serwisu),
numer LA (widoczny w tabeli w polu "Numer SMS")
Rejestracja z wykorzystaniem API
Dostęp do API (interfejsu REST) jest chroniony za pomocą basic-authorization. Przy wywoływaniu
wszystkich metod, należy podać login i hasło Partnera.
W celu rejestracji użytkownika, należy wysłać metodą POST (kontent type: application/xml)
następujący XML:
<register>
<operator>POLAND_ERA</operator>
<msisdn>48501234567</msisdn>
<name>TEST</name>
<la>555</la>
</register>
pod adres: https://www.justpay.pl/smscodes/mt/subscriber
Lista kodów operatorów:
<operator>POLAND_ORANGE</operator>
<operator>POLAND_ERA</operator>
<operator>POLAND_PLUS</operator>
<operator>POLAND_P4</operator>
Wywołanie metody GET na adresie:
https://www.justpay.pl/smscodes/mt/operator/numer_telefonu
zwraca nazwę operatora dla podanego numeru telefonu. Informacja jest prawdziwa tylko wtedy, gdy
numer nie został przeniesiony do innego operatora.
W przypadku prawidłowej rejestracji (kod HTTP 2xx), zwrotnie zostanie dostarczony XML:
<info>
<command>TEST1</command>
<la>60255</la>
<subscriberId>39</subscriberId>
<msisdn>48501234567</msisdn>
<description>Test description</description>
<priceGr>500</priceGr>
<sendsPerWeek>7</sendsPerWeek>
<webActivation>false</webActivation>
<backURL>http://partner.service.pl</backURL>
</info>
Informacje zawarte w XML'u to odpowiednio:
• la, command: numer SMS oraz prefiks (również nazwa serwisu u operatora),
• subscriberId: identyfikator Subskrybenta (Użytkownika) w systemie Justpay,
• msisdn: numer telefonu użytkownika,
• description: opis podany podczas rejestracji,
• priceGr: cena w groszach,
• sendsPerWeek: liczba wysyłek w ciągu tygodnia,
•
•
webActivation: true, w przypadku, gdy możliwa jest aktywacja przez stronę www (bez
konieczności wysyłki dodatkowego sms'a),
backURL: nie używane w tej metodzie rejestracji
Dane takie są wystarczające do wyświetlenia na stronie Partnera informacji o tym, jakie dalsze kroki
powinien podjąć użytkownik w celu rejestracji w subskrypcji: w przykładzie użytkownik powinien
wysłać SMS aktywujący na numer 60255 o treści 'START TEST1'.
Wykonanie opisanej operacji na www spowoduje rejestrację użytkownika w systemie Justpay. Jednak
do jej dokończenia konieczne jest wysłanie przez użytkownika SMS-a rejestracyjnego, co spowoduje
potwierdzenie rejestracji. W przypadku gdy użytkownik nie potwierdzi rejestracji w ciągu 1h,
zostanie automatycznie usunięty z systemu i całą rejestrację trzeba powtórzyć.
Polecamy zapisanie identyfikatora subskrybenta (na przykład bazie danych w danych użytkownika):
ułatwi to późniejsze odpytywanie systemu justpay o to, czy subskrypcja dla danego użytkownika jest
opłacona.
WAŻNE
W przypadku korzystania z własnej strony przejściowej, konieczne jest podanie wszystkich
niezbędnych danych wymaganych przez operatorów (poniżej pokazane są także screeny, jak
wyglądają przejściówki Justpay):
•
Jest to usługa subskrypcyjna
•
Usługa dostępna jest w sieci Plus, Era, Orange, Play
•
Opłata za każdy SMS przychodzący to: (np. 2 zł netto, 2,46 zł z VAT)
•
W ciągu tygodnia będą wysyłane maksymalnie 3 SMSy
•
Aby wypisać się z usługi należy wysłać SMS o treści: (np. STOP PAY na 60255). Opłata
jak za zwykły SMS
•
Link do regulaminu usługi
•
Adres email do obsługi reklamacji
b) Rejestracja przez przejściówkę
W celu uruchomienia rejestracji przez stronę pośredniczącą Justpay („przejściówkę”), należy wysłać
formularz (metodą POST) z ustawionymi polami (ich typ nie ma znaczenia) na adres:
https://www.justpay.pl/smscodes/mt/{mtid}
gdzie {mtid} jest identyfikatorem właściciela serwisu MT w systemie Justpay. Identyfikator ten
(„Identyfikator Klienta”) jest widoczny w zakładce "Subskrypcje" przy konfiguracji danego serwisu
lub jego edycji (poprzez link „Zmień”).
Przykładowy formularz:
<form method="post" action="http://www.justpay.pl/smscodes/mt/1">
<table>
<tr>
<td><label for="msisdn">msisdn: </label></td>
<td><input name="msisdn" id="msisdn" type="text"/></td>
</tr>
<tr>
<td><label for="operator">operator: </label></td>
<td><input id="operator" name="operator" type="text"/></td>
</tr>
<tr>
<td><label for="name">name: </label></td>
<td><input id="name" name="name" type="text"/></td>
</tr>
<tr>
<td><label for="la">la: </label></td>
<td><input name="la" id="la" type="text"/></td>
</tr>
<th>
<td colspan="2"><input type="submit" value="OK"/></td>
</th>
</table>
</form>
Jeśli rejestracja zakończy się sukcesem, użytkownik zostanie przekierowany na stronę, gdzie zostanie
wyświetlona informacja, jakie kroki muszą zostać podjęte w celu dokończenia subskrypcji. Po
naciśnięciu na przycisk"OK" użytkownik zostanie przekierowany na adres podany w polu "Adres
www w przypadku poprawnej weryfikacji".
Podczas tworzenia adresu powrotnego do podanego URL istnieje możliwość dodania parametrów
zwrotnych, które mogą być przydatne dla Partnera. Parametry są analogiczne do tego, co opisano w
przypadku rejestracji z wykorzystaniem API, a podawane są w następującej kolejności: command, la,
subscriberId, msisdn, description, priceGr, sendsPerWeek, webActivation. Przykładowo dla URL
ustawionego jako:
http://serwis.partnera.pl/skrypt/{0}:{1}/{2}
utworzony adres będzie miał postać:
http://serwis.partnera.pl/skrypt/TEST1:60255/39. Podobnie, jak w przypadku rejestracji przez API,
warto zapisać identyfikator subskrybenta (argument 2).
Oto screeny pokazujące przejściówkę Justpay:
Standardowa:
Wersja dla rejestracji WWW (dla Orange):
3. Weryfikacja pobrania opłaty od Użytkownika
Tak jak w przypadku rejestracji przez API dostęp do interfejsu REST jest chroniony za pomocą basicauthorization. Przy wywoływaniu wszystkich metod, należy podać login i hasło Partnera.
W celu sprawdzenia czy dany subskrybent ma aktywną subskrypcję, należy wykonać metodę PUT na
adresie:
https://www.justpay.pl/smscodes/mt/check/{subscriberId}
gdzie subscriberId jest zapamiętanym wcześniej identyfikatorem subskrybenta. Zapamiętywanie
identyfikatora nie jest konieczne. Ważność subskrypcji można sprawdzić również wykonując metodę
PUT na adresie:
https://www.justpay.pl/smscodes/mt/check/{msisdn}/{prefix}:{la}
gdzie: {msisdn} to numer telefonu użytkownika; {prefix} to prefiks w systemie justpay; {la} to numer
SMS, na którym działa serwis MT.
W wyniku otrzymywany jest ciąg znaków 'true' w przypadku, gdy podany subskrybent ma aktywną
subskrypcję, bądź też 'false' w przeciwnym przypadku.
UWAGA: w przypadku subskrypcji zliczeniowych każdorazowe wykonanie metody powoduje
zmniejszenie liczby dostępnych tokenów o jeden. Należy to uwzględnić podczas implementacji
serwisu.
4. Proces korzystania z subskrypcji przez Użytkownika
REJESTRACJA
1) Użytkownik na stronie Partnera znajduje funkcjonalność, która jest płatna w formie
subskrypcji;
2) Użytkownik decyduje się na subskrypcję i podaje na stronie Partnera swój numer telefonu
komórkowego oraz wybiera swoją sieć komórkową;
3) W zależności od wariantu wdrożenia Użytkownik otrzymuje informację na www Partnera
lub na stronie Justpay o numerze SMS (np. 60255), pod który powinien przesłać komendę
rejestracyjną (np. START PAY), aby dokończyć rejestrację w subskrypcji. Dodatkowo na
tej stronie znajdują się informacje o kosztach za otrzymywane SMSy, częstotliwości ich
wysyłania oraz link do regulaminu i reklamacji;
4) Użytkownik wysyła SMS rejestracyjny (koszt jak zwykły SMS wg jego planu taryfowego), a
w odpowiedzi otrzymuje potwierdzenie rejestracji w postaci dwóch SMSów zwrotnych przykłady:
Witamy w usludze subskrypcje kodow Justpay. Oplata za kazdego przychodzacego SMS
specjalnego to 2,00 PLN netto (2,46 PLN brutto). Otrzymasz 3 SMSy tygodniowo.
Komenda do dezaktywacji uslugi: SMS o tresci STOP PAY pod numer 60255. Regulamin
na: www.justpay.pl/mt
Treści wiadomości SMS są stałe i niezmienne dla danego serwisu.
POBIERANIE OPŁAT OD UŻYTKOWNIKA
5) Maksymalnie w ciągu 30 minut od rejestracji Użytkownik otrzymuje pierwszą płatną
wiadomość SMS o treści (stała treść dla wszystkich serwisów):
Dostep do wybranej przez Ciebie uslugi zostal aktywowany.
6) Kolejne wiadomości płatne Użytkownik otrzymuje zgodnie z wybraną subskrypcją (np. trzy
razy w tygodniu). Jest to wiadomość SMS o treści (stała treść dla wszystkich serwisów):
Dostep do wybranej przez Ciebie subskrypcji zostal przedluzony.
KORZYSTANIE Z USŁUGI PARTNERA
7) Po dokonaniu rejestracji Użytkownik wybiera link umożliwiający skorzystanie z opłaconej
funkcjonalności na www Partnera (wymagane podanie przez Użytkownika przynajmniej
numeru telefonu komórkowego, który został wcześniej użyty przy rejestracji);
8) Partner wtedy wykorzystuje połączenie do Justpay, aby zweryfikować, czy została pobrana
opłata od Użytkownika poprzez płatny SMS z subskrypcji;
9) Jeśli tak, to Użytkownik otrzymuje dostęp do płatnej funkcjonalności.
5. Jak skonfigurować i wdrożyć przykładowe lub własne skrypty
Przygotowanie strony z formularzem do logowania. W odpowiednim miejscu na stronie,
należy dodać następujący kod PHP:
<?php
include_once('MtSubscriptionsLib.php');
$c->render($label = "msisdn:",$prefix = "PAY",$la = "60255", $actionscript = "login.php");
?>
W miejsce "msisdn:", należy podać tekst, który ma się wyświetlać przy okienku do
wprowadzania kodu, a zamiast "login.php", skrypt który przetworzy proces logowania.
W miejsce PAY należy wstawić nazwę ustawionej subskrypcji, $la to numer na który mają
być wysyłane smsy rejestracyjne.
Oczywiście "PAY" oraz "60255" należy zastąpić odpowiednio zdefiniowaną komendą i
jednym z numerów SMS Premium.
Przygotowanie strony zabezpieczonej. W celu zabezpieczenia strony, należy dodać na samym
początku w kodzie PHP dodać:
<?php
session_start();
include_once('MtSubscriptionsLib.php');
$c = new MtSubscriptionsLib();
if (!$c->isSessionCodeValid()) {
header("Location: login.php");
exit;
}
?>
W momencie gdy użytkownik nie logował się wcześniej zostanie przekierowany na stronę do
logowania.
Dla metody tej przygotowano przykładowe skrypty które przedstawiają podstawową logikę
aplikacji czyli strona do logowania, formularz do rejestracji który korzysta z metody z
wykorzystaniem przejściówek.
Przedstawione skrypty są jedynie przykładami — często są one celowo uproszczone, czy też
napisane wręcz schematycznie. W przypadku ich ewentualnej integracji z produkcyjnym
systemem, należy pamiętać o ich dokładnym sprawdzeniu pod kontem wymogów konkretnej
aplikacji, oraz zgodności ze standardami bezpieczeństwa przyjętymi w systemie docelowym.
Klasa MtSubscriptionsLib
Klasa MtSubscriptionsLib zdefiniowana w pliku MtSubscriptionsLib.php, służy do
komunikacji z systemem justpay.pl w celu weryfikacji subskrypcji
Wykorzystanie klasy MtSubscriptionsLib jest bardzo proste. Wystarczy na początku skryptu
PHP, który ma być „chroniony”, dokleić na samym początku następujący fragment kodu:
<?php
session_start();
include_once('MtSubscriptionsLib.php');
$c = new MtSubscriptionsLib();
if (!$c->isSessionCodeValid()) {
header("Location: login.php");
exit;
}
?>
W celu wyświetlenia formularza do wprowadzenia kodu przez użytkownika, można użyć
następującego fragmentu kodu:
<?php
session_start();
include_once('MtSubscriptionsLib.php');
$c->render($label = "msisdn:",$prefix = "PAY",$la = "60255", $actionscript =
"login.php");
?>
W miejsce "msisdn" należy wstawić etykietę, która ma być związana z polem tekstowym do
wprowadzenia kodu, natomiast w miejsce "login.php" — skrypt, który przetworzy proces
logowania. W miejsce PAY należy wstawić nazwę ustawionej subskrypcji., $la to numer na
który mają być wysyłane smsy rejestracyjne.
Skrypt do przetworzenia procesu logowania może wyglądać następująco:
include_once('MtSubscriptionsLib.php');
$c = new MtSubscriptionsLib();
if (isset($_POST['msisdn']) && floatval($_POST['msisdn']) && (strlen($_POST['msisdn'])
== 9 || strlen($_POST['msisdn']) == 11)) {
//sprawdzamy czy podane przez użytkownika parametry są prawidłowe i czy ma wykupioną
subskrypcje
$test = $c->isMsisdnValid($_POST['msisdn'], $_POST['la'], $_POST['prefix']);
if ($test) {
header("Location: premium.php");
exit;
} else {
$c->setloginError("numer nie posiada wykupionej subskrypcji");
}
}else{
if(isset($_POST['msisdn'])){
$c->setloginError("podany numer nie jest prawidłowy");
}
}
Na stronę rejestracyjną formularz do rejestracji metodą przejściówkową możemy wstawić w
następujący sposób:
<?php
include_once('MtSubscriptionsLib.php');
$c->renderregister($prefix = "PAY",$la = "60255", $subscriptionid = "1000202");
?>
6. Przykład zabezpieczonej strony
Kompletny przykład „zabezpieczonej” strony składa się z następujących plików:
index.php — strona nie zabezpieczona prezentująca informacje o dostępnych opcjach
– możliwość logowania i możliwość rejestracji
MtSubscriptionsLib.php — opisana wyżej definicja klasy MtSubscriptionsLib,
login.php — przykładowy formularz do wprowadzania numeru telefonu - weryfikuje
on czy posiadacz numeru ma wykupioną subskrypcję,
premium.php – strona zabezpieczona – próba wejścia bezpośrednio na tą stronę bez
logowania powoduje przekierowanie użytkownika na stronę login.php
otherpremium.php — druga zabezpieczona strona (umożliwia powrót do pierwszej:
„głównej” zabezpieczonej strony).
register.php – strona z formularzem umożliwiającym rejestrację użytkownika do
subskrypcji
Jeśli cała konfiguracja została przeprowadzona prawidłowo, to przykładowa strona powinna
działać następująco:
1. domyślnie ładuje się strona index.php , jeżeli użytkownik jest już zalogowany i
spróbuje wejść na stronę główną zostanie przekierowany na stronę premium.php
2. Jakakolwiek próba dostania się na stronę „chronioną”, powinna spowodować
wyświetlenie login.php,
3. Po podaniu numeru telefonu który ma wykupioną subskrypcję, użytkownik
powinien mieć swobodną możliwość przechodzenia pomiędzy stronami
zabezpieczonymi (bez konieczności ponownego podawania numeru telefonu).
W razie pytań prosimy o kontakt: [email protected]