Bezpieczne Zakupy. specyfikacja techniczna implementacji pełnej

Bezpieczne Zakupy specyfikacja techniczna implementacji pełnej 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 w ww. f irs t d a ta.pl Strona 1 z 22

Spis treści Strona ZMIANY... 3 TERMINOLOGIA... 4 AUTORYZACJA... 5 POŁĄCZENIE POSIADACZA KARTY DO WITRYNY KONTRAHENTA... 5 AUTORYZACJA PŁATNOŚCI ZA ZAMÓWIENIE I PRZEKAZANIE KONTRAHENTOWI ODPOWIEDZI AUTORYZACYJNEJ... 7 PRZEKIEROWANIE KLIENTA, REALIZACJA ZAMÓWIENIA... 10 OBSŁUGA BŁĘDÓW... 11 DOSTĘP DO BAZY TRANSAKCJI... 12 ROZLICZENIA... 12 FORMAT PLIKU ROZLICZENIOWEGO... 14 BUDOWA PLIKU ROZLICZENIOWEGO... 14 Nagłówek... 14 Dane... 16 Format cfc, dane dla firmy rozliczeniowej (FDP) o transakcjach przeprowadzanych przy pomocy kart bankowych.... 16 Format cfd, dane zwrotne z firmy rozliczeniowej (FDP)... 17 PRZYKŁADY... 19 FORMULARZ INICJUJĄCY ZAPYTANIE AUTORYZACYJNE... 19 SKRYPT DO OBSŁUGI ROZLICZEŃ... 20 ZBIÓR CFC-001.TXT (FORMAT CFC) Z ZADEKLAROWANYM SEPARATOREM (,)... 21 ZBIÓR CFC-001.TXT (FORMAT CFC) Z DOMYŚLNYM SEPARATOREM (TABULATOR)... 21 ZBIÓR CFD-001.TXT (FORMAT CFD) Z ZADEKLAROWANYM SEPARATOREM (,)... 22 ZBIÓR CFD-001.TXT (FORMAT CFD) Z DOMYŚLNYM SEPARATOREM (TABULATOR)... 22 Strona 2 z 22

Nr wersji Data Zmiany Zakres zmiany 1.1 13 lipiec, 2000 1. Odpowiedź autoryzacyjna: 1. Nowe pole test 2. Nowe pole bin 2. Uściślenie zawartości certyfikatów SSL 3. Uściślenie formatu pól odpowiedzi autoryzacyjnej 4. Zapytanie autoryzacyjne: 1. Nowe pole client_ip 5. Obsługa błędów 6. Pozostawienie kontrahentowi tylko jednego numeru pos_id, przeniesienie mechanizmu dynamicznego przydzielania numerów pos_id do FDP 1.2.1 20 września, 2000 1. Odpowiedź autoryzacyjna 1. Nowe pole auth_code 2. Nowe pole fraud 3. Nowe pole sequence 4. Sposób reakcji na próbę połączenia z błędnym certyfikatem SSL 5. Zmiana kodowania kraju w adresie wysyłki 2. Nowe połączenie do odczytu danych opisujących transakcję 3. Rozliczenia 1. Wyjaśnienie mechanizmu przekazania raportu CFD 1.2.3 1. Postępowanie w przypadku odrzucania przez serwer kontrahenta certyfikatów Thawte 1.2.4 9 lipiec, 2004 1. Postępowanie w przypadku błędu rozliczeń 98 2. Zmiana typów kart przesyłana w odpowiedzi autoryzacyjnej 1.2.5 2 listopad, 2004 1. Dodanie informacji n/t sposobu weryfikacji nowych certyfikatów wydanych przez Thawte (w drzewie razem z VeriSign) 2. Usunięcie informacji n/t stosowania certyfikatów PolCard_TestCA 3. Dodanie informacji o weryfikacji 2 poziomów podpisów w certyfikatach 4. Więcej szczegółów n/t przekazywania pola cc_number_hash 1.2.6 06 październik, 2005 1. Formatowanie dokumentu 1.3 31 marzec, 2008 1. Rebranding Strona 3 z 22

Przeznaczenie dokumentu Niniejszy dokument opisuje: 1. protokół autoryzacji transakcji dokonywanych w systemie Bezpieczne Zakupy; 2. postać zbiorów przeznaczonych do prowadzenia rozliczeń transakcji internetowych, w tym: i. przedstawiania przez Kontrahentów FDP transakcji rozliczeniowych, na które uprzednio uzyskano zgodę FDP; ii. przekazywania przez FDP informacji zwrotnej o przyjęciu bądź odrzuceniu transakcji do rozliczenia. Zakres stosowania dokumentu: Kontrahenci FDP posiadający ważną umowę w zakresie współpracy przy akceptacji kart płatniczych wraz z aneksem na usługę Bezpieczne Zakupy jako załącznik do oferty usługi Bezpieczne Zakupy. Terminologia POLCARD zarejestrowany znak towarowy w ramach którego świadczona jest usługa Bezpieczne Zakupy FDP FIRST DATA POLSKA S.A. właściciel marki POLCARD udostępniający usługę Bezpieczne Zakupy adres bankowy - adres podany przez klienta w banku, we wniosku o wydanie karty płatniczej; adres wysyłki - adres pocztowy, pod który zostaną wysłane zamówione towary. Jeśli towar jest niematerialny, to jako adres wysyłki traktowany jest adres e-mail Klienta i numer IP komputera, z którego uzyskał on połączenie do serwera Kontrahenta. Jest to adres podany przez Klienta Kontrahentowi i przekazywany przez Kontrahenta do FDP w procesie autoryzacji zamówienia; amount - całkowita wartość zamówienia Klienta, uwzględniająca wszystkie czynniki, takie jak opłaty manipulacyjne itp.; cc_number_hash/cc_hash - wynik działania jednokierunkowej funkcji skrótu na numerze karty Klienta. Kontrahent może przechowywać wartości tego pola i podejmować decyzje o dokonaniu transakcji znając historie płatności dokonanych z użyciem tej karty; pole to jest przesyłane przez FDP w tzw. odpowiedzi autoryzacyjnej i powinno być prezentowane przez kontrahenta w odpowiednim miejscu w plikach rozliczeniowych (CFC). Nie należy tego pola mylić z BINem karty. Strona 4 z 22

