Implementacja mechanizmu SkyCashClick Wersja 0.1 SkyCash 1/6
Spis treści: 1. Opis usługi... 3 2. Osadzenie przycisku SkyCashClick... 4 2.1. Parametry transakcji... 4 2.2. Weryfikacja znacznika parametrów transakcji... 4 2.3. Powiadomienie o dokonaniu płatności... 5 a) timestamp... 5 b) message... 5 c) to... 5 d) amount... 5 e) ref... 5 f) cmessage... 5 g) from... 5 h) currency... 5 i) signed... 5 2.4. Weryfikacja płatności... 6 SkyCash 2/6
1. Opis usługi SkyCashClick to alternatywny dla Pay Link a sposób zapłaty za określone produkty, prezentowany na stronie sklepu w postaci przycisku umieszczonego na stronie będącej podsumowaniem koszyka lub bezpośrednio na stronie będącej opisem produktu. Aby dokonać płatności metodą SkyCashClick, użytkownik sklepu nie jest kierowany na kolejną stronę inicjującą płatność, przejście przez panel transakcyjny, jak w przypadku klasycznych metod płatności typu Pay Link, gdyż zapłata odbywa się w oparciu o dedykowaną usługę w aplikacji mobilnej SkyCash. Integracja w modelu SkyCashClick ogranicza się do umieszczenia na stronie sklepu widgetu, którego efektem widocznym przez kupującego jest przycisk, którego wskazanie myszką (poprzez wciśnięcie lewego przycisku myszy) spowoduje rejestrację (w tle) transakcji w systemie i wyświetlenie użytkownikowi dedykowanego dla transakcji kodu, który jest jedynym parametrem identyfikującym transakcję. Celem realizacji płatności, użytkownik powinien wprowadzić kod transakcji w zakładce usługi, dostępnej w aplikacji mobilnej. Ponadto tylko za pierwszym razem wymagane jest wprowadzenie danych adresowych do wysyłki zamówienia. Podczas kolejnych zakupów dane adresowe zostaną zapamiętane w aplikacji. Po zakończeniu proces na przycisku SkyCashClick pojawi się użytkownikowi informacja o dokonaniu płatności (w miejsce wcześniej prezentowanego kodu), a sam przycisk przekieruje użytkownika do strony będącej podsumowaniem transakcji. Funkcjonalność przekierowania na stronę podsumowania jest opcjonalna, jeżeli w procesie osadzenia widgetu, nie zostanie wskazany URL do strony podsumowania, proces płatności zakończy się na stronie, na której wyświetlony został przycisk SkyCashClick. Merchant wraz z powiadomieniem o dokonaniu płatności (CallBackURL opisany w kolejnych rozdziałach) otrzymuje dane adresowe do wysyłki, w związku z tym nie jest wymagane wprowadzanie danych do wysyłki na stronach sklepu, tym bardziej rejestracja użytkownika w sklepie Merchanta. Każdy potencjalny użytkownik SkyCash może zostać jednym kliknięciem klientem sklepu. Więcej informacji na temat usługi, przykłady zastosowania, wraz z generatorem kodu do osadzenia na stronie, znajdziecie Państwo na dedykowanym portalu: http://skycashclick.com Niniejszy dokument opisuje techniczne aspekty związane z integracją rozwiązania na stronie Merchanta. SkyCash 3/6
2. Osadzenie przycisku SkyCashClick Niniejszy rozdział zawiera wszystkie aspekty związane z osadzeniem kodu generującego przycisk SkyCashClick na stronie sklepu oraz z powiadomieniem o dokonaniu transakcji (CallBackURL). Integralnym elementem mechanizmu, również opisanym w niniejszym rozdziale jest opcjonalny, lecz zalecany mechanizm weryfikacji znacznika transakcji. 2.1. Parametry transakcji Widget, aby spełniał swoją rolę musi zawierać niezbędne do zidentyfikowania Merchanta i samej transakcji parametry: amount kwota transakcji currency waluta transakcji (standardowo PLN) to numer merchanta transid identyfikator transakcji detailslink (opcjonalny) URL strony będącej podsumowaniem transakcji (w formacie RAW URL) hash (opcjonalny) znacznik parametrów transakcji (opisany w kolejnym podrozdziale) Sposób osadzenia parametrów w kodzie widgetu przedstawiony został na dedykowanym usłudze portalu (link we wstępnie), na którym Merchant znajdzie również generator kodu widgetu w oparciu o dostarczone parametry transakcji. W przypadku automatycznego osadzania parametrów transakcji przez programistów sklepu internetowego, należy zwrócić uwagę na szczególny parametr, jakim jest hash. Parametr ten jest zabezpieczeniem przed nieautoryzowaną próbą zmiany parametrów transakcji i zalecane jest jego wykorzystanie w procesie osadzenia widgetu na stronie. 2.2. Weryfikacja znacznika parametrów transakcji System będzie weryfikował parametr hash tylko w przypadku, w którym Merchant w panelu transakcyjnym SkyCash aktywował opcję znacznik parametrów, a co za tym idzie wprowadził klucz znacznika parametrów (parametr wspólny dla metod: PayLink oraz SkyCashClick ). Poniżej przedstawiono algorytm wyliczania parametru hash dla metody SkyCashClick. hash = md5 (amount.to.transtid.key) Objaśnienia: znak. oznacza konkatenację parametr key ustala Sprzedawca w procesie aktywacji mechanizmu w Panelu Merchanta pozostałe parametry, to opisane powyżej składniki widgetu, które należy połączyć zgodnie z podaną kolejnością Przykład: Przy założeniu następujących parametrów transakcji: amount = 30.20 to = 118118 transid = 121212 SkyCash 4/6
Przy założeniu, że klucz ma postać: key = 1234567890qwer Zgodnie z algorytmem (kolorami odróżnione zostały poszczególne parametry): hash = md5 ( 30.201181181212121234567890qwer ) Znacznik będzie miał postać: hash = 4e0de38553203b5aa9d7b7c7c88f8cdb 2.3. Powiadomienie o dokonaniu płatności System SkyCash umożliwia Merchantom zdefiniowanie adresu URL na który wysyłane będzie każdorazowo powiadomienie o dokonaniu płatności przez użytkownika. CallBackURL należy zdefiniować w Panelu Transakcyjnym w zakładce o nazwie Callbackurl i zatwierdzić PINem. Powiadomienie o dokonaniu płatności na konto merchanta oznacza wywołanie zdefiniowanego URLa z poniższymi parametrami przekazywanymi metodą GET: a) timestamp Znacznik czasu, kiedy płatność została dokonana. Jego wartość określona jest zgodnie z konwencją pochodzącą z systemu Unix i bibliotek systemowych Javy jako różnica mierzona w milisekundach pomiędzy aktualnym czasem a północą 1 stycznia 1970 roku (wg UTC). b) message Opis transakcji widoczny przez użytkownika w historii transakcji. SKYCASH CLICK CODE:Rub931 OSOBA: Jan Kowalski Zurawia 32/34 00-515 Warszawa NUMER TRANSAKCJI:121212 c) to Identyfikator konta Odbiorcy w systemie SkyCash. d) amount Kwota transakcji. e) ref Numer referencyjny transakcji wygenerowany przez SkyCash. f) cmessage Parametr zawierający identyfikator transakcji oraz dane do wysyłki. Dla SkyCashClick będzie on przyjmował następujący format: SkyCashClick CLICK:kiss911 NAME:Jan Kowalski ULICA:Zurawia 32/34 KOD:00-515 MIASTO:Warszawa g) from Identyfikator SkyCash klienta, czyli numer telefonu komórkowego, z ukrytymi czterema ostatnimi cyframi. h) currency Oznaczenie waluty transakcji, aktualnie tylko PLN. i) signed Elektroniczny podpis umożliwiający weryfikację autentyczności parametrów SkyCash 5/6
URL'a zwrotnego (algorytm SHA256withRSA). Powiadomienia generowane są do momentu, w którym serwer Sprzedawcy zwróci w nagłówku HTTP status 200, czyli OK. W przypadku braku odpowiedzi lub innego statusu HTTP System będzie w ciągu 24 godzin ponawiał powiadomienia w odstępie 10 minut. W przypadku, w którym w zadanym czasie żadne wywołanie nie zakończy się powodzeniem, z systemu SkyCash zostanie wysłana wiadomość e-mail, informującą o tym fakcie, zarówno do Sprzedawcy jak i do klienta, który dokonał płatności, celem odpowiedniej reakcji na zaistniałą sytuację. Uwaga: Sprzedawca powinien być zatem przygotowany do wielokrotnej obsługi zgłoszeń http GET dotyczących tego samego zamówienia, które może jednoznacznie zidentyfikować przy pomocy parametrów 'cmessage' oraz numeru referencyjnego płatności w parametrze 'ref'. 2.4. Weryfikacja płatności Sprzedawca powinien dodatkowo zweryfikować transakcję zarówno pod kątem jej zaksięgowania w systemie SkyCash jak i wartości parametrów płatniczych takich jak kwota transakcji, identyfikator produktu, użytkownika, itp. SkyCash podpisuje cyfrowo zawartość URL'a zwrotnego i dołącza podpis do jego parametrów. Weryfikacji można dokonać korzystając z usługi udostępnianej przez SkyCash pod adresem: https://mars.skycash.com/paylinkv Celem weryfikacji transakcji należy wywołać ww. URL wraz z parametrami otrzymanymi wraz ze zwrotnym URL'em. W przypadku prawidłowego podpisu, zwrócona zostanie wartość: 'verified', w przeciwnym przypadku: 'notok'. Poniżej przedstawiony został przykładowy URL weryfikujący płatność: https://mars.skycash.com/paylinkv?timestamp=1260189962334&message=skycash%20click%20code:rub931%20o SOBA:%20Jan%20Kowalski%20Zurawia%2032/34%2000-515%20Warszawa%20NUMER%20TRANSAKCJI:121212&to=118118&amount=60.05¤cy=PLN& ref=1000110000000572864&cmessage=skycashclick%20click:kiss91%20name:jan%20kowalski%20ulica:zurawia%2 032/34%20KOD:00-515%20MIASTO:Warszawa&from&signed=JfyYgGhwQuMV1f3rgo......kxHlLEQzgMQ== SkyCash 6/6