Dokument zawiera specyfikację techniczną instalacji systemu płatności Przelewy24.

Transkrypt

1 Przelewy24 Specyfikacja techniczna instalacji Data: Wersja: 3.1 Dokument zawiera specyfikację techniczną instalacji systemu płatności Przelewy24. Strona 1 z 12

2 1 Przebieg transakcji Operacje po stronie Sprzedawcy Operacje w Przelewy24 1. W swoim serwisie przygotowujesz stronę, na której zawarta będzie lista zakupów klienta i ostateczna cena, którą należy zapłacić. 2. Przygotowane odpowiednio żądanie transakcji przesyłasz do serwisu Przelewy Klient wybiera formę płatności i dokonuje niezbędnych operacji. 4. Klient dokonuje płatności zgodnie z przedstawioną instrukcją. 5. System weryfikuje dokonanie przelewu, informuje o wyniku klienta i wysyła odpowiedź zwrotną na podany przez Ciebie adres URL. Odpowiedź zwrotną (pozytywną lub negatywną) otrzymasz w czasie nie dłuższym niż 15 minut. 6. Po odebraniu odpowiedzi z nadanym numerem transakcji, musisz ją ostatecznie zweryfikować wysyłając odpowiednie dane do skryptu weryfikującego w serwisie Przelewy Skrypt serwisu Przelewy24 generuje odpowiedź z wynikiem na podstawie otrzymanych danych. Jeżeli transakcja była poprawna, w tym momencie jest ona uznawana za zakończoną. 8. Transakcja zakończona. 2 Terminologia Sprzedawca - instytucja lub osoba prywatna korzystająca z usług serwisu PRZELEWY24 Identyfikator sesji - unikalny identyfikator służący do weryfikacji danych pojedynczej transakcji. Identyfikator ten pobierany jest od sprzedawcy. 3 Oprogramowanie Aby prawidłowo przeprowadzić transakcję sprzedawca na swoich stronach WWW musi wprowadzić niżej opisaną obsługę wysyłania żądania transakcji oraz odbiór odpowiedzi poprawnej i błędnej. Strona 2 z 12

3 4 Transakcja 4.1 Rejestracja transakcji Przed wysłaniem żądania transakcji należy zapisać jej dane do lokalnej bazy danych sprzedawcy. W szczególności należy zachować informacje o identyfikatorze sesji i kwocie transakcji. Żądanie transakcji należy przesłać ze stron sprzedawcy przy pomocy formularza wykonując operację POST. Adres URL, pod który należy wysłać formularz jest następujący: Adres URL: Parametry POST transakcji: Nazwa pola Typ Wymagane Opis p24_merchant_id INT T ID sprzedawcy p24_pos_id INT T ID sprzedawcy p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123) p24_currency STRING(3) T PLN, EUR, GBP, CZK p24_description STRING(1024) T Opis transakcji p24_ STRING(50) T Klienta p24_client STRING(50) N** Imię i nazwisko Klienta p24_address STRING(80) N** Adres Klienta p24_zip STRING(10) N** Kod pocztowy Klienta p24_city STRING(50) N** Miasto Klienta p24_country STRING(2) T Kody krajów zgodnie z punktem 7.5 p24_phone STRING(12) N Telefon klienta w formacie: p24_language STRING(2) N pl / en / de / es / it p24_method INT N Lista metod płatności widoczna w panelu lub dostępna przez API (patrz pkt. 5) p24_url_return STRING(250) T Adres powrotny po zakończeniu transakcji (w tym status transakcji) Strona 3 z 12