BIN Bank Identification Number numer identyfikujący bank wydawcę karty, wartość ta jest przesyłana w odpowiedzi autoryzacyjnej, może być stosowana przy okresowych promocjach dla klientów konkretnego banku. internetowy punkt handlowy - punkt w sieci Internet, w którym są lub będą dokonywane transakcje z użyciem karty płatniczej jako środka zapłaty; Klient - osoba zamierzająca zamówić u Kontrahenta towary, usługi bądź informacje, za które zapłaci kartą płatniczą - posiadacz karty; Kontrahent - instytucja prowadząca działalność gospodarczą, która podpisała z FDP umowę o współpracę w zakresie akceptowania i rozliczania transakcji dokonanych z użyciem kart płatniczych oraz aneks na usługę Internet Order Online; order_id - unikalny identyfikator zamówienia, przedstawiony Klientowi po dokonaniu transakcji (np. numer faktury VAT); pos_id - numer identyfikujący serwer Kontrahenta. Numer ten jest nadawany przez FDP. response_code - kod odpowiedzi autoryzacyjnej informujący czy wydawca karty zgodził się na realizację płatności; session_id - unikalny identyfikator zdarzenia polegającego na przejściu przeglądarki Klienta ze stron Kontrahenta na stronę autoryzacyjną FDP w celu dokonania płatności; sklep internetowy - punkt w sieci Internet, w którym są lub będą dokonywane transakcje z użyciem karty płatniczej jako środka zapłaty (inaczej: internetowy punkt handlowy); towar - dobra materialne i niematerialne, za które Klient dokonuje zapłaty kartą płatniczą Kontrahentowi; Autoryzacja Połączenie posiadacza karty do witryny kontrahenta Klient (posiadacz karty) uzyskuje połączenie zgodne z protokołem http, zabezpieczonym technologią SSL z serwerem kontrahenta. Klient zapoznaje się z ofertą kontrahenta i dokonuje wyboru towarów, które chce zamówić. Przed przejściem do autoryzacji zamówienia konieczne jest spełnienie następujących warunków, w dowolnej kolejności: klient powinien zapoznać się z końcową ceną zamawianych towarów, zawierającą wszystkie przewidywalne składniki (np. koszty wysyłki), klient powinien podać adres wysyłki, serwer kontrahenta powinien wygenerować numer session_id., serwer kontrahenta winien zidentyfikować i zapisać do własnej bazy danych adres IP komputera klienta, który Strona 5 z 22

dokonuje zapłaty kartą płatniczą, tego typu dana winna być udostępniana na każde żądanie FDP; Po spełnieniu tych warunków serwer kontrahenta generuje stronę HTML z formularzem odsyłającym klienta do strony autoryzacyjnej FDP. Adres pod który powinien odsyłać formularz jest następujący: https://post.polcard.com.pl/cgi-bin/autoryzacja.cgi Wewnątrz formularza powinny znajdować się niżej opisane pola: Nazwa pola Format Opis zawartości pola session_id ANC {1,1024} Jak w części terminologia. Nowa wartość tego identyfikatora powinna być generowana zawsze przed dostarczeniem klientowi formularza odsyłającego do strony autoryzacyjnej FDP order_id ANC{1,64} Unikalny identyfikator zamówienia (koszyka towarów), znany trzem stronom (klient, kontrahent, FDP), który pojawi się na potwierdzeniu sprzedaży przedstawionym przez sklep posiadaczowi karty po udanej autoryzacji i po decyzji sklepu o dokonaniu sprzedaży. Może to być numer faktury VAT, lub rachunku, który pojawi się na towarzyszącym produktowi, dokumencie papierowym. W przypadku ponownego wygenerowania session_id dla nowej autoryzacji, ten identyfikator nie ulega zmianie. pos_id ANC {1,20} Nadany przez FDP identyfikator serwera kontrahenta (identyfikator wirtualnego "punktu sprzedaży" lub "terminala"), wartość stała dla danego kontrahenta amount NUM {1,10} Wartość zamówienia uwzględniająca wszystkie przewidywalne czynniki. Kwota podana w groszach, tzn. 20 zł 34 gr powinno być zapisane jako 2034 street AN {0,40} Pierwsza linia adresu wysyłki. W większości wypadków powinna zawierać nazwę ulicy i numer lokalu street_n1 AN {0,10} Numer związany z adresem, prawie zawsze jest to numer domu street_n2 AN {0,10} Numer związany z adresem, będzie to numer mieszkania o ile numer mieszkania ma zastosowanie addr2 AN {0,40} Druga linia adresu wysyłki. addr3 AN {0,40} Trzecia linia adresu wysyłki city AN {0,40} Nazwa miasta z adresu wysyłki postcode AN {0,10} Numer kodu pocztowego z adresu wysyłki w formacie 99-999, lub jego odpowiednik dla adresów zagranicznych country AN {1,3} Kod kraju z adresu wysyłki. Kod powinien być taki, jaki stosuje się na samochodowych tablicach rejestracyjnych w danym kraju (Dla Polski="PL", dla Stanów Zjednoczonych Ameryki Pn. "USA", dla Niemiec "D" itd.) language AN {2,2} Język, w którym FDP powinien komunikować się z klientem. Możliwe wartości to: "PL" - polski, "EN" - angielski. email ANC {0,40} Adres e-mail klienta test AN {1,1} Wskaźnik, czy transakcja ma być traktowana jako testowa czy jako produkcyjna. Możliwe są dwie wartości: "N" - produkcyjna, "Y" - testowa client_ip ANC{0,15} Adres IP komputera klienta Strona 6 z 22

