Bezpieczne Zakupy specyfikacja techniczna implementacji pełnej

Transkrypt

Bezpieczne Zakupy
specyfikacja techniczna
implementacji pełnej
____________________________________________________________________________________________
POLCARD is a regis tered tra de ma rk of FIRST D AT A POLSKA S.A.,
FIRST DAT A POLSKA S.A., Al. Je roz ol imskie 92, 00-807 Wa rszawa , tel.: +48 22 515 30 05, faks : +48 22 515 30 98
www.firstdata.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
___________________________________________________________________________________
POLCARD is a registered trademark of FIRST DATA POLSKA S.A.
FIRST DATA POLSKA S.A., Al. Jerozolimskie 92, 00-807 Warszawa, tel.: +48 22 515 30 05, faks: +48 22 515 30 98,
Sąd rejestrowy: Sąd Rejonowy dla m. st. Warszawy, nr KRS 0000061293,
kapitał zakładowy: 5.151.000 zł, kapitał wpłacony: 5.151.000 zł,
NIP: 526-02-10-429, www.firstdata.pl
Strona 2 z 22
Zmiany
Nr
wersji
1.1
13 lipiec, 2000
1.2.1
20 września, 2000
Data
1.2.3
1.2.4
9 lipiec, 2004
1.2.5
2 listopad, 2004
1.2.6 06 październik, 2005
1.3
31 marzec, 2008
Zakres zmiany
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. 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. Postępowanie w przypadku odrzucania przez serwer kontrahenta
certyfikatów Thawte
1. Postępowanie w przypadku błędu rozliczeń 98
2. Zmiana typów kart przesyłana w odpowiedzi autoryzacyjnej
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. Formatowanie dokumentu
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
ANC{1,64} Wartość pola order_id przesłanego do FDP przy autoryzacji
płatności.
session_id
ANC{1,1024} Wartość pola session_id przesłanego do FDP przy autoryzacji
płatnosci.
___________________________________________________________________________________
Strona 8 z 22
Nazwa pola
Format
amount
response_code
Zawartość
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
cc_number_hash
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.
card_type
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
address_ok
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".
auth_code
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.
bin
NUM{6,6} Pierwsze 6 cyfr numeru karty, identyfikujące jednoznacznie produkt
kartowy i bank-wydawcę.
fraud
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.
sequence
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
order_id
session_id
Format
Zawartość
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.
pos_id
ANC{1,20} Nadany przez FDP identyfikator serwera kontrahenta (identyfikator
wirtualnego "punktu sprzedaży" lub "terminala"), wartość stała dla danego
kontrahenta
message
AN{0,1024} Komunikat o błędzie w języku określonym wcześniej przez wartość pola
language.
err_code
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
Występowanie
Tid
wymagane
Format
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
Nazwa
Adres
Data
opcjonalne
opcjonalne
Ref
Liczba
Suma
Md5
opcjonalne
opcjonalne
opcjonalne
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.
Pełna nazwa kontrahenta FDP
Adres kontrahenta FDP
Data utworzenia pliku, jeżeli nie występuje przyjmuje się datę odebrania pliku w
FDP
Numer referencyjny - nadawany przez kontrahenta
Liczba rekordów finansowych w przesyłce
Suma wartości transakcji zawartych w zbiorze
opcjonalne
Suma kontrolna części finansowej przesyłki (bez nagłówka)
•
Separator
opcjonalne
Batch
wymagane
opcjonalne
___________________________________________________________________________________
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
Opis
Wersja oprogramowania systemu FDP
Format
Rozróżnienie formatów danych finansowych, wartości dopuszczalne jak dla
rozliczeniowego
Data
TID
Batch
SumaRozliczenia
LiczbaTransakcji
KwotaUznan
LiczbaUznan
KwotaObciazen
LiczbaObciazen
KwotaOdmow
LiczbaOdmow
KwotaError
LiczbaError
KwotaUznanTestowych
LiczbaUznanTestowych
KwotaObciazenTestowych
LiczbaObciazenTestowych
KwotaOdmowTestowych
LiczbaOdmowTestowych
pliku
Data przetworzenia pliku przez FDP
Identyfikator punktu sprzedaży, równy wartości pos_id stosowanej przy autoryzacji.
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
Suma kwot transakcji nie zrealizowanych
Suma kwot transakcji z "katastrofalnym" błędem obsługi (ewentualny błąd w
procedurach FDP)
Suma kwot transakcji testowych rozliczonych w dobro rachunku posiadacza karty
Ilość transakcji testowych włączonych do powyższej sumy
Suma kwot transakcji testowych obciążających rachunek posiadacza karty
Suma kwot transakcji testowych nie zrealizowanych
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
przeprowadzanych przy pomocy kart bankowych.
1.
2.
3.
4.
5.
6.
7.
8.
(FDP)
o
transakcjach
Skrót numeru karty, poprzedzony literą H bez żadnych znaków pomiędzy
Session_ID
Data transakcji (YYMMDD)
Kwota w groszach (tj. bez kropki/przecinka dziesiętnego oddzielającego
pełne złote)
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
Kod Autoryzacji
Typ transakcji (I - Internet Order)
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
Dostępne są przykłady:
● Plik w formacie cfd z zadeklarowanym separatorem
● Plik 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="[email protected]">
<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
Zbiór CFC-001.TXT (format cfc) z zadeklarowanym separatorem (,)
TID: 76543210
Nazwa: NIET-NET, Telefonia Miedzyplanetarna.
Waluta: PLN
Separator: ,
Format: C
H1765518abcdef0333333333333t788a657889973,1903,991203,32100,PD,,I,fak-13
H2765518abcdef0955555559765t788a657889972,9705,991207,150,PD,,I,fak-96
H3765518abcdef09871467855555588a657889971,0312,991207,14999,PD,,I,fak-14
Zbiór CFC-002.TXT (format cfc) z domyślnym separatorem (tabulator)
TID: 76543210
Waluta: PLN
Format: C
md5: 0946e358c3f174ef2751ed0333eb7cfe
H1765518abcdef0333333333333t788a657889973
H1765518abcdef0333333333333t788a657889973
H3765518abcdef09871467855555588a657889971
1903
9705
0312
991203
991207
991207
32100 PD
150
PD
14999 PD
I
I
I
fak-13
fak-96
fak-14
___________________________________________________________________________________
Strona 21 z 22
Zbiór CFD-001.TXT (format cfd, odpowiedź na CFC-001.TXT) z zadeklarowanym
separatorem (,)
TID: 76543210
Waluta: PLN
Separator: ,
Format: D
md5: 3ca22d6f7acf632b2cd797c626deffa4
WersjaOprogramowania: 2.1
T,00,H1765518abcdef0333333333333t788a657889973,1903,991203,32100,PD,,I,fak-13
F,02,H2765518abcdef0955555559765t788a657889972,9705,991207,150,PD,,I,fak-96
F,01,H3765518abcdef09871467855555588a657889971,0312,991207,149999,PD,,I,fak-14
Zbiór CFD-002.TXT (format cfd, odpowiedź na CFC-002.TXT) z domyślnym
separatorem (tabulator)
TID: 76543210
Waluta: PLN
Format: D
md5: 3ca22d6f7acf632b2cd797c626deffa4
WersjaOprogramowania: 2.1
T
F
T
00
fak-13
02
fak-96
00
fak-14
H1765518abcdef0333333333333t788a657889973
1903
991203
32100
PD
I
H1765518abcdef0333333333333t788a657889973
9705
991207
150
PD
I
H3765518abcdef09871467855555588a657889971 0312
991207
14999
PD
I
___________________________________________________________________________________
Strona 22 z 22

Bezpieczne Zakupy specyfikacja techniczna implementacji pełnej

Transkrypt

Podobne dokumenty

Farba do włosów Herbatint - trwała- FF2 PURPUROWA

Pobierz (dokument pdf)

cennik reklamy - JazdaMiejska.pl

Aktualizacja danych firmy Kontrahenta

Konsultant ds. Telesprzedaży

Warszawa, dn. 30.11.2016 Szanowni Państwo, First Data

Polityka informacyjna First Data Polska SA

Regulamin Konkursu AMBASADOR § I. Organizator

Wózek ociekowy

Aktualizacja danych punktu handlowo-usługowego