4 p24_url_cancel STRING(250) T Adres powrotny w przypadku rezygnacji / wystąpienia błędu p24_url_status * STRING(250) N Adres do przekazania statusu transakcji p24_time_limit * INT N Limit czasu na wykonanie transakcji, 0 - brak limitu, maks. 99(w minutach) p24_wait_for_result * INT N 0 - nie 1 - tak p24_channel * INT N 1 - karty, 2 - przelewy, 4 - przelew tradycyjny, 8 N/A 16 - wszystkie 24/7, 32 - użyj przedpłatę p24_shipping INT N Koszt dostawy/wysyłki/etc p24_transfer_label * STRING(20) N Opis pojawiający się w tytule przelewu 1 p24_api_version STRING(5) T 3.1 Lista zakupów, gdzie X jest liczbą (opcjonalne 2 ) p24_name_x STRING(127) T Nazwa towaru p24_description_x STRING(127) N Dodatkowy opis towaru p24_quantity_x INT T Ilość sztuk towaru p24_price_x INT T Cena jednostkowa towaru p24_number_x INT N ID towaru w systemie sprzedawcy p24_sign STRING(100) T Suma kontrolna wyliczana wg opisu poniżej. (patrz pkt. 7.1) p24_encoding STRING(15) N System kodowania przesyłanych znaków: ISO , UTF-8, Windows-1250 * - dostępne w wersji 3.2. Zalecamy wdrożenie parametrów które będą dla Państwa użyteczne, ponieważ wraz z wejściem dokumentacji 3.2 integracja nie będzie wymagała modyfikacji. ** - pola wymagane dla płatności kartami płatniczymi, PayPal, FerBuy. 1 Dodatkowy opis nie pojawia się we wszystkich metodach płatności 2 Wymagane dla PayPal Protected Payment, systemów ratalnych Strona 4 z 12

5 Zwrotnie wyświetli się TOKEN którego należy użyć do przejścia do panelu transakcyjnego. Przykładowy kod HTML takiego formularza jest następujący: <form action=" method="post" class="form"> <input type="text" name="p24_session_id" value="session_id" /> <input type="text" name="p24_merchant_id" value="twój ID_SPRZEDAWCY" /> <input type="text" name="p24_pos_id" value="twój ID_SPRZEDAWCY" /> <input type="text" name="p24_amount" value="kwota W WALUTA/100" /> <input type="text" name="p24_currency" value="pln" /> <input type="text" name="p24_description" value="tytuł" /> <input type="text" name="p24_client" value="jan Kowalski" /> <input type="text" name="p24_address" value="ul. Polska 33/33" /> <input type="text" name="p24_zip" value="66-777" /> <input type="text" name="p24_city" value="poznań" /> <input type="text" name="p24_country" value="pl" /> <input type="text" name="p24_ " value=" @host.pl" /> <input type="text" name="p24_language" value="pl" /> <input type="text" name="p24_url_return" value=" /> <input type="text" name="p24_url_cancel" value=" /> <input type="text" name="p24_api_version" value="3.1" /> <input type="hidden" name="p24_sign" value="e2c43dec c518e1f514d3b434b" /> <input name="submit_send" value="wyślij" type="submit" /> </form> 4.2 Przejście do panelu transakcyjnego Adres URL: gdzie {TOKEN} został pobrany w wyniku zarejestrowania transakcji (patrz p. 4.1) 4.3 Przejście z pominięciem rejestracji transakcji Adres URL: Parametry wysyłane metodą POST analogicznie do rejestracji transakcji. 4.4 Odbiór wyniku transakcji W zależności od wyniku transakcji wywołany zostanie jeden z przekazanych do systemu Przelewy24.pl adres url: Transakcja błędna Wywołany adres url: p24_url_cancel. Takie wywołanie może nastąpić w dwóch przypadkach. Gdy transakcja zostaje anulowana przez klienta lub minie czas oczekiwania na wynik transakcji (standardowo 15 min od dokumentacji 3.2 będzie ustawiane parametrem wejściowym p24_time_limit). Transakcja prawidłowa Wywołany adres url: p24_url_return. Wywołanie następuje gdy nastąpiła prawidłowa wpłata przez klienta. Strona 5 z 12