Gdzie: {x,y} - pole o minimalnej długości x, maksymalnej długości y; ANC - litery małe i duże a-za-z, cyfry 0-9, następujące znaki: []{}~@#$%^&*()_+- \/<>,.'`*, bez spacji i polskich liter; NUM - cyfry 0-9; AN - jak ANC, z dopuszczonymi spacjami. Kontrahent powinien uniemożliwić więcej niż jedną autoryzację na dany "order_id". W momencie dokonania autoryzacji transakcja z danym "order_id" powinna zostać zaznaczona jako zautoryzowana i w przypadku potrzeby autoryzacji dalszych płatności przez danego klienta powinien być generowany nowy "order_id". FDP może ograniczyć liczbę prób zapłaty z danym "order_id". Po naciśnięciu przez klienta przycisku "Zapłata kartą" nastąpi połączenie do strony autoryzacyjnej FDP. Autoryzacja płatności za zamówienie i przekazanie kontrahentowi odpowiedzi autoryzacyjnej Po połączeniu się ze stroną autoryzacyjną FDP klient (posiadacz karty) wprowadza dodatkowe dane (w tym numer karty i datę jej ważności) konieczne do uzyskania autoryzacji. Autoryzacja jest przeprowadzana przez FDP. Polega ona na skontaktowaniu się z systemem komputerowym banku, który wydał kartę i uzyskaniu odpowiedzi, czy dana płatność może być zrealizowana. Po uzyskaniu odpowiedzi od banku wydawcy FDP przesyła ją kontrahentowi. W tym celu serwer FDP nawiązuje połączenie https zabezpieczone SSL z serwerem kontrahenta wykonując operację POST. Podczas nawiązywania połączenia FDP przedstawia swój certyfikat SSL podpisany przez jeden ze znanych urzędów certyfikacyjnych. Dzięki temu kontrahent ma możliwość upewnienia się, że nadawcą komunikatu jest FDP. Połączenie następuje pod uzgodniony wcześniej z kontrahentem adres URL. Po otrzymaniu przez serwer kontrahenta połączenia pod wskazany adres URL, oprogramowanie serwera kontrahenta powinno w pierwszej kolejności zweryfikować drugą stronę połączenia upewniając się, że jest nią FDP. W tym celu serwer kontrahenta powinien żądać przedstawienia certyfikatu SSL i po jego otrzymaniu upewnić się, że weryfikacja certyfikatu zakończyła się sukcesem, a następnie sprawdzić zawartość poniższych pól certyfikatu: Pole X.509 Symbol Powinno być równe Organization S_DN_O "PolCard S.A." Locality S_DN_L "WARSZAWA" Strona 7 z 22

CommonName S_DN_CN "post.polcard.com.pl" Country S_DN_C "PL" Powyższy certyfikat powinien być podpisany przez: Thawte lub Verisign. Certyfikat instytucji podpisującej również należy sprawdzić (poniżej dane dla certyfikatu wydanego przez Thawte): Pole X.509 Symbol Powinno być równe Organization I_DN_O "Thawte Consulting (Pty) Ltd." CommonName I_DN_CN "Thawte SGC CA" Country I_DN_C "ZA" UWAGA! Ze względu na fakt, że powyższy certyfikat jest podpisany przez root CA Verisign, należy bezwzględnie włączyć w serwerze HTTPS weryfikację certyfikatów do 2 poziomów. W przypadku serwera Apache i modułu mod_ssl, linia taka ma postać: SSLVerifyDepth 2 Z uwagi na fakt, iż błędna weryfikacja może oznaczać próbę dokonania nadużycia, zalecane jest zakończenie połączenia bez udzielania jakiejkolwiek odpowiedzi. W wypadku błędnej weryfikacji certyfikatu kontrahent nie powinien analizować odebranych danych. Zakłada się wtedy, że FDP nie skontaktował się z kontrahentem. Serwer kontrahenta powinien w takiej sytuacji przesłać następującą odpowiedź: Content-Type: text/plain Client authentication failed Taka odpowiedź powinna być przesyłana w każdym przypadku błędnej weryfikacji certyfikatu FDP, tzn. również przy odebraniu żądania dostępu do bazy danych transakcji przez FDP, i przy przesłaniu z FDP raportu rozliczeniowego. Po pozytywnej weryfikacji certyfikatu serwer Kontrahenta powinien odczytać informacje zawarte w następujących polach: Nazwa pola Format Zawartość order_id session_id ANC{1,64} Wartość pola order_id przesłanego do FDP przy autoryzacji płatności. ANC{1,1024} Wartość pola session_id przesłanego do FDP przy autoryzacji płatnosci. Strona 8 z 22

