Specyfikacja Płatności CashBill. Instrukcja podłączenia płatności elektronicznych do typowych zastosowań.

Transkrypt

1 Specyfikacja Płatności CashBill Instrukcja podłączenia płatności elektronicznych do typowych zastosowań. CashBill Spółka Akcyjna ul. Rejtana 20, Dąbrowa Górnicza Tel.: Fax: Infolinia: marketing@cashbill.pl NIP: KRS: REGON: kapitał zakładowy zł opłacony w całości

2 Spis treści 1 Sklep internetowy Procedura uruchomienia usługi Proces autoryzacji nowej transakcji Odebranie potwierdzenia Procedura testowa Kody Dostępu Automatyczne Procedura uruchomienia usługi Proces autoryzacji nowej transakcji Opis metody sprawdzenia poprawności kodu Kody Dostępu Obsługowe Procedura uruchomienia usługi Proces autoryzacji nowej transakcji Historia zmian

3 1 Sklep internetowy Usługa umożliwiająca wdrożenie płatności elektronicznych tak, by właściciel strony www mógł bez przeszkód pobrać ustaloną przez siebie kwotę od klienta. Ten rodzaj punktu płatności skierowany jest, więc głównie do właścicieli sklepów internetowych, nie oznacza to jednak, że usługi nie można dostosować do dowolnego, indywidualnego projektu i rozwiązania punktu płatności w Internecie. Rozwiązanie do zastosowania również na witrynach o charakterze dostępowym. 1.1 Procedura uruchomienia usługi Zakładanie nowego Punktu Płatności polega na wypełnieniu formularza dostępnego w systemie CashBill w zakładce Płatności Internetowe/Dodaj nowy Punkt Płatności. W celu uruchomienia usługi płatności w systemie CashBill należy uzupełnić następujące dane: Nazwa punktu płatności Opis punktu płatności Adres powrotu przeglądarki Adres serwerowego potwierdzenia transakcji Adres owego potwierdzenia transakcji Wewnętrzna nazwa niewidoczna dla płacącego Opis towaru lub usługi jakiej dotyczy transakcja Adres URL, na który zostanie przekierowana przeglądarka klienta po sfinalizowaniu transakcji Adres URL, na który system CashBill odsyła dane dotyczące procesu autoryzacji transakcji kanałem serwer-serwer Adres , na który system CashBill wyśle powiadomienie dotyczące zmiany statusu transakcji Po założeniu usługi, udostępnione zostaną niezbędne do uruchomienia informacje: Identyfikator punktu Tajny klucz do podpisu transakcji Unikalny w skali systemu identyfikator punktu Tajny klucz znany tylko systemowi CashBill oraz punktowi płatności, służący do zapewnienia wiarygodności danych wysyłanych i odbieranych przez punkt płatności Sklep internetowy 3