6 Parametry POST wywołania: p24_merchant_id INT ID Sprzedawcy p24_pos_id INT ID Sprzedawcy p24_session_id STRING(100) Unikalny identyfikator z systemu sprzedawcy p24_amount INT Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123) p24_currency STRING(3) PLN, EUR, GBP, CZK p24_order_id INT Numer transakcji nadany przez Przelewy24 p24_method INT Metoda płatności użyta przez klienta p24_sign STRING Suma kontrolna wyliczana wg opisu poniżej (patrz pkt. 7.1) z pól: p24_session_id, p24_order_id, p24_amount,p24_currency i pola Klucz CRC 4.5 Weryfikacja otrzymanego wyniku transakcji Po odebraniu, skrypt musi wykonać dodatkową operację mającą na celu potwierdzenie autentyczności odpowiedzi. Operacja ta polega na wywołaniu odpowiedniego skryptu serwisu Przelewy24.pl. Adres URL: Parametry POST wywołania: p24_merchant_id INT ID sprzedawcy p24_pos_id INT ID sprzedawcy p24_session_id STRING(100) Unikalny identyfikator z systemu sprzedawcy p24_amount INT Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123 wcześniej zapisana nie uzyskana z wyniku transakcji z Przelewy24.pl) p24_currency STRING(3) PLN, EUR, GBP, CZK p24_order_id INT Numer transakcji nadany przez Przelewy24 p24_sign STRING Suma kontrolna wyliczana wg opisu poniżej (patrz pkt. 7.1) z pól: p24_session_id, p24_order_id, p24_amount, p24_currency i pola Klucz CRC. Strona 6 z 12

7 W odpowiedzi serwis przekazuje stan danej transakcji. Jeżeli transakcja jest prawidłowa pojawi się komunikat : Content-Type: text/plain RESULT TRUE w przeciwnym wypadku pojawią się informacje: Content-Type: text/plain RESULT ERR kod błędu opis błędu Poszczególne linie odpowiedzi oddzielone są sekwencją dwóch bajtów: CR=0x0D i następującym po nim LF=0x0A. Kody błędu opisane poniżej (patrz pkt. 7.4). Ważne! Transakcja zostaje uznana za potwierdzoną po jej weryfikacji. Jeżeli klient dokona transakcji, wróci na strony sprzedawcy, ale sprzedawca nie zweryfikuje transakcji, dana kwota nie zostanie przekazana sprzedawcy ani uwzględniona w rozliczeniach. Pozostanie ona do dyspozycji klienta w formie przedpłaty. Przykładowa funkcja obsługująca weryfikację transakcji z wykorzystaniem protokołu SSL wygląda następująco (wymagana obsługa biblioteki CURL): function p24_weryfikuj($p24_merchant_id, $p24_session_id, $p24_order_id, $p24_amount, $p24_currency) { $P = array(); $RET = array(); $url = " $P[] = "p24_merchant_id=".$p24_merchant_id; $P[] = "p24_pos_id=".$p24_merchant_id; $P[] = "p24_session_id=".$p24_session_id; $P[] = "p24_order_id=".$p24_order_id; $P[] = "p24_amount=".$p24_amount; $P[] = "p24_currency=".$p24_currency; $P[] = "p24_sign=".md5($p24_session_id." ". $p24_order_id." ". $p24_amount." ".$p24_currency." abc1def2"); $user_agent = "Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)"; $ch = curl_init(); curl_setopt($ch, CURLOPT_POST,1); if(count($p)) curl_setopt($ch, CURLOPT_POSTFIELDS,join("&",$P)); curl_setopt($ch, CURLOPT_URL,$url); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2); curl_setopt($ch, CURLOPT_USERAGENT, $user_agent); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); $result=curl_exec ($ch); curl_close ($ch); $T = explode(chr(13).chr(10),$result); $res = false; foreach($t as $line){ $line = ereg_replace("[\n\r]","",$line); if($line!= "RESULT" and!$res) continue; if($res) $RET[] = $line; Strona 7 z 12