Nazwa pola Format Zawartość amount response_code cc_number_hash card_type address_ok auth_code NUM{1,10} Wartość pola amount przesłanego do FDP przy autoryzacji płatności. Jednocześnie, jest to maksymalna kwota (wyrażona w groszach), do wysokości której kontrahent może wysłać informacje o dokonanej transakcji z danym session_id w celu jej rozliczenia. ANC{3,3} Kod odpowiedzi informujący, czy wydawca karty zgodził się na realizację płatności. Jeśli tej zgody nie uzyskano, FDP nie rozliczy transakcji z danym session_id. Możliwe kody to: 000 zgoda 100 odmowa ANC{1,512} Wynik działania jednokierunkowej funkcji skrótu na numerze karty klienta i numerze pos_id. Kontrahent może przechowywać wartości tego pola i podejmować decyzje o dokonaniu transakcji znając historię płatności dokonanych z użyciem tej karty. ANC{1,20} Napis określający typ karty, służy do wydrukowania szczegółów płatności na fakturze (zamiast numeru karty). Te napisy to np.:visa, ECMC, JCB, PC, PBK Styl, DC ANC{1,1} Rezultat veryfikacji adresu posiadacza karty: 0 - nie był sprawdzany 1 - adres jest OK. 2 - kod pocztowy jest poprawny test ANC{1,1} Wartość flagi test otrzymanej przez FDP w zapytaniu autoryzacyjnym. Powinna być identyczna z wartością flagi test umieszczonej przez kontrahenta w formularzu służącym do dokonania zapytania autoryzacyjnego, tzn. kontrahent powinien kontrolować czy na transakcje produkcyjne otrzymuje odpowiedzi z flagą "N" a na testowe z flagą "Y". bin fraud sequence ANC{1,16} Kod autoryzacji. Jest to kod generowany przez bank-wydawcę karty w razie zaakceptowania transakcji. Wartość tego pola powinna być później odesłana przez kontrahenta w pliku rozliczeniowym. NUM{6,6} Pierwsze 6 cyfr numeru karty, identyfikujące jednoznacznie produkt kartowy i bank-wydawcę. NUM{1,1} Wynik oceny ryzyka przeprowadzanej przez FDP. Wartości pola są następujące: 0 - Ocena ryzyka nie została przeprowadzona dla tej transakcji. 1 - Spodziewany brak ryzyka lub niskie ryzyko w ocenie FDP. 2 - Spodziewane wysokie ryzyko transakcji, nie realizuj zlecenia. Okoliczności przeprowadzenia transakcji będą wyjaśniane przez FDP. Skontaktuj się telefonicznie z FDP w celu wyjaśnienia czy transakcję można przeprowadzić. 3 - Nie realizuj transakcji - bardzo wysoki poziom ryzyka. Wartość tego pola ma charakter informacyjny i nie obliguje kontrahenta do zaniechania realizacji transakcji nawet jeśli została przesłana wartość 2 lub 3. Wiążąca jest jedynie wartość pola response_code. Usługa oceny ryzyka ma na celu zminimalizowanie strat kontrahenta związanych ze sprzedażą przez internet. NUM{6,6} Numer kolejny odpowiedzi autoryzacyjnej, nadawany przez FDP. Numeracja zaczyna się od "000000" i kończy się na "999999". Następną wartością po osiągnięciu "999999" jest znów "000000". Istnienie tego numeru ma ułatwić identyfikację transakcji poprzez stworzenie sekwencyjnego ciągu. Numer ten ma znaczenie Strona 9 z 22

Nazwa pola Format Zawartość wyłącznie jako ewentualna pomoc przy wyjaśnianiu pomiędzy kontrahentem a FDP historii dokonywanych transakcji. Po sprawdzeniu, ze wartości pól "session_id" i "amount" odpowiadają jednemu z realizowanych zamówień, kontrahent powinien potwierdzić fakt otrzymania odpowiedzi autoryzacyjnej, niezależnie od wartości pola "response_code". Potwierdzenie polega na odesłaniu w odpowiedzi do FDP (w tym samym połączeniu) strony HTML zawierającej parę tagów <url_redirect> i </url_redirect>, wewnątrz której powinien zawrzeć się adres, pod który FDP powinien przekierować przeglądarkę klienta (posiadacza karty). Przykładowa odpowiedź może wyglądać następująco: <html> <body> Otrzymano odpowiedź autoryzacyjną do session_id A00123 <url_redirect>https://www.sklep.pl/welcome_back.cgi</url_redirect> </body> </html> FDP udziela posiadaczowi karty odpowiedzi o powodzeniu czy nie powodzeniu autoryzacji transakcji internetowej, a następnie przekierowuje klienta na właściwą stronę. Przekierowanie klienta, realizacja zamówienia Klient zostaje przekierowany pod adres podany w potwierdzeniu odpowiedzi autoryzacyjnej. Kontrahent podejmuje decyzję o realizacji lub odrzuceniu zamówienia. Strona 10 z 22

