Bezpieczne Zakupy - specyfikacja techniczna implementacji uproszczonej P OL C AR D is a regis t e r e d t ra d e ma rk o f FI R S T D AT A P O L S K A S. A., FI RS T D AT A P O L S K A S. A., Al. J e roz o l i ms k i e 9 2, 0 0-8 0 7 Wa r s z a wa, t e l. : +4 8 2 2 5 15 30 0 5, faks : + 48 22 5 1 5 30 98 www. firs tdata. pl Strona 1 z 8
Spis treści Strona 1. OMÓWIENIE PROCESU ZAPŁATY KARTĄ... 3 2. FORMULARZ SŁUŻĄCY DO PRZEJŚCIA NA STRONĘ POLCARDU... 4 3. SKRYPTY OBSŁUGUJĄCE ZGODĘ I ODMOWĘ... 6 4. SKRYPT DO OBSŁUGI BŁĘDÓW... 7 5. TABELA ZMIAN... 8 Strona 2 z 8
1. Omówienie procesu zapłaty kartą Klient po wybraniu towarów w sklepie internetowym, podaniu adresu wysyłki towarów, ustaleniu kwoty płatności i sposobu płatności (karta płatnicza) przechodzi na stronę autoryzacyjną FDP. Przejście na stronę FDP odbywa się ze strony sklepu internetowego zawierającej formularz zawierający pola określone dalej w tym dokumencie. Na stronie autoryzacyjnej FDP klient podaje numer karty, jej datę ważności, opcjonalnie kod CVV, oraz swoje dane. Po podaniu tych danych FDP przetwarza te dane i przesyła do banku wydawcy karty zapytanie autoryzacyjne o możliwość dokonania transakcji. Po uzyskaniu odpowiedzi FDP przesyła do przeglądarki klienta stronę z potwierdzeniem transakcji. Strona ta zawiera podstawowe informacje dotyczące transakcji, ale bez informacji o tym, czy bank udzielił zgody, czy odmowy dla dokonania transakcji. Na stronie tej znajduje się również przycisk kierujący przeglądarkę klienta do sklepu internetowego, pod jeden z dwóch uzgodnionych ze sklepem internetowym adresów, w zależności od tego, czy jest zgoda na dokonanie transakcji czy odmowa. W sytuacji kiedy podczas przetwarzania danych w FDP zostanie wykryty błąd, klient zostanie przekierowany pod trzeci z adresów uzgodnionych ze sklepem internetowym, służący sklepowi internetowemu do zakomunikowania klientowi wystąpienia błędu i zaproponowania dalszego postępowania. Implementacja rozwiązania po stronie sklepu internetowego składa się z trzech części: 1. Wykonanie formularza służącego do płatności 2. Przygotowanie stron obsługujących zgodę i odmowę 3. Wykonanie skryptu obsługującego błędy Strona 3 z 8
2. Formularz służący do przejścia na stronę FDP Na stronie z której następuje przejście do strony autoryzacyjnej FDP powinien znaleźć się formularz HTML, kierujący pod adres https://post.polcard.com.pl/cgi-bin/autoryzacja.cgi, metodą POST. Poniższa tabela przedstawia listę pól formularza. nazwa pola format opis pos_id order_id Alfanumeryczne, od 1 do 20 znaków Alfanumeryczne, od 1 do 20 znaków Identyfikator sklepu internetowego, otrzymany z FDP. Identyfikator zamówienia, nadawany przez sklep internetowy. amount od 1 do 10 cyfr Kwota transakcji wyrażona w groszach, np. dla transakcji na kwotę 123 zł 45 gr pole powinno mieć wartość 12345. test 1 znak: 'N' lub 'Y' Flaga określająca czy transakcja jest w trybie testowym (wartość 'Y') czy produkcyjnym ('N') language PL lub EN lub RU Określenie w jakim języku powinna otworzyć się strona autoryzacyjna FDP. Możliwe wartości to: PL,EN. client_ip np. 213.76.114.131 Numer IP komputera klienta z którego złożono zamówienie street Alfanumeryczne, 0 do 40 znaków street_n1 Alfanumeryczne, 0 do 10 znaków street_n2 Alfanumeryczne, 0 do 10 znaków phone Alfanumeryczne, 0 do 15 znaków city Alfanumeryczne, 0 do 40 znaków postcode Alfanumeryczne, 0 do 10 znaków country Alfanumeryczne, 0 do 3 znaków Pierwsza linia adresu wysyłki (ulica) Numer domu z adresu wysyłki Numer mieszkania z adresu wysyłki Numer telefonu klienta Miasto z adresu wysyłki Kod pocztowy z adresu wysyłki Kod kraju z adresu wysyłki. Dla wysyłki na terenie Polski ma wartość PL. email Poprawny adres e- mail, 0 do 40 znaków Adres e-mail klienta Strona 4 z 8
a) Obowiązkowe jest przesłanie pól: pos_id, order_id, amount, test, language. b) Obowiązkowe jest też przesłanie pola client_ip, z wyjątkiem sytuacji kiedy wypełnienie tego pola jest technicznie niemożliwe. c) Obowiązkowe jest przesłanie wszystkich posiadanych przez sklep pól adresu wysyłki. Przez adres wysyłki rozumiane są pola: street, street_n1, street_n2, postcode, city, country, email. d) Wielkość liter w nazwach pól ma znaczenie, np. nazwa pola Pos_Id jest nieprawidłowa. Przykład strony HTML zawierającego poprawny formularz znajduje się poniżej. <html> <head> <title>zaplata za koszyk</title> </head> <body> <p>zamowiles towary za laczna kwote 123 zl 45 gr</p> <p>nacisnij przycisk "Place" w celu przejscia na strone autoryzacyjne firmy PolCard S.A. i uiszczenia zaplaty karta.</p> <form method="post" action="https://post.polcard.com.pl/cgi-bin/autoryzacja.cgi"> <input type="hidden" name="pos_id" value="7100000"> <input type="hidden" name="order_id" value="agd-2004-3124"> <input type="hidden" name="amount" value="12345"> <input type="hidden" name="test" value="n"> <input type="hidden" name="language" value="pl"> <input type="hidden" name="client_ip" value="213.76.114.131"> <input type="hidden" name="street" value="konrada"> <input type="hidden" name="street_n1" value="3"> <input type="hidden" name="street_n2" value="15"> <input type="hidden" name="phone" value=""> <input type="hidden" name="city" value="konin"> <input type="hidden" name="postcode" value="62500"> <input type="hidden" name="country" value="pl"> <input type="hidden" name="email" value="przyklad@testowy.pl"> <input type="submit" value="place"> </form> </body> </html> Strona 5 z 8
3. Skrypty obsługujące zgodę i odmowę Należy przygotować dwa adresy internetowe (URL) pod które będzie przesyłany klient: a) Po uzyskaniu zgody na przeprowadzenie transakcji. Pod tym adresem może być np. strona z podziękowaniem za dokonanie transakcji i instrukcjami dotyczącymi wysyłki. UWAGA! Nie wolno traktować samego faktu wejścia na ten adres jako pełnego potwierdzenia że bank wyraził zgodę na dokonanie transakcji, ponieważ strona ta jest z definicji ogólnodostępna i można na nią wejść celowo nawet jeśli była odmowa dokonania transakcji. Pełne potwierdzenie uzyskuje się po zalogowaniu do panelu administracyjnego FDP i sprawdzeniu statusu transakcji. b) Po otrzymaniu odmowy na dokonanie transakcji. Pod tym adresem może być informacja o tym, że bank wydający kartę nie wyraził zgody na dokonanie transakcji. Może znaleźć się tam np. sugestia dla klienta żeby upewnił się że podał prawidłowy numer karty, datę ważności, ewentualnie kod CVV (wymagany tylko dla kart MasterCard), a w razie kiedy te dane zostały podane poprawnie, skontaktował się z bankiem w celu wyjaśnienia przyczyn odmowy. Na tej stronie może też być sugestia dla klienta żeby spróbował dokonać płatności inną kartą, i służący do tego celu formularz przenoszący na stronę FDP (1). Powyższe adresy mogą być zrealizowane jako skrypty PHP, CGI, ASP, servlety Javy lub w dowolnej innej technologii. Skrypt odbiera z przeglądarki połączenie metodą POST, z następującymi parametrami: nazwa zawartość pos_id order_id Identyfikator sklepu internetowego, otrzymany z PolCardu. Identyfikator zamówienia, nadawany przez sklep internetowy. Dodatkowo przesyłany jest parametr o nazwie session_id, który jest wewnętrznym identyfikatorem transakcji w systemie PolCard S.A. i nie jest istotny dla funkcjonowania sklepu internetowego. Adresy tych skryptów muszą być stałe (nie mogą zawierać zmiennych elementów), ponieważ są wpisywane w FDP jako element konfiguracji sklepu internetowego. Strona 6 z 8
4. Skrypt do obsługi błędów Należy przygotować adres internetowy (URL) pod który będzie przesyłany klient ze stron FDP w razie wystąpienia błędu podczas przetwarzania transakcji. Adres ten może być zrealizowane jako skrypt PHP, CGI, ASP, servlet Javy lub w dowolnej innej technologii. Skrypt odbiera z przeglądarki połączenie metodą POST, z następującymi parametrami: nazwa zawartość pos_id order_id err_code message Identyfikator sklepu internetowego, otrzymany z PolCardu. Identyfikator zamówienia, nadawany przez sklep internetowy. Kod błędu. Kody błędów są opisane w następnej tabeli. Opcjonalny komunikat wyjaśniający okoliczności powstania błędu. Dodatkowo przesyłany jest parametr o nazwie session_id, który jest wewnętrznym identyfikatorem transakcji w systemie FDP. i nie jest istotny dla funkcjonowania sklepu internetowego. Kody błędów (err_code) mogą przybierać następujące wartości (lista może być w przyszłości rozszerzona): kod Opis err01 err02 err03 err04 err05 err06 err07 err08 err09 Błąd techniczny. Nie uzyskano odpowiedzi autoryzacyjnej od banku wydawcy karty. Transakcja byla już przetwarzana i uzyskała zgodę. Nie prowadzono wyszystkich wymaganych danych, lub są one niepoprawne. Nie udało się odczytać konfiguracji sklepu internetowego (na podstawie identyfikatora pos_id). Błąd techniczny. Kod obenie nie używany. Błąd techniczny. Przekroczono dozwoloną liczbę poprawek danych. Należy rozpocząć transakcję od początku (z tym samym order_id) Strona 7 z 8
kod Opis err10 err11 Przekroczono maksymalną kwotę dla tranksacji internetowej (lub kwota jest zbyt niska). Kod obenie nie używany. Adres skryptu musi być stały (nie może zawierać zmiennych elementów), ponieważ jest wpisywany w FDP jako element konfiguracji sklepu internetowego. 5. Tabela zmian Data Data Zakres zmian 01 21.11.2005 Utworzenie dokumentu 02 06.10.2005 Formatowanie dokumentu 03 03.04.2008 Rebranding Strona 8 z 8