8 } else $res = true; } return $RET; $session_id = $_POST["p24_session_id"]; $order_id = $_POST["p24_order_id"]; $id_merchant = 99999; // TWÓJ ID SPRZEDAWCY $amount = 123; // WYNIK POBRANY Z TWOJEJ BAZY (w WALUTA/100) $WYNIK = p24_weryfikuj($id_merchant,$session_id, $order_id, $amount); if($wynik[0] == "TRUE") { // transakcja prawidłowa }else { // transakcja błędna // $WYNIK[1] - kod błędu // $WYNIK[2] - opis } 4.6 Automatyczne przekazywanie wyniku transakcji W sytuacji, gdy z pewnych przyczyn wynik transakcji nie zostanie przekazany do sprzedawcy w określonym czasie (np. informacja o wpłacie pojawi się po 15 minutach, klient zamknie przedwcześnie przeglądarkę lub w wyniku problemów w komunikacji wynik nie zostanie poprawnie odebrany) istnieje możliwość automatycznego przekazania wyniku transakcji dokonanej przez klienta. System, gdy wykryje transakcję prawidłową, której wynik nie został w ciągu 15 minut zweryfikowany przez sprzedawcę (potwierdzony odbiór) może wysyłać ten wynik przekazując przez POST parametry : p24_merchant_id INT ID sprzedawcy p24_pos_id INT ID sprzedawcy p24_session_id STRING(100) Unikalny identyfikator z systemu sprzedawcy p24_amount INT Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123 wcześniej zapisana nie uzyskana z wyniku transakcji z Przelewy24.pl) p24_currency STRING(3) PLN, EUR, GBP, CZK p24_order_id INT Numer transakcji nadany przez Przelewy24 p24_sign STRING Suma kontrolna wyliczana wg opisu poniżej (patrz pkt. 7.1) z pól: p24_session_id, p24_order_id, p24_amount, p24_currency i pola Klucz CRC. Ważne jest, że przy korzystaniu z tego rozszerzenia należy przewidzieć w swoim systemie sytuację, w której pomimo otrzymania w czasie przeznaczonym dla klienta (15 minut) wyniku z błędem, możliwe będzie ponowne przyjęcie wyniku dla tej samej transakcji, tym razem prawidłowej. Dzieje się tak w sytuacji, gdy wpłata nadeszła po 15 minutach od żądania Strona 8 z 12

9 transakcji. W takim przypadku Państwa system powinien zastąpić w swojej bazie informację o błędzie dla danej transakcji informacją o wyniku poprawnym. Aby skorzystać z tego rozszerzenia należy przygotować odpowiedni skrypt, który poprawnie odbierze i zweryfikuje wynik. Następnie należy ten skrypt umieścić na swoim serwerze i przesłać na adres serwis@przelewy24.pl dokładny adres URL do tego skryptu. Skrypt może być zabezpieczony protokołem SSL. Ważne, by skrypt ten był uniwersalny dla wszystkich transakcji. Okres jaki zalecamy oczekiwać na wynik, czyli przechowywać zamówienia nie zapłacone w Państwa bazie danych, to minimum 14 dni. Wpłaty dokonane po tym czasie będą traktowane, albo jako przedpłaty do ponownego wykorzystania, albo zostaną zwrócone. Czas oczekiwania jest zależny od specyfiki Państwa systemu i ustala się go ignorując przesyłane z Przelewy24.pl wyniki dla transakcji, których data wygenerowania jest starsza od przyjętego. Z punktu widzenia systemu Przelewy24.pl czas ten może być dowolny. 4.7 Cykl powiadamiania o wpłacie System przewiduje 5-krotne powiadomienie systemu Sprzedawcy o wpłacie Klienta. Powiadomienia wysyłane są w podanych poniżej odstępach czasu z tolerancją +/- 5 minut. Powiadomienia wysyłane są w następujących odstępach: 15, 30, 60, 150 i 450 minut, po upłynięciu czasu na dokonanie wpłaty przez Klienta ( 15 min ). 5 Usługi webservices Adres serwera WebServices Przelewy24: Encoded: Literal: Dokumentacja do pobrania ze strony 6 Środowisko testowe Podczas implementowania mechanizmów w Twoim systemie możesz skorzystać ze środowiska testowego. Środowisko to umożliwia zweryfikowanie poprawności instalacji bez konieczności dokonywania przelewów. Adresy URL do połączeń do środowiska testowego: - założenie konta testowego i wgląd do panelu - żądanie transakcji testowej - adres weryfikacji wyniku transakcji Transakcje testowe będą widoczne w panelu testowym. Strona 9 z 12