Obsługa błędów W razie wystąpienia błędu w trakcie przetwarzania autoryzacji przez serwer FDP, nastąpi przekierowanie przeglądarki klienta pod adres uzgodniony z kontrahentem. Przeglądarka klienta połączy się pod w/w adres wykonując operację POST i przekazując dane dotyczące błędu w następujących polach: Nazwa pola Format Zawartość order_id session_id pos_id message err_code ANC{1,64} Wartość pola order_id przesłanego do FDP przy autoryzacji płatności ANC{1,1024} Wartość pola session_id przesłanego do FDP przy autoryzacji płatnosci. ANC{1,20} Nadany przez FDP identyfikator serwera kontrahenta (identyfikator wirtualnego "punktu sprzedaży" lub "terminala"), wartość stała dla danego kontrahenta AN{0,1024} Komunikat o błędzie w języku określonym wcześniej przez wartość pola language. ANC{1,10} Kod błędu, jeden z wymienionych w tabeli poniżej. Kody błędów - wartości pola err_code err_code Znaczenie err01 Nie uzyskano od sklepu potwierdzenia odebrania odpowiedzi autoryzacyjnej Autoryzacja płatności została wykonana przez FDP, ale nie doszło do skutku połączenie do serwera kontrahenta w celu przekazania odpowiedzi autoryzacyjnej. Jeśli autoryzacja była pozytywna, tzn. bank który wydał kartę wyraził zgodę na przeprowadzenie transakcji, to najczęściej (w zależności od banku który wydał kartę) kwota środków dostępnych na karcie zostanie zmniejszona o kwotę transakcji (na kilka dni, po których środki te zostaną odblokowane automatycznie). Nie nastąpi obciążenie konta posiadacza karty, ani płatność dla kontrahenta. err02 Nie uzyskano odpowiedzi autoryzacyjnej Nie udała się autoryzacja płatności przeprowadzana przez FDP, tzn. zapytanie do banku który wydał kartę o możliwość przeprowadzenia transakcji. Zazwyczaj przyczyną powstania tego błędu jest chwilowy wzrost obciążenia sieci autoryzacyjnych i należy ponowić próbę płatności. err03 To zapytanie było już przetwarzane Zapytanie autoryzacyjne identyfikowane przez session_id było już wcześniej przetwarzane przez FDP i uzyskana została zgoda na przeprowadzenie transakcji. Należy ponowić próbę z użyciem innej wartości session_id. err04 Zapytanie autoryzacyjne niekompletne lub niepoprawne Dane przesłane w zapytaniu autoryzacyjnym były niekompletne lub niepoprawne. Zawartość pola message wskazuje na pola których wartość była niepoprawna. err05 Nie udało się odczytać konfiguracji sklepu internetowego Przyczyną powstania tego błędu może być niewłaściwa wartość pola pos_id. err06 Nieudany zapis zapytania autoryzacyjnego Błąd wewnętrzny w systemie FDP. err07 Inna osoba dokonuje płatności. Została przekroczona dozwolona liczba osób które mogą jednocześnie dokonywać płatności. W takiej sytuacji należy ponowić próbę zapłaty za transakcję. FDP po wykryciu takiej sytuacji zwiększy limit jednoczesnych połączeń dla kontrahenta. err08 Nieustalony status połączenia ze sklepem Błąd wewnętrzny w systemie FDP. Strona 11 z 22

err_code Znaczenie err09 Przekroczono dozwoloną liczbę poprawek danych Dla danego session_id przekroczono dozwoloną liczbę poprawek danych wprowadzanych przez posiadacza karty, takich jak numer karty, jej data ważności, typ karty, adres posiadacza karty. Należy ponowić próbę płatności z użyciem innej wartości session_id. err10 Przekroczono maksymalną kwotę transakcji Dla danego session_id przekroczono dozwoloną liczbę poprawek danych wprowadzanych przez posiadacza karty, takich jak numer karty, jej data ważności, typ karty, adres posiadacza karty. Należy ponowić próbę płatności z użyciem innej wartości session_id. Rozliczenia Na koniec dnia, serwer FDP połączy się ze specjalną stroną kontrahenta tzw. URL pollingu w celu pobrania plików rozliczeniowych. Pliki te powinny zawierać informacje o transakcjach do rozliczenia, które zostały zaakceptowane przez kontrahenta. W szczególności może się zdarzyć, że te pliki będą zawierały inne transakcje niż lista autoryzacji wykonanych na rzecz danego Kontrahenta w danym dniu. Może tak się zdarzyć wówczas, gdy z jakichś powodów kontrahent nie wysłał zakupionego towaru w dniu autoryzacji, a robi to kilka dni później (na przykład po uzupełnieniu braków magazynowych). Kontrahent może przekazać transakcje do rozliczenia w ciągu 7 dni kalendarzowych od daty autoryzacji. W przypadku zwrotów, Kontrahent: 1. Jeżeli transakcja autoryzacyjna zakończyła się akceptacją nie musi wykonywać dodatkowej specjalnej autoryzacji dla zwrotu. Informację o zwrocie dołącza do pliku rozliczeniowego. 2. Może przysłać zwrot w czasie zwyczajowo przyjętym na akceptację zwrotów, tj.: 3 miesięcy. Limit 7-miu dni od daty autoryzacji nie obowiązuje w przypadku zwrotów, 3. Jako identyfikację transakcji, musi przyjąć od posiadacza karty numer faktury i numer sesji. Nie może przyjąć jawnego numeru karty ani jawnej daty ważności karty, Kontrahent pod znanym FDP adresowi URL umieszcza aplikację, która na zapytanie HTTP GET prześle aktualny, bieżący plik rozliczeniowy, a następnie na zapytanie HTTP POST przyjmie plik z raportem rozliczeniowym z FDP. Ten skrypt, (patrz przykład), podobnie jak skrypt przyjmujący odpowiedź autoryzacyjną z FDP, musi sprawdzić certyfikaty klienta go wywołującego, tak samo jak w przypadku autoryzacji. W połączeniu POST serwer FDP przesyła raport rozliczeniowy jako upload pliku w parametrze o nazwie clearing_report_file, zgodnie z RFC 1867. Przesłanie tego pliku jest widziane przez serwer kontrahenta tak, jak efekt działania przykładowego formularza: <FORM METHOD="POST" ACTION="www.sklep.pl/rozliczenia" ENCTYPE="multipart/form-data"> Strona 12 z 22

