Specyfikacja 1.2.1 Płatności CashBill Instrukcja podłączenia płatności elektronicznych do typowych zastosowań. CashBill Spółka Akcyjna ul. Rejtana 20, 41-300 Dąbrowa Górnicza Tel.: +48 032 764-18-42 Fax: +48 032 764-18-40 Infolinia: 0 801 011 802 e-mail: marketing@cashbill.pl NIP: 629-241-08-01 KRS: 0000323297 REGON: 241048572 kapitał zakładowy 5 000 000 zł opłacony w całości
Spis treści 1 Sklep internetowy... 3 1.1 Procedura uruchomienia usługi...3 1.2 Proces autoryzacji nowej transakcji...4 1.3 Odebranie potwierdzenia... 6 1.4 Procedura testowa... 8 2 Kody Dostępu Automatyczne... 8 2.1 Procedura uruchomienia usługi...9 2.2 Proces autoryzacji nowej transakcji...9 2.3 Opis metody sprawdzenia poprawności kodu...10 3 Kody Dostępu Obsługowe...11 3.1 Procedura uruchomienia usługi...11 3.2 Proces autoryzacji nowej transakcji...12 4 Historia zmian... 13 2
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 e-mailowego 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 e-mail, 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
1.2 Proces autoryzacji nowej transakcji Punkt rozpoczyna proces autoryzacji transakcji poprzez przekierowanie przeglądarki klienta z określonymi danymi na adres: https://www.cashbill.pl/cblite/pay.php 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
Nazwa u forname surname email tel street street_n1 street_n2 city postcode country Opis imię nazwisko adres e-mail 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 + email + 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
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
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
Powiadomienie na wskazany adres e-mail Zmiana status transakcji sygnalizowana może być również poprzez wysłanie wiadomości na przypisany dla punktu płatności adres e-mail. Potwierdzenia takie wysyłane są przez CashBill w przypadku podania adresu e-mail w konfiguracji punktu płatności (Adres emailowego 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
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 emailowego 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 email, 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: https://www.cashbill.pl/cblite/paycode.php?id=identyfikator_punktu gdzie: Kody Dostępu Automatyczne 9
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 e-mail 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: http://www.cashbill.pl/cblite/backcode_check.php 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
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 e-mailowego 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 e-mail, 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
3.2 Proces autoryzacji nowej transakcji Punkt rozpoczyna proces autoryzacji transakcji poprzez przekierowanie przeglądarki klienta z określonymi danymi na adres: https://www.cashbill.pl/cblite/paycode.php?id=identyfikator_punktu 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 e-mail kolejny z wygenerowanych w panelu systemu CashBill kodów dostępowych do serwisu. Kody Dostępu Obsługowe 12
4 Historia zmian data wersja zmiany 13.11.2012 1.2.1 Aktualizacja szaty graficznej dokumentu 16.08.2012 1.2 Ujednolicenie dokumentacji 21.05.2009 1.1 Procedury testowe Kody obsługowe i automatyczne 08.05.2009 1.0 Utworzenie dokumentu Historia zmian 13