10 W środowisku testowym każda transakcja zostaje automatycznie uznana za prawidłową. Aby przetestować transakcję błędną przygotowane zostało pięć przypadków najczęściej pojawiających się w systemie. Aby przetestować konkretny przypadek w polu p24_description należy umieścić jeden z poniższych tekstów: TEST_ERR04, TEST_ERR54, TEST_ERR102, TEST_ERR103 lub TEST_ERR110. Środowisko testowe nie może być wykorzystywane do realizacji transakcji produkcyjnych. 7 Informacje dodatkowe 7.1 Pole p24_sign Celem dodatkowej weryfikacji danych formularza przesyłanego do serwisu Przelewy24 udostępnione jest pole p24_sign. Pole to ma na celu weryfikację, czy parametry wejściowe są prawidłowe i nie zostały zmodyfikowane. W panelu transakcyjnym, w zakładce Moje dane jest ciąg o nazwie Klucz do CRC. Wartość z tego pola (16 znaków alfanumerycznych) jest potrzebna do obliczania sumy kontrolnej. Sumę kontrolną p24_sign obliczamy wg poniższego wzoru: p24_sign => to wartość funkcji MD5 z połączonych ze sobą pól: p24_session_id, p24_merchant_id, p24_amount,p24_currency oraz klucza CRC. Łącznikiem pól jest znak. Przykład: md5 dla ciągu: abcdefghijk PLN a123b456c789d012 wynosi: 6c7f0bb62c046fbc89921dc3b2b23ede UWAGA: Dla danych wejściowych i podczas weryfikacji obliczane p24_sign jest z innych pól. 7.2 Adresy IP serwerów Zalecamy zabezpieczenie skryptów przed podejrzanymi wywołaniami, stosując filtrację adresów IP dla przychodzących połączeń. Zakresy IP serwerów Przelewy24 to: Kody błędów err00 err01 err02 Nieprawidłowe wywołanie skryptu Nie uzyskano od sklepu potwierdzenia odebrania odpowiedzi autoryzacyjnej Nie uzyskano odpowiedzi autoryzacyjnej Strona 10 z 12

11 err03 err04 err05 err06 err07 err08 err09 err10 err49 err51 err52 To zapytanie było już przetwarzane Zapytanie autoryzacyjne niekompletne lub niepoprawne Nie udało się odczytać konfiguracji sklepu internetowego Nieudany zapis zapytania autoryzacyjnego Inna osoba dokonuje płatności Nieustalony status połączenia ze sklepem. Przekroczono dozwoloną liczbę poprawek danych. Nieprawidłowa kwota transakcji! Zbyt wysoki wynik oceny ryzyka transakcji. Nieprawidłowe wywołanie strony Błędna informacja zwrotna o sesji! err53 Błąd transakcji! err54 err55 err56 err57 err58 err59 Niezgodność kwoty transakcji! Nieprawidłowy kod odpowiedzi! Nieprawidłowa karta Niezgodność flagi TEST! Nieprawidłowy numer sekwencji! Nieprawidłowa waluta transakcji! err101 Błąd wywołania strony W żądaniu transakcji brakuje któregoś z wymaganych parametrów lub pojawiła się niedopuszczalna wartość. err102 Minął czas na dokonanie transakcji err103 Nieprawidłowa kwota przelewu err104 Transakcja oczekuje na potwierdzenie. err105 Transakcja dokonana po dopuszczalnym czasie err161 Żądanie transakcji przerwane przez użytkownika Klient przerwał procedurę płatności wybierając przycisk "Powrót" na stronie wyboru formy płatności. err162 Żądanie transakcji przerwane przez użytkownika Klient przerwał procedurę płatności wybierając przycisk "Rezygnuj" na stronie z instrukcją płatności. Strona 11 z 12

12 7.4 Kody krajów Andora AD Norwegia NO Austria AT Polska PL Belgia BE Portugalia PT Cypr CY San Marino SM Czechy CZ Słowacja SK Dania DK Słowenia SI Estonia EE Szwajcaria CH Finlandia FI Szwecja SE Francja FR Węgry HU Grecja EL Wielka Brytania GB Hiszpania ES Włochy IT Holandia NL USA US Irlandia IE Kanada CA Islandia IS Japonia JP Litwa LT Ukraina UA Łotwa LV Białoruś BY Luxemburg LU Rosja RU Malta MT Załącznik nr 1 Historia zmian Data Autor Uwagi Opracowanie dokumentu Aktualizacja opisów, dodanie kodów błędów i kodów krajów Strona 12 z 12