<INPUT NAME="clearing_report_file"> <INPUT TYPE="SUBMIT" VALUE="Wyslij plik rozliczeniowy"> </FORM> Plik przesłany tą metodą jest możliwy do odebrania w różny sposób, w zależności od typu serwera posiadanego przez kontrahenta. Moduł CGI.pm używany wraz z serwerem Apache udostępnia przesyłany plik jako "filehandle" przesłany w polu o nazwie clearing_report_file. Serwery IIS firmy Microsoft nie mają (lub nie wszystkie mają) zaimplementowaną tą część obsługi HTML, i konieczne może być analizowanie zawartości POST'a napisane we własnym zakresie lub zakupione od firmy zewnętrznej. W szczególności, firma Microsoft informuje na swoich stronach o (prawdopodobnie własnym) produkcie "ActiveFile", który ma za zadanie uzupełnienie tej funkcjonalności. W odpowiedzi na POST z FDP skrypt powinien odesłać potwierdzenie w następującym formacie: Content-Type: text/plain Received [pos_id,batch] Słowa pos_id i batch należy zastąpić odpowiednią wartością pos_id i batch (wartość pola Batch z nagłówka otrzymanego raportu). URL przyjmujący rezultat autoryzacji w FDP musi wykonać te samą wstępną kontrolę (tj.: powyższy skrypt aż do linii [use CGI], gdzie zaczyna się obsługa zbiorów rozliczeniowych). Proces rozliczenia jest powtarzany cyklicznie dla każdego ze zbiorów po kolei (jeden zbiór CFC - przetworzenie - jeden zbiór CFD - kolejny CFC... itd.). System przeglądania oczekujących zbiorów rozliczeniowych w FDP, będzie ponawiał GET tego URL aż do czasu, kiedy nie dostanie żadnego zbioru. Wówczas system pobierania zbiorów rozliczeniowych przechodzi do następnego URL. Jeśli kontrahent nie otrzyma raportów rozliczeniowych za dany dzień (na przykład w przypadku awarii serwera czy łącza telekomunikacyjnego) przy każdym następnym połączeniu będą ponawiane próby przetworzenia tych zbiorów. Strona 13 z 22

Format pliku rozliczeniowego Zbiory są plikami tekstowymi ASCII z konwencją końca linii przyjętą w MS-DOS, tj. linie zakończone są sekwencją dwóch bajtów: CR=0x0D i następującym po nim LF=0x0A. Struktura pliku rozliczeniowego Nagłówek Zbiory składają się z nagłówka, który zawiera linie z ogólnymi informacjami o kontrahencie w formie: <Słowo_kluczowe><dwukropek(tj._znak_":")><opcjonalne_spacje_lub_tab*><informacja> * w kodzie heksadecymalnym spacje - 20, tabulacje - 09 Słowa kluczowe mogą zawierać małe lub duże litery. Program analizujący nagłówek przesyłki musi robić porównanie słów kluczowych bez zwracania uwagi na "wielkość" liter (case-insensitive match). Zdefiniowane słowa kluczowe: Słowo kluczowe Tid Format Występowanie wymagane wymagane Opis Kod punktu sprzedaży klienta - - przydzielany przez FDP. Jest on równy wartości pos_id stosowanej przy autoryzacji. Rozróżnienie formatów danych finansowych, możliwe wartości to: C dla pliku CFC Separator Batch opcjonalne wymagane D dla pliku CFD (odpowiedź na rozliczenie wysyłane do FDP). Zmiana znaku separatora pól (domyślnie jest nim tabulator HT). Tutaj "informacją" jest wybierany nowy znak - jeden spośród: '`";,/?~!@#$%^&*_+- = Kolejny numer paczki transakcji (zbioru). Ten numer przybiera kolejne wartosci od 000 do 999 i ponownie 000 i stanowi identyfikacje paczki rozliczeniowej. Jest tym samym numerem, który pojawia się w nazwie zbioru. Nazwa opcjonalne Pełna nazwa kontrahenta FDP Adres opcjonalne Adres kontrahenta FDP Data opcjonalne Data utworzenia pliku, jeżeli nie występuje przyjmuje się datę odebrania pliku w FDP Ref opcjonalne Numer referencyjny - nadawany przez kontrahenta Liczba opcjonalne Liczba rekordów finansowych w przesyłce Suma opcjonalne Suma wartości transakcji zawartych w zbiorze Md5 opcjonalne Suma kontrolna części finansowej przesyłki (bez nagłówka) Strona 14 z 22