4 1.2 Proces autoryzacji nowej transakcji Punkt rozpoczyna proces autoryzacji transakcji poprzez przekierowanie przeglądarki klienta z określonymi danymi na adres: Dane używane w procesie autoryzacji transakcji (wysyłane metodą POST): transakcji): Dane identyfikujące transakcję (dane te są wymagane w procesie autoryzacji Nazwa u Opis Wymagane / wartość domyślna id Identyfikator konta użytkownika w systemie CashBill T service Identyfikator Punktu Płatności nadany w procesie tworzenia T amount Kwota transakcji, separator dziesiętny:. (kropka) T desc Opis transakcji T op Operator płatności N / brak lang Język interfejsu ( PL EN) N / PL userdata Dane dodatkowe T sign Podpis wysyłanych danych (patrz poniżej) T Dane identyfikujące klienta (dane te są opcjonalne, ich wysłanie spowoduje wypełnienie odpowiednich pól w formularzu autoryzacyjnym): Sklep internetowy 4

5 Nazwa u forname surname tel street street_n1 street_n2 city postcode country Opis imię nazwisko adres telefon adres zamieszkania (ulica) adres zamieszkania (numer domu) adres zamieszkania (numer mieszkania) adres zamieszkania (miasto) adres zamieszkania (kod pocztowy) adres zamieszkania (kraj) Wzór na utworzenie podpisu wysyłanych danych: sign = md5 ( id + service + amount + desc + op + lang + userdata + forname + surname + + tel + street + street_n1 + street_n2 + city + postcode + country + key ) Oznaczenia: symbol md5 znaczenie funkcja skrótu MD5 + operacja konkatenacji (łączenia) napisów (np.: aa + bb + c = aabbc) key tajny klucz punktu płatności Jeżeli wszystkie dane są prawidłowo przekazane do systemu CashBill, klientowi zostanie wyświetlona strona z wyborem metody płatności, jeżeli wprowadzone dane są błędne, w zależności od trybu uruchomionego punktu płatności, wyświetlona zostanie następująca informacja o błędzie: Sklep internetowy 5

6 tryb pracy Tryb produkcyjny punktu płatności Tryb testowy punktu płatności komunikat BŁĘDNE DANE WEJŚCIOWE BŁĘDNE DANE WEJŚCIOWE: KOMUNIKAT BŁĘDU Możliwe komunikaty błędu: Komunikat błędu no sysinfo invalid status invalid sign Opis Nieprawidłowy punktu płatności Punkt płatności jest zablokowany Nieprawidłowy podpis wysłanych danych invalid amount Nieprawidłowa kwota transakcji (kwota powinna być większa od 1 ) 1.3 Odebranie potwierdzenia Przekierowanie przeglądarki klienta Po dokonaniu transakcji następuje przekierowanie przeglądarki klienta na adres URL ustalony w procesie rejestracji. Dane przekazywane poprzez przeglądarkę klienta (wysyłane metodą GET): Nazwa u id service orderid Opis Identyfikator konta użytkownika w systemie CashBill Identyfikator punktu płatności Identyfikator transakcji w systemie CashBill amount Kwota transakcji, separator dziesiętny:. (kropka) userdata status key Dodatkowe dane przekazane w procesie autoryzacji nowej transakcji Status płatności ( ok err ) ok transakcja autoryzowana pozytywnie err transakcja autoryzowana negatywnie Podpis wysyłanych danych (patrz poniżej) Sklep internetowy 6

7 Wzór na utworzenie podpisu wysyłanych danych: sign = md5 ( id + service + orderid + amount + userdata + status + key ) Oznaczenia: symbol md5 znaczenie funkcja skrótu MD5 + operacja konkatenacji (łączenia) napisów (np.: aa + bb + c = aabbc) key tajny klucz punktu płatności UWAGA: dane te wysyłane są jedynie w celu informacyjnym oraz służą do identyfikacji transakcji. Główne sprawdzenie poprawności musi odbywać się podczas odebrania danych poprzez kanał serwer-serwer. Powiadomienie kanałem serwer-serwer Na adres podany w procesie rejestracji ( Adres serwerowego potwierdzenia transakcji) przesyłane są dane, zgodne z pkt. powyższym, metodą POST. Po odebraniu danych punkt winien wysłać odpowiedź o treści: OK Jakakolwiek inna odpowiedź będzie traktowana jako błąd odebrania potwierdzenia. Punkt płatności zobowiązany jest do sprawdzenia poprawności odebranego potwierdzenia poprzez porównanie otrzymanych danych z wcześniej wysyłanymi ( dotyczy pól id, service oraz amount ), sprawdzenia statusu procesu autoryzacji ( pole status ) oraz weryfikacji poprawności podpisu ( pole sign ). Należy również zwrócić uwagę czy transakcja nie była już obsłużona przez punkt (czy transakcja o identycznym identyfikatorze (pole orderid) nie była już wysyłana do punktu). Sklep internetowy 7

8 Powiadomienie na wskazany adres Zmiana status transakcji sygnalizowana może być również poprzez wysłanie wiadomości na przypisany dla punktu płatności adres . Potwierdzenia takie wysyłane są przez CashBill w przypadku podania adresu w konfiguracji punktu płatności (Adres owego potwierdzenia transakcji). 1.4 Procedura testowa Aby umożliwić przetestowanie założonego punktu płatności należy w konfiguracji punktu płatności aktywować tryb testowy. Tryb testowy domyślnie jest wyłączony. W momencie, gdy aktywowany jest tryb testowy dla punktu płatności, udostępniany jest testowy operator płatności (możliwość dokonania transakcji bez fizycznego przelewu środków) oraz wyświetlane są rozszerzone komunikaty błędów dla błędnie podanych ów autoryzacyjnych transakcji. Cała procedura autoryzacji transakcji w trybie testowym nie zmienia się. W produkcyjnym wykorzystaniu punktu płatności należy, ze względów bezpieczeństwa, WYŁĄCZYĆ tryb testowy 2 Kody Dostępu Automatyczne Usługa Punktu Płatności, Kody Dostępu Automatyczne daje możliwość pozyskania płatnego dostępu do witryny www o ustalonej wartości i czasie ważności. Obsługa i weryfikacja kodów leży po stronie systemu CashBill. Udostępniany jest gotowy skrypt do umieszczenia na serwis internetowym, niezbędny do weryfikacji poprawności wpisywanego kodu dostępu. Kody Dostępu Automatyczne 8

9 2.1 Procedura uruchomienia usługi Zakładanie nowego Punktu Płatności polega na wypełnieniu formularza dostępnego w systemie CashBill w zakładce Płatności Internetowe/Dodaj nowy Punkt Płatności. W celu uruchomienia usługi płatności w systemie CashBill należy uzupełnić następujące dane: Nazwa punktu płatności Opis punktu płatności Adres powrotu przeglądarki Cena zakupu kodu Czas ważności kodu Adres owego potwierdzenia transakcji Wewnętrzna nazwa niewidoczna dla płacącego Opis towaru lub usługi jakiej dotyczy transakcja Adres URL, na który zostanie przekierowana przeglądarka klienta po sfinalizowaniu transakcji Koszt zakupu kodu wyrażony w kwocie brutto Okres ważności kodu (przedział czasowy od momentu aktywacji kodu) wyrażony w sekundach. W przypadku ustawienia czasu ważności na 0, przydzielony kod jest kodem jednorazowym Adres , na który system CashBill wyśle powiadomienie dotyczące zmiany statusu transakcji Po założeniu usługi, udostępnione zostaną niezbędne do uruchomienia informacje: identyfikator punktu Unikalny w skali systemu identyfikator punktu 2.2 Proces autoryzacji nowej transakcji Punkt rozpoczyna proces autoryzacji transakcji poprzez przekierowanie przeglądarki klienta z określonymi danymi na adres: gdzie: Kody Dostępu Automatyczne 9

10 identyfikator_punktu nadany w procesie tworzenia identyfikator punktu płatności Po pozytywnej autoryzacji transakcji klientowi zostanie wysłany na podany w procesie autoryzacji adres wygenerowany kod dostępu do serwisu. 2.3 Opis metody sprawdzenia poprawności kodu Aby sprawdzić poprawność wpisanego przez użytkownika serwisu kodu, należy wysłać zapytanie metodą GET na adres URL: podając odpowiednie y żądania. Parametry żądania: id check identyfikator punktu płatności wpisany przez użytkownika kod do sprawdzenia W odpowiedzi na tak wysłane żądanie możliwe są następujące odpowiedzi: ERROR Podany kod jest nieprawidłowy lub minął termin jego ważności Kody Dostępu Automatyczne 10

11 OK ilosc_sekund Podany kod jest prawidłowy i aktywny. Do końca ważności kodu pozostało ilosc_sekund sekund 3 Kody Dostępu Obsługowe Punkt Płatności, Kody Dostępu Obsługowe to usługa pozwalająca na realizację płatnego dostępu do serwisu www na zasadzie kodów. Właściciel usługi sam generuje paczki kodów w panelu systemu CashBill, a następnie obsługuje je po swojej stronie, weryfikując ich poprawność. 3.1 Procedura uruchomienia usługi Zakładanie nowego Punktu Płatności polega na wypełnieniu formularza dostępnego w systemie CashBill w zakładce Płatności Internetowe/Dodaj nowy Punkt Płatności. W celu uruchomienia usługi płatności w systemie CashBill należy uzupełnić następujące dane: Nazwa punktu płatności Opis punktu płatności Adres powrotu przeglądarki Cena zakupu kodu Adres owego potwierdzenia transakcji Wewnętrzna nazwa niewidoczna dla płacącego Opis towaru lub usługi jakiej dotyczy transakcja Adres URL, na który zostanie przekierowana przeglądarka klienta po sfinalizowaniu transakcji Koszt zakupu kodu wyrażony w kwocie brutto Adres , na który system CashBill wyśle powiadomienie dotyczące zmiany statusu transakcji Po założeniu usługi, udostępnione zostaną niezbędne do uruchomienia informacje: identyfikator punktu Unikalny w skali systemu identyfikator punktu Kody Dostępu Obsługowe 11

12 3.2 Proces autoryzacji nowej transakcji Punkt rozpoczyna proces autoryzacji transakcji poprzez przekierowanie przeglądarki klienta z określonymi danymi na adres: gdzie: identyfikator_punktu Nadany w procesie tworzenia identyfikator punktu płatności Po pozytywnej autoryzacji transakcji klientowi zostanie wysłany na podany w procesie autoryzacji adres kolejny z wygenerowanych w panelu systemu CashBill kodów dostępowych do serwisu. Kody Dostępu Obsługowe 12

13 4 Historia zmian data wersja zmiany Aktualizacja szaty graficznej dokumentu Ujednolicenie dokumentacji Procedury testowe Kody obsługowe i automatyczne Utworzenie dokumentu Historia zmian 13