Raport z rozliczenia transakcji będzie miał taki sam separator jak zbiór przyjęty do rozliczenia. W przesyłce zwrotnej (tj. wysyłanej z FDP do klienta) mogą dodatkowo wystąpić następujące linie nagłówka: Słowo kluczowe WersjaOprogramowania Format Data TID Batch SumaRozliczenia LiczbaTransakcji KwotaUznan LiczbaUznan KwotaObciazen LiczbaObciazen KwotaOdmow LiczbaOdmow KwotaError LiczbaError KwotaUznanTestowych LiczbaUznanTestowych Opis Wersja oprogramowania systemu FDP Rozróżnienie formatów danych finansowych, wartości dopuszczalne jak dla rozliczeniowego Data przetworzenia pliku przez FDP Identyfikator punktu sprzedaży, równy wartości pos_id stosowanej przy autoryzacji. pliku Kolejny numer paczki transakcji (zbioru). Ten numer przybiera kolejne wartosci od 000 do 999 i ponownie 000 i stanowi identyfikację paczki rozliczeniowej. Jest to numer Batch zbioru rozliczeniowego cfc, którego dotyczy raport. Różnica pomiędzy sumą obciążeń i sumą uznań Ilość transakcji odpowiadająca polu Liczba w przesyłce do FDP Suma kwot transakcji w rozliczonych dobro rachunku posiadacza karty Ilość transakcji włączonych do powyższej sumy Suma kwot transakcji obciążających rachunek posiadacza karty Ilość transakcji włączonych do powyższej sumy Suma kwot transakcji nie zrealizowanych Ilość transakcji włączonych do powyższej sumy Suma kwot transakcji z "katastrofalnym" błędem obsługi (ewentualny błąd w procedurach FDP) Ilość transakcji włączonych do powyższej sumy Suma kwot transakcji testowych rozliczonych w dobro rachunku posiadacza karty Ilość transakcji testowych włączonych do powyższej sumy KwotaObciazenTestowych Suma kwot transakcji testowych obciążających rachunek posiadacza karty LiczbaObciazenTestowych Ilość transakcji testowych włączonych do powyższej sumy KwotaOdmowTestowych LiczbaOdmowTestowych Suma kwot transakcji testowych nie zrealizowanych Ilość transakcji testowych włączonych do powyższej sumy Linie nagłówka zaczynające się znakiem niewidocznym - spacją = 0x20 lub tabulatorem = 0x09, stanowią kontynuacje poprzednich linii nagłówka. Nagłówek kończy się pustą linią, czyli wystąpienie bezpośrednio po sobie dwóch znaków końca linii (z których każdy jest dwubajtową sekwencją) oznacza koniec nagłówka. Strona 15 z 22

Dane Wszystko, co następuje po nagłówku jest informacją finansową i ma format linii tekstu z poszczególnymi danymi oddzielonymi od siebie znakiem separatora - domyślnie tabulatora (0x09). Format dopuszcza możliwości użycia innego znaku niż znak tabulatora jako separatora pól. Nowy separator jest zdefiniowany w nagłówku. Jeżeli w linii nagłówka "separator:" jest umieszczony inny znak niż zawarty w liście legalnych separatorów, to dla programu przyjmującego przesyłkę, separatorem pozostaje znak tabulatora. Raport z przetwarzania CFD będzie miał ten sam separator który był zdefiniowany w zbiorze z transakcjami CFC. Pola opcjonalne mogą pozostać niewypełnione. Rok jest na kartach zapisywany w formie dwucyfrowej YY. Liczby YY mniejsze niż 60 oznaczają rok w XXI stuleciu, np. 09 oznacza rok 2009. Konwencja nazw zbiorów CFC-xxx.TXT CFD-xxx.TXT zbiory przychodzące do FDP (format cfc) zbiory wychodzące z FDP (format cfd) Format cfc, dane dla firmy rozliczeniowej (FDP) o transakcjach przeprowadzanych przy pomocy kart bankowych. 1. Skrót numeru karty, poprzedzony literą H bez żadnych znaków pomiędzy 2. Session_ID 3. Data transakcji (YYMMDD) 4. Kwota w groszach (tj. bez kropki/przecinka dziesiętnego oddzielającego pełne złote) 5. Wskaźnik określający rodzaj transakcji: Test/Production oraz Credit/Debit/Void - znak TC, TD, TV, PC, PD lub PV. Transakcje 'Production' mogą przesyłać jedynie punkty (sklepy), którym w FDP został nadany odpowiedni status. Transakcje z punktów, które nie mają statusu produkcyjnego, są traktowane jako transakcje testowe niezależnie od przesłanego wskaźnika P/T. Znaczenie znacznika C/V/D jest następujące: Transakcje D obciążają konto posiadacza karty, transakcje C uznają konto posiadacza karty kwotą zwrotu, transakcje V oznaczają transakcje, które były w sklepie autoryzowane, ale sklep z jakichś powodów (np.: niezgodności adresów wysyłki i posiadacza karty) nie będzie realizował zamówienia. 1 6. Kod Autoryzacji 7. Typ transakcji (I - Internet Order) 8. Order_ID Dostępne są przykłady: 1 Jeśli chcą Państwo dokonać zwrotu na kartę już rozliczonej transakcji, należy ją przedstawiać jako PC (odpowiednio TC dla transakcji testowych). Strona 16 z 22

Plik w formacie cfc z zadeklarowanym separatorem Plik w formacie cfc z domyślnym separatorem Format cfd, dane zwrotne z FDP Dane zwrotne mają ten sam format co dane przesłane do rozliczeń, z dokładnością do dwóch pól poprzedzających dane "formatu C". Wskazują one stan realizacji transakcji. Pole "Kod Autoryzacyjny" może być wypełnione przez FDP w wyniku realizacji transakcji. 1. Wskaźnik realizacji transakcji: T - transakcja przyjęta do rozliczenia, F - transakcja odrzucona, E - transakcja, w trakcie której wystąpił błąd systemu FDP (taki raport transakcji jest powodem do wszczęcia "procedury alarmowej"). 2. kod rozliczenia (patrz: możliwe kody rozliczenia) 3. Skrót numeru karty (poprzedzony litera 'H') 4. Session_ID 5. Data transakcji (YYMMDD) 6. Kwota w groszach (tj. bez kropki/przecinka dziesiętnego oddzielającego pełne złote) 7. Wskaźnik określający rodzaj transakcji: Test/Production/Credit/Debit - znak TC lub PC lub TD lub PD 8. Kod Autoryzacji 9. Typ transakcji (I dla transakcji Internetowych) 10. Order_ID Plik Plik Dostępne są przykłady: w formacie cfd z zadeklarowanym separatorem w formacie cfd z domyślnym separatorem Kody rozliczeń: Status Opis 00 OK., transakcja przyjęta do rozliczenia 01 Nie znaleziono pary session_id + pos_id + cc_hash (nie ma takiej transakcji) 02 Autoryzacja odmowna 03 Rezygnacja Kontrahenta z transakcji przyjęta przez FDP 04 Zbyt późne przedstawienie transakcji do rozliczenia 05 Kwota wyższa od kwoty autoryzacji 06 Transakcja była już rozliczona 07 Próba uznania do nierozliczonej transakcji 08 Kwota poniżej limitu dolnego transakcji Strona 17 z 22

Status Opis 09 Nieznany typ transakcji (nie Debit i nie Credit) 10 Brak daty autoryzacji 97 Cc_hash nie jest oznaczony jako hash (brak "H" na początku wiersza 98 Database update error. Przedstaw tę transakcję do rozliczenia później w kolejnym pliku batch. 99 Inny powód nie przyjęcia do rozliczenia, nieodwracalny Strona 18 z 22

Przykłady Formularz inicjujący zapytanie autoryzacyjne <FORM METHOD="POST" ACTION="https://post.polcard.com.pl/cgi-bin/autoryzacja.cgi"> <INPUT TYPE="HIDDEN" NAME="session_id" VALUE="A00123"> <INPUT TYPE="HIDDEN" NAME="order_id" VALUE="fak-43/12/98:bac"> <INPUT TYPE="HIDDEN" NAME="pos_id" VALUE="123456"> <INPUT TYPE="HIDDEN" NAME="amount" VALUE="2034"> <INPUT TYPE="HIDDEN" NAME="street" VALUE="Ostrobramska"> <INPUT TYPE="HIDDEN" NAME="street_n1" VALUE="103"> <INPUT TYPE="HIDDEN" NAME="street_n2" VALUE=""> <INPUT TYPE="HIDDEN" NAME="addr2" VALUE=""> <INPUT TYPE="HIDDEN" NAME="addr3" VALUE=""> <INPUT TYPE="HIDDEN" NAME="city" VALUE="Warszawa"> <INPUT TYPE="HIDDEN" NAME="postcode" VALUE="04-041"> <INPUT TYPE="HIDDEN" NAME="country" VALUE="PL"> <INPUT TYPE="HIDDEN" NAME="language" VALUE="PL"> <INPUT TYPE="HIDDEN" NAME="email" VALUE="joe@nowhere.com.pl"> <INPUT TYPE="HIDDEN" NAME="test" VALUE="N"> <INPUT TYPE="SUBMIT" VALUE="Platnosc karta"> <FORM> Strona 19 z 22

Skrypt do obsługi rozliczeń #!/usr/bin/perl -w # kontrola certyfikatów wykonana przez warstwę SSL, jej rezultaty są dostępne w ENV unless ( $ENV{'SSL_CLIENT_VERIFY'} and ($ENV{'SSL_CLIENT_VERIFY'} eq 'SUCCESS') and ($ENV{'SSL_CLIENT_S_DN_O'} eq 'PolCard S.A.')) { and ($ENV{'SSL_CLIENT_S_DN_L'} eq 'WARSZAWA') and ($ENV{'SSL_CLIENT_S_DN_CN'} eq 'post.polcard.com.pl') and ($ENV{'SSL_CLIENT_S_DN_C'} eq 'PL') and ($ENV{'SSL_CLIENT_I_DN_O'} eq 'Thawte Consulting cc')) { and ($ENV{'SSL_CLIENT_I_DN_CN'} eq 'Thawte Server CA')) { and ($ENV{'SSL_CLIENT_I_DN_C'} eq 'ZA') exit; } else { # test czasu ważności prezentowanego certyfikatu klienta use HTTP::Date; my @F = split / /, $ENV{'SSL_CLIENT_V_START'}; $tm = str2time("$f[1] $F[0] $F[3] $F[2] $F[4]") or exit; exit if ($tm > time); @F = split / /, $ENV{'SSL_CLIENT_V_END'}; $tm = str2time("$f[1] $F[0] $F[3] $F[2] $F[4]") or exit; exit if ($tm < time); } use CGI; $q = CGI->new; if (($filename = $q->param('clearing_report_file')) and ($filename =~ /^cfd/i)) { # w tej gałęzi, skrypt przyjmuje jeden raport CFD; tym zbiorem jest konkretnie # zawartosc parametru: CLEARING_REPORT_FILE, pozostałe parametry tego # formularza, to (duze litery sa tu użyte tylko dla wytłuszczenia): # - POS_ID - numer punktu sprzedaży (pochodzi z linii nagłówka TID zbiory CFC) # - BATCH - numer wysyłki, również pochodzi z nagłówka CFC. # Na koniec, ten skrypt musi zaznaczyć w bazach danych serwera, ze właśnie # odebrany zbiór CFD usuwa odpowiadający mu CFC z kolejki oczekujących na # wysłanie, co daje możliwość drugiej gałęzi tego skryptu, na wysłanie # kolejnego CFC przy następnym wywołaniu # poniższy tekst powinien pojawić się po zakończeniu odbierania pliku. print $q->header(-content_type => 'text/plain'); print "Received [$pos_id,$batch]\n"; # W przypadku wystąpienia błędów uniemożliwiających dalszą obslugę CFD, ta # część skryptu powinna brutalnie przerwać połączenie. } else { print $q->header(-type => "text/plain; charset=iso-8859-2", -content_transfer_encoding => "8bit"); # teraz, ten skrypt wysyła jeden, bieżący CFC. } Strona 20 z 22