Integracja Merchanta - dokumentacja techniczna

Transkrypt

Integracja Merchanta
- dokumentacja techniczna
Wer 01/25
Warszawa, Wrzesień 2011
Integracja Merchanta – dokumentacja techniczna eService S.A.
1
1. Modyfikacje dokumentu
Data modyfikacji Wersja
Opis
2010-11-15
Wer 01/01
Tadeusz Żurawski – wersja podstawowa dokumentu
2010-11-18
Wer 01/02
Sebastian Ramatowski – uzupełnienie informacji
2010-11-19
Wer 01/03
Tadeusz Żurawski – uzupełnienie informacji
o mdStatus i wymagania techniczne
2010-12-07
Wer 01/04
2010-12-07
Wer 01/05
Tadeusz Żurawski – modyfikacja tekstu
2010-12-08
Wer 01/06
2010-12-08
Wer 01/07
2010-12-13
Wer 01/08
2010-12-14
Wer 01/09
2010-12-20
Wer 01/10
Tadeusz Żurawski – uzupełnienie o spis treści
2010-12-31
Wer 01/11
Tadeusz Żurawski – modyfikacja dokumentacji
2011-01-05
Wer 01/12
Tadeusz Żurawski – wprowadzenie ograniczeń do
OrderId
2011-01-24
Wer 01/13
Tadeusz Żurawski – wprowadzenie informacji o
przelewach
2011-01-24
Wer 01/14
Sebastian Ramatowski – modyfikacja dokumentu
2011-02-02
Wer 01/15
Tadeusz Żurawski – modyfikacja dokumentu
2011-02-02
Wer 01/16
2011-02-04
Wer 01/17
Sebastian Ramatowski – modyfikacja kodów walut
2011-02-07
Wer 01/18
Sebastian Ramatowski – modyfikacja dokumentu
2011-02-07
Wer 01/19
2011-02-08
Wer 01/20
Edyta Wypart – korekta
2011-02-17
Wer 01/21
2011-03-31
Wer 01/22
Tadeusz Żurawski – uzupełnienie informacji o
powiadomieniu i systemie PayPal
2011-04-04
Wer.01/23
Edyta Wypart – korekta
2
2011-08-25
Wer. 01/24
Boroński Radosław – uzupełnienie informacji
dotyczących usługi PayPal
2011-09-23
Wer. 01/25
Norbert Bielski – uzupełnienie przykładów HTTP z
wymaganymi parametrami o wpis dotyczący
pendingUrl
3
Spis treści:
1. Modyfikacje dokumentu......................................................................................... 2
2. eService Payment Gateway .................................................................................. 5
2.1.
Przeznaczenie dokumentu..................................................................................... 5
2.1.
Zalety eService Payment Gateway ........................................................................ 5
2.2.
Wymagania techniczne dla Systemu Sklepu.......................................................... 6
2.3.
Weryfikacja posiadacza karty................................................................................. 6
3. Udostępnienie płatności w sklepie ........................................................................ 7
3.1.
Uwierzytelnienie Merchanta - TOKEN.................................................................... 8
3.2.
Metody płatności ...................................................................................................11
3.3.
Typ Transakcji (TranTyp) ......................................................................................12
3.4.
Model 1 – Główna strona płatności eService (model domyślny, zalecany) ...........12
3.5.
Model 2 – Wybór formy płatności na stronie sklepu ..............................................24
3.6.
Metoda automatycznego powiadamiana sklepu o zmianie statusu zamówienia ....33
3.7.
Metoda płatności PayPal.......................................................................................38
4. Przejście do systemu produkcyjnego .................................................................. 45
5. Zarządzanie transakcjami ................................................................................... 48
5.1.
Zarządzanie transakcjami przez Panel Administracyjny Akceptanta (model
podstawowy) ....................................................................................................................48
5.2.
Zarządzanie transakcjami przez API (model rozszerzony) ....................................49
6. Natychmiastowe potwierdzanie transakcji........................................................... 50
7. Kontakt ................................................................................................................ 52
4
2. eService Payment Gateway
2.1.
Przeznaczenie dokumentu
Niniejszy dokument opisuje podstawowe metody umożliwiające
obsługę transakcji dokonywanych za pomocą elektronicznych form
płatności z wykorzystaniem eService Payment Gateway.
Przedstawione w dokumencie modele integracji oprogramowania
sklepu z eService są zalecanymi modelami domyślnymi.
2.1.
Zalety eService Payment Gateway
2.1.1. Zalety dla posiadaczy kart
Zalety bezpiecznych płatności eService Payment Gateway dla posiadacza karty:
bezpieczne zakupy online,
brak potrzeby zakupu dodatkowego oprogramowania,
brak konieczności podawania numerów kart w sklepie.
.
2.1.2. Zalety dla Sprzedawców
Zalety bezpiecznych płatności eService Payment Gateway dla Merchantów:
łatwa integracja oprogramowania używanego przez sprzedawcę,
wzrost sprzedaży połączony ze wzrostem zaufania klientów (klient bardziej ufa
rozwiązaniom, w których nie podaje numerów kart na stronie sklepu),
zmniejszenie ryzyka nadużyć finansowych,
minimalizacja wzajemnych oddziaływań klienta i sprzedawcy,
przenoszenie zobowiązania ze sprzedawcy na bank wystawcę karty.
5
2.2.
Wymagania techniczne dla Systemu Sklepu
System sklepu powinien spełniać następujące warunki:
•
ustalony stały publiczny nr IP,
•
przekierowanie do systemu płatniczego musi przenosić na stronę eService
(nie może obsługiwać strony eService we FRAME ani POP-UP),
•
wykorzystywać połączenie szyfrowane do wysyłania informacji,
•
zalecane wykorzystywać połączenie szyfrowane do odbioru informacji.
2.3.
Weryfikacja posiadacza karty
Usługa autoryzacji karty jest dokonywana w czasie rzeczywistym.
Proces ten składa się z faz:
klient wypełnia zakupu odpowiednie pola na stronie eService podając numer
karty, rodzaj karty itd. Następnie klient wciska przycisk „Płacę”.
po naciśnięciu przycisku „Płacę”, do wystawcy karty (Visa lub MasterCard)
wysyłana jest prośba o autentykację Klienta (3-D Secure). Wystawca
sprawdza czy kupujący jest zarejestrowany w programie.
jeśli posiadacz karty jest zarejestrowany to automatycznie otwiera się strona
banku i wtedy wpisuje on swoje sekretne hasło autentykujące.
jeśli hasło zostanie zatwierdzone przez bank to rozpoczyna się właściwy
proces autoryzacji.
jeśli hasło nie zostanie zatwierdzone to autoryzacja nie zostanie dokonana.
6
3. Udostępnienie płatności w sklepie
W niniejszym rozdziale opisano sposoby, w jakie sklep może udostępnić możliwość
przejścia przez proces płatności swojemu klientowi:
Model 1 – wybór formy płatności na głównej stronie płatniczej eService
(model zalecany),
Model 2 – wybór formy płatności na stronie sklepu.
Do potrzeb integracji z systemem testowym wykorzystywane są następujące dane:
ClientId 720000001111101 – tylko karty płatnicze
ClientId 720000001111102 – karty płatnicze i przelewy
Password 123456
Numer karty VISA 4242424242424242
Data ważności
01/2014 – transakcja OK
01/2010 – transakcja NOK
Kod cvv2/cvc2/CID 000
Obok płatności kartowych jest możliwość wykonania płatności za pomocą przelewów
elektronicznych. Z punktu widzenia integracji systemów sklepu i eService, operacje
przelewów nie różnią się od płatności kartami.
UWAGA:
Mając na uwadze powyższe oraz fakt, iż banki nie udostępniają testowych
systemów bankowych, eService zaleca przeprowadzanie testów płatności
eService Payment Gateway poprzez wykonanie transakcji elektronicznych
wyłącznie za pomocą kart płatniczych.
7
3.1.
Uwierzytelnienie Merchanta - TOKEN
Usługa Token jest odpowiedzialna za początkową rejestrację transakcji, zależy
w dużym stopniu od kwoty transakcji, która musi być stała dla danej płatności.
Sprawdza także nazwę użytkownika i hasło sprzedawcy. Serwis zwraca unikalny
identyfikator (Token) używany do identyfikacji transakcji w kolejnych etapach. Usługa
Token jest ujawniana w oprogramowaniu sprzedawcy - komunikacja nie jest
widoczna dla zleceniodawcy.
Pola do wysłania dla weryfikacji Akceptanta:
Nazwa parametru Opis parametru
ClientId MID sprzedawcy
Password Hasło sprzedawcy
OrderId
Unikalny numer zamówienia sprzedawcy może zawierać
znaki [0-9][A-Z][a-z] oraz [-] i mieć długość do 64 znaków.
Kwota transakcji z dwoma miejscami po przecinku lub kropce,
Total musi być taka sama dla dokończenia transakcji przez klienta
– nie może ulec zmianie w trakcie płatności)
Currency
Kod waluty zgodnie ze standardami ISO4217. Wartość
liczbowa reprezentowane jako ciąg znaków. Dla PLN - 985.
Obsługiwane waluty ( Currency) :
Kod Waluta
985 PLN
978 EUR
840 USD
826 GBP
756 CHF
208 DKK
124 CAD
8
578 NOK
752 SEK
643 RUB
440 LTL
946 RON
428 LVL
203 CZK
392 JPY
348 HUF
191 HRK
980 UAH
949 TRY
223 EEK
Powyższe parametry muszą zostać wysłane metodą „post” pod adres:
https://testvpos.eservice.com.pl/pg/token
Przykład HTTP z wymaganymi parametrami.
<form method="post" action="https://testvpos.eservice.com.pl/pg/token">
<input type="hidden" name="ClientId" value="720000001111101"/>
<input type="hidden" name="Password" value="123456" />
<input type="hidden" name="OrderId" value="2010122814122383" />
<input type="hidden" name="Total" value="9.95" />
<input type="hidden" name="Currency" value="985" />
</form>
Odpowiedz z serwera:
status
OK – gdy transakcja została zarejestrowana
ERROR – gdy transakcja nie została zarejestrowana
9
Wygenerowany token (dla statusu==OK)
msg Lista błędnych wiadomości oddzielonych przecinkiem (dla
statusu==ERROR)
Przykład wiadomości z wygenerowanym tokenem:
status=OK&msg=86c830280a85416faf75e3cafc492162
Przykłady wiadomości z błędami:
status=ERROR&msg=amount-lack,currency-invalid,order-number-invalid
status=ERROR&msg=amount-invalid
Kody błędów:
Nazwa błędu Opis błędu
amount-lack Brak kwoty
amount-invalid Zły format kwoty
currency-lack Brak waluty
currency-invalid Nie obsługiwana waluta
order-number-lack Brak numeru zamówienia
order-number-invalid Nieprawidłowy numer zamówienia
order-number-duplicated Transakcja z tym numerem zamówienia już istnieje
merchant-lack Brak ID sprzedawcy
merchant-invalid Sprzedawca lub hasło nieprawidłowe
password-lack Brak hasła sprzedawcy
10
3.2.
Metody płatności
Wyróżniamy trzy podstawowe metody płatności:
Metody płatności kartami:
Metoda płatności (PaymentMethod) Opis
VISA Płatności kartami Visa
MASTERCARD Płatności kartami MasterCard
MAESTRO Płatności kartami Maestro
AMEX Płatności kartami American Express
DINERS Płatności kartami Diners Club i Discover
Metody płatności przelewami:
BZWBK Bank Zachodni WBK
INTELIGO Inteligo
MTRANSFER mBank
MULTIBANK MultiBank
PEKAO Bank Pekao S.A.
ING Bank ING
LUKAS Lukas Bank
CITIBANK Bank Handlowy Citibank (PayByNet)
NORDEA Nordea (PayByNet)
MILLENNIUM Bank Millenium
MILLENNIUM_KIR Bank Millenium (PayByNet)
KREDYT Kredyt Bank
RAIFFEISEN Raiffeisen Bank
INVEST Invest Bank
DEUTSCHE Deutsche Bank
IPKO iPKO
11
BPH BPH
ALIOR Alior Bank
EUROBANK Eurobank
Metoda płatności PayPal:
PAYPAL Metoda płatności PayPal
3.3.
Typ Transakcji (TranTyp)
Wyróżniamy dwa podstawowe typy transakcji:
PreAuth – jest to transakcja z rezerwacją środków z późniejszym dopełnieniem
transakcji
Auth – jest to standardowa autoryzacja kartą płatniczą z wykonaniem od razu
transakcji
finansowej.
Po
poprawnym
zrealizowaniu
transakcji
następuję
automatyczne rozliczenie transakcji
UWAGA:
Wykonywanie transakcji Auth (Autorozliczenie) jest standardowo zablokowane
w eService Payment Gateway. Jeżeli prowadzony przez Państwa model wdrożenia
wymaga jego aktywacji, prosimy o kontakt z eService (patrz rozdział „Kontakt”).
3.4.
Model 1 – Główna strona płatności eService (model domyślny,
zalecany)
W tym modelu sprzedawca, po skompletowaniu przez kupującego zamówienia
w sklepie, przekierowuje go na główna stronę płatności eService, gdzie dokonywany
jest wybór jednej z dostępnych form płatności.
12
System wymaga od sklepu w tym przypadku zamieszczenia swoich danych i danych
dotyczących sprzedaży.
Pola poniżej są obowiązkowe:
ClientId Numer sprzedawcy nadany przez eService – MID
StoreType Typ sprzedawcy .(Dla tego modelu musi być "3d_pay_hosting")
Token Token przesłany z systemu – patrz punkt 2.1.
TranType Pole musi zawierać „Auth” lub „PreAuth” – patrz punkt 2.3.
Total Kwota transakcji
Currency
Kod waluty zgodnie ze standardami ISO4217. Wartość liczbowa
reprezentowane jako ciąg znaków. Dla PLN - 985.
OrderId Unikalny numer zamówienia sprzedawcy
ConsumerName Imię kupującego
ConsumerSurename Nazwisko kupującego
okUrl
failUrl
pendingUrl
lang
Strona internetowa na którą ma być przekierowanie w
przypadku pomyślnej procedury płatności
przypadku niepomyślnej procedury płatności
przypadku oczekującej procedury płatności
Język formatki płatności (pl dla języka polskiego, en dla języka
angielskiego)
<form method="post" action="https://testvpos.eservice.com.pl/fim/eservicegate">
<input type="hidden" name="StoreType" value="3d_pay_hosting" />
<input type="hidden" name="Token" value="16bf1b3fce6f43d48ddb5a0b813bccd2" />
<input type="hidden" name="TranType" value="Auth" />
13
<input type="hidden" name="ConsumerName" value="Michał" />
<input type="hidden" name="ConsumerSurname" value="Smith"/>
<input type="hidden" name="okUrl" value=" https://www.teststore.com/ok.php " / >
<input type="hidden" name="pendingUrl" value=" https://www.teststore.com/pending.php " / >
<input type="hidden" name="failUrl" value="https:// www.teststore.com /fail.php" />
<input type="hidden" name="lang" value="pl" />
</form>
Po poprawnym przesłaniu danych do systemu płatniczego eService nastąpi
przekierowanie
do
strony
wyboru
sposobu
płatności.
Przykładowa
strona
zamieszczona jest poniżej.
Pojawienie się tej strony świadczy o poprawnym przekazaniu niezbędnych informacji
do rozpoczęcia procesu płatności. Następnie klient wybiera sposób płatności
wyświetlane mu jest odpowiednie okno z formularzem do wypełnienia, lub
przekierowany jest do wybranego banku (przelewy).
Dla wersji z obsługą kart płatniczych (MID: 720000001111101) pojawi się strona
zamieszczona poniżej.
14
15
Dla wersji z obsługą przelewów (MID: 720000001111102) pojawi się strona
16
Ekran po wybraniu metody płatności kartą VISA
Po poprawnym wpisaniu danych i zatwierdzeniu przez wciśnięcie przycisku „Płacę”,
system po weryfikacji wygeneruje status transakcji, który po upływie domyślnego
czasu (30s) przekieruje na odpowiedni link powrotny. Będzie to link okUrl w sytuacji
powodzenia transakcji lub failUrl w sytuacji niepowodzenia transakcji.
17
Poniżej przykład strony z komunikatem o pozytywnym zakończeniu transakcji, na
którą, zostanie przekierowany płacący (na zdefiniowany przez Merchanta okUrl).
Pola poniżej nie są obowiązkowe, można je traktować jako dodatkowe:
Numer
ID
transakcji
dla
uwierzytelnienia
3D
zostaje
PayerTxnId wygenerowany przez system. (musi być zakodowany jako
based64 i mieć 28 znaków)
refreshtime
Czas oczekiwania na przekierowanie. (Domyślnie 30s jeżeli nie
jest podany)
TelVoice Numer telefonu
Email Adres e-mail
BillToCompany Nazwa firmy
BillToName Nazwa sprzedawcy
BillToStreet1 Adres sprzedawcy
18
BillToStreet2 Adres 2 linii
BillToStateProv Region
BillToCity Miasto
BillToPostalCode Kod pocztowy
BillToCountry ISO03166 Kod kraju (dla Polski 616)
ShipToCompany Nazwa firmy dostarczającej
ShipToName Nazwa osoby dostarczającej
ShipToStreet1 Adres dostarczającego
ShipToStreet2 Adres 2 linii
ShipToStateProv Region dostarczenia
ShipToCity Miasto dostarczenia
ShipToPostalCode Kod pocztowy miejsca dostarczenia
ShipToCountry ISO03166 Kod kraju (dla Polski 616)
ItemNumber1 Numer produktu
ProductCode1 Kod produktu
Qty1 Ilość
Desc1 Opis
Id1 ID produktu
Price1 Cena
Total1 Koszt całkowity
Przykład HTTP z wymaganymi i opcjonalnymi parametrami.
19
<input type="hidden" name="PayerTxnId" value="egsF658v9uNpdqmksFZ5j9xHV/U=" />
<!—Informacje o sprzedającem [Opcjonalne]-->
<input type="hidden" name="TelVoice" value="012345678">
<input type="hidden" name="Email" value="[email protected]">
<input type="hidden" name="BillToCompany" value="Billing Company">
<input type="hidden" name="BillToName" value="John Smith">
<input type="hidden" name="BillToStreet1" value="Address line 1">
<input type="hidden" name="BillToCity" value="Warsaw">
<input type="hidden" name="BillToStateProv" value="mystate">
<input type="hidden" name="BillToPostalCode" value="12345">
<input type="hidden" name="BillToCountry" value="616">
<!—Informacje o dostawcy [Opcionalne]-->
<input type="hidden" name="ShipToCompany" value="Shipping Company">
<input type="hidden" name="ShipToName" value="John Smith">
<input type="hidden" name="ShipToStreet1" value="Address line 1">
<input type="hidden" name="ShipToCity" value="Warsaw">
<input type="hidden" name="ShipToStateProv" value="mystate">
<input type="hidden" name="ShipToPostalCode" value="12345">
<input type="hidden" name="ShipToCountry" value="616">
<!—Pozostałe paramerty [Opcjonalne]-->
<input type="hidden" name="ItemNumber1" value="a5">
<input type="hidden" name="ProductCode1" value="a5">
<input type="hidden" name="Qty1" value="3">
<input type="hidden" name="Desc1" value="a5 desc">
<input type="hidden" name="Id1" value="a5">
<input type="hidden" name="Price1" value="6.25">
<input type="hidden" name="Total1" value="7.50">
</form>
20
Zmienna PayerTxnId może przyjmować wartość:
$data['PayerTxnId'] = trim(base64_encode(genxid()));
function genxid(){
$let = "ABCDEFGIKLMNOPRSTUWXYZ";
$num = "234567890";
$xid = substr($let, rand(0,(strlen($let)-1)), 1) .
substr($let, rand(0,(strlen($let)-1)), 1) .
substr($num, rand(0,(strlen($num)-1)), 1) .
substr($num, rand(0,(strlen($num)-1)), 1) ;
return $xid;
}
Powyższe parametry muszą zostać wysłane pod adres:
https://testvpos.eservice.com.pl/fim/eservicegate
Pola, które wyśle sprzedawca mogą być wysyłane jako ukryte. Jeśli formularz
zostanie dostarczony do akceptanta nastąpi przygotowanie do zatwierdzenia
płatności. Po zakończeniu tego procesu informacje na temat weryfikacji z poniższymi
21
parametrami będą kierowane do okUrl strony sprzedawcy (w przypadku powodzenia
transakcji) lub failUrl (w przypadku gdy transakcja będzie odrzucona).
Pola odpowiedzi przychodzące do Merchanta:
Kod odpowiedzi:
Response
„Approved” – Zaakceptowana transakcja
„Error" – Wystąpił błąd
„Declined” – Odrzucona transakcja
ClientId Numer sprzedawcy nadany przekazany przez sklep
StoreType Typ sprzedawcy .(Dla tego modelu to "3d_pay_hosting")
Token
TranType
Token przesłany z systemu eService przy uwierzytelnieniu
merchanta – patrz punkt 2.1.
Pole określające typ transakcji ( „Auth” lub „PreAuth” ) –
patrz punkt 2.3.
Currency
Kod waluty zgodnie ze standardem ISO4217. Wartość
PaymentMethod Metoda płatności – patrz punkt 2.2.
mdStatus Status kodu dla uwierzytelnienia metodą 3D
AuthCode Kod weryfikacji transakcji
vendorCode Kod błędu dostawcy metody 3D
ErrMsg Informacja o przyczynie błędu
ProcReturnCode 2 cyfrowe status transakcji. 00 dla autoryzacji pozytywnej
22
Parametr mdStatus zawiera informacje na temat uwierzytelniania 3D.
Kody mdStatus:
Wynik
url
mdStatus Opis
Authenticated transaction (Full 3D)
ok
1
Operacja zatwierdzona
Card not participating or attempt
ok
2,3,4
Karta nie obsługuje 3D
fail
5,6,7,8
Autoryzacja niemożliwa
(Half 3D)
Authentication not available or
system error
Authentication failed
do wykonania
fail
0
Operacja odrzucona
23
3.5.
Model 2 – Wybór formy płatności na stronie sklepu
W tym modelu sprzedawca, po skompletowaniu przez kupującego zamówienia
w sklepie, umożliwia kupującemu dokonanie wyboru formy płatności na swojej
stronie. W następnym kroku kupujący przekierowany jest do właściwego banku lub
na stronę płatności kartą.
StoreType
Typ sprzedawcy .(Dla tego modelu musi być
"3d_pay_hosting_pm")
TranType
Pole określające typ transakcji ( „Auth” lub „PreAuth” ) – patrz
punkt 2.3.
Total Suma transakcji
PaymentMethod
Currency
Metoda płatności (VISA / MASTERCARD / MAESTRO /
DINERS / BZWBK / INELIGO …) – patrz punkt 2.2.
Kod waluty zgodnie ze standardem ISO4217. Wartość liczbowa
okUrl
failUrl
lang
angielskiego)
24
<input type="hidden" name="StoreType" value="3d_pay_hosting_pm" />
<input type="hidden" name="PaymentMethod" value="VISA" />
</form>
Po poprawnym przesłaniu danych do systemu płatniczego eService SA nastąpi
przekierowanie do strony z formularzem do wypełnienia.
25
Po poprawnym wpisaniu danych i zatwierdzeniu przez wciśnięcie przycisku „Płacę”,
system po weryfikacji wygeneruje status transakcji, który po upływie domyślnego
czasu (30s) przekieruje na odpowiedni link powrotny. Będzie to link okUrl w sytuacji
powodzenie transakcji lub failUrl w sytuacji niepowodzenia transakcji.
Poniżej przykład strony z komunikatem o pozytywnym zakończeniu transakcji, na
którą, po zakończeniu domyślnego czasu (30s), zostanie przekierowana na
zdefiniowany przez Merchant okUrl.
26
Pola poniżej nie są obowiązkowe, można je traktować jako dodatkowe:
Numer
ID
transakcji
dla
uwierzytelnienia
3D
zostaje
PayerTxnId wygenerowany przez system. (musi być zakodowany jako
based64 i mieć 28 znaków)
refreshtime
Czas oczekiwania na przekierowanie. (Domyślnie 30s jeżeli nie
jest podany)
TelVoice Numer telefonu
Email Adres e-mail
BillToCompany Nazwa firmy
BillToName Nazwa sprzedawcy
BillToStreet1 Adres sprzedawcy
BillToStateProv Region
BillToCity Miasto
27
BillToPostalCode Kod pocztowy
BillToCountry ISO03166 Kod kraju (dla Polski 616)
ShipToCompany Nazwa firmy do której ma być dostarczane zamówienie
ShipToName Osoba kontaktowa do przyjęcia zamówienia
ShipToStreet1 Adres dostarczenia zamówienia
ShipToStateProv Region dostarczenia
ShipToCity Miasto dostarczenia
ShipToPostalCode Kod pocztowy miejsca dostarczenia
ShipToCountry ISO03166 Kod kraju (dla Polski 616)
ItemNumber1 Numer produktu
ProductCode1 Kod produktu
Qty1 Ilość
Desc1 Opis
Id1 ID produktu
Price1 Cena
Total1 Koszt całkowity
28
<!—Informacje o sprzedającym [Opcjonalne]-->
</form>
29
Zmienna PayerTxnId może przyjmować wartość:
$data['PayerTxnId'] = trim(base64_encode(genxid()));
function genxid(){
$let = "ABCDEFGIKLMNOPRSTUWXYZ";
$num = "234567890";
$xid = substr($let, rand(0,(strlen($let)-1)), 1) .
substr($num, rand(0,(strlen($num)-1)), 1) ;
return $xid;
}
Pola, które wyśle sprzedawca mogą być wysyłane jako ukryte. Jeśli formularz
zostanie dostarczony do akceptanta nastąpi przygotowanie do zatwierdzenia
płatności. Po zakończeniu tego procesu informacje na temat weryfikacji z poniższymi
30
parametrami będą kierowane do okUrl strony sprzedawcy (w przypadku powodzenia
transakcji) lub failUrl (w przypadku gdy transakcja będzie odrzucona).
Kody odpowiedzi:
Kod odpowiedzi:
Response
„Approved” – Zaakceptowana transakcja
„Error" – Wystąpił błąd
„Declined” – Odrzucona transakcja
StoreType Typ sprzedawcy .(Dla tego modelu to "3d_pay_hosting_pm")
Token
TranType
Token przesłany z systemu przy uwierzytelnieniu merchanta
– patrz punkt 2.1.
patrz punkt 2.3.
Currency
PaymentMethod Metoda płatności – patrz punkt 2.2.
mdStatus Status kodu dla uwierzytelnienia metodą 3D
AuthCode Kod weryfikacji transakcji
vendorCode Kod błędu dostawcy metody 3D
ErrMsg Informacja o przyczynie błędu
ProcReturnCode 2 cyfrowe status transakcji. 00 dla autoryzacji pozytywnej
31
Parametr mdStatus zawiera informacje na temat uwierzytelniania 3D.
Kody mdStatus:
Wynik
url
mdStatus Opis
Authenticated transaction (Full 3D)
ok
1
Operacja zatwierdzona
Card not participating or attempt
ok
2,3,4
Karta nie obsługuje 3D
fail
5,6,7,8
Autoryzacja niemożliwa
(Half 3D)
Authentication not available or
system error
Authentication failed
do wykonania
fail
0
Operacja odrzucona
32
3.6.
Metoda automatycznego powiadamiana sklepu o zmianie statusu
zamówienia
Model automatycznego powiadomienia sklepu o zmianie statusu zamówienia dotyczy
głównie d-przelewów oraz niektórych e-przelewów. Występują tylko w sytuacji gdy
klient musi dokonać przelewu, a bank od razu nie dokonuje transakcji tylko wystawia
status na oczekujący (pending). Aby uzyskać automatyczny status powiadomienia
o zmianie statusu należy wysłać następujące pola:
StoreType
Typ sprzedawcy .(dla modelu 1 musi być "3d_pay_hosting"; dla
modelu 2 musi być "3d_pay_hosting_pm".)
TranType Pole musi zawierać „Auth” lub „PreAuth”
Currency
okUrl
failUrl
pendingUrl
Strona
internetowa
na
którą
ma
być
przekierowanie
w przypadku pomyślnej procedury płatności
Strona
internetowa
na
którą
ma
być
przekierowanie
w przypadku niepomyślnej procedury płatności
Strona
internetowa
na
którą
ma
być
przekierowanie
w przypadku oczekującej procedury płatności
lang
angielskiego)
33
Przykład HTTP z wymaganymi parametrami dla modelu 1.
<input type="hidden" name="pendingUrl" value="https:// www.teststore.com /pending.php" />
</form>
Przykład HTTP z wymaganymi parametrami dla modelu 2.
</form>
przekierowanie
do
strony
wyboru
sposobu
płatności.
Przykładowa
strona
zamieszczona jest poniżej. Następnie klient wybiera sposób płatności i zostaje
przekierowany do wybranego banku.
34
Poniżej przykład strony z komunikatem o pozytywnym zakończeniu transakcji. Klient
zostanie przekierowany na zdefiniowany przez Merchanta pendingUrl, skrypt z
obsługą operacji oczekującej.
35
Pola, które wyśle Merchant mogą być wysyłane jako ukryte. Po zakończeniu tego
procesu informacje na temat weryfikacji z poniższymi parametrami będą kierowane
do pendingUrl strony opisującej oczekiwanie na przelew.
Pola odpowiedzi przychodzące do Merchanta:
Response
Kod odpowiedzi:
„Pending” – transakcja oczekująca
Token
36
TranType
patrz punkt 2.3.
Currency
PaymentMethod Metoda płatności – patrz punkt 2.2. – przelewy
Następnie po zmianie statusu w systemie akceptanta z „oczekującego” na
„zatwierdzony” zostanie automatycznie wysłana informacja na okUrl o zatwierdzeniu
transakcji.
Na okUrl zostanie wysłana informacja zawierająca:
Response
Kod odpowiedzi:
„Approved” – transakcja zaakceptowana
Token
TranType
patrz punkt 2.3.
Currency
PaymentMethod Metoda płatności – patrz punkt 2.2. – przelewy
37
3.7.
Metoda płatności PayPal
Integracja płatności PayPal z eService zachodzi według modelu 1.
Aby uzyskać możliwość procesowania transakcji z wykorzystaniem systemu PayPal
merchant musi być zarejestrowany i posiadać aktywne konto w systemie PayPal.
Dodatkowo należy zdefiniować w systemie informację o rodzaju dostarczanych
usług. Należy zdefiniować czy merchant sprzedaje tzw. dobra wirtualne czy dobra
materialne. Jest to parametr niezbędny do prawidłowego dziania sytemu płatności
PayPal.
3.7.1. Tworzenie konta PayPal dla środowiska testowego
………………
………………
3.7.2. Procedura testów dla środowiska testowego PayPal
Sprzedawca,
po
skompletowaniu
przez
kupującego
zamówienia
w sklepie,
przekierowuje go na główna stronę płatności eService, gdzie dokonywany jest wybór
jednej z dostępnych form płatności.
StoreType Typ sprzedawcy .(Dla tego modelu musi być "3d_pay_hosting")
38
TranType Pole musi zawierać „Auth” lub „PreAuth” – patrz punkt 2.3.
Currency
okUrl
failUrl
lang
angielskiego)
</form>
przekierowanie
do
strony
wyboru
sposobu
płatności.
Przykładowa
strona
zamieszczona jest poniżej.
Pojawienie się tej strony świadczy o poprawnym przekazaniu niezbędnych informacji
39
do rozpoczęcia procesu płatności. Następnie klient wybiera sposób płatności
wyświetlane mu jest odpowiednie okno z formularzem do wypełnienia, lub
przekierowany jest do wybranego banku (przelewy).
Dla wersji z obsługą kart płatniczych (MID: 720000001111107) pojawi się strona
Poniżej strona z wyborem płatności na której klient może wybrać metodę PayPal:
Przykład komunikatu dla zapytania o token z wymaganymi parametrami:
<input type="hidden" name="Token" value="0f4a21d16d754afa9282e6e2cdfe3acb">
<input type="hidden" name="lang" value="pl">
<input type="hidden" name="xid" value="JjV3E2dK4GTUk2ekveh8n2LB/lY=">
<input type="hidden" name="Currency" value="985">
<input type="hidden" name="StoreType" value="3d_pay_hosting">
<input type="hidden" name="Total" value="9,95">
<input type="hidden" name="okUrl" value="http://dev-tool.com/eservice/php/teststore.php">
40
<input type="hidden" name="IPAddress" value="62.233.165.73">
<input type="hidden" name="Password" value="123456">
<input type="hidden" name="ClientId" value="720000001111101">
<input type="hidden" name="ConsumerName" value="Michal">
<input type="hidden" name="OrderId" value="RPAW-64">
<input type="hidden" name="failUrl" value="http://dev-tool.com/eservice/php/teststore.php">
<input type="hidden" name="TranType" value="Auth">
<input type="hidden" name="ConsumerSurname" value="Smith">
<input type="hidden" name="failCount" value="0">
<input type="hidden" name="PaymentMethod" value="">
Przykład HTTP z wymaganymi parametrami dla transakcji PayPal:
<input type="hidden" name="Response" value="Pending">
<input type="hidden" name="token" value="EC-0HN38695MF9539819">
<input type="hidden" name="IPAddress" value="62.233.165.73">
<input type="hidden" name="oid" value="RPAW-65">
<input type="hidden" name="clientid" value="720000001111101">
<input type="hidden" name="lang" value="pl">
<input type="hidden" name="PayerID" value="63FWQQF3F2DM4">
<input type="hidden" name="paypal" value="1">
<input type="hidden" name="Response" value="Pending">
<input type="hidden" name="PAYPAL.PendingMsg" value="Pending unilateral">
<input type="hidden" name="PAYPAL.TransId" value="2JP22245678265332">
<input type="hidden" name="ClientId" value="720000001111101">
<input type="hidden" name="TransId" value="112381010470810036">
<input type="hidden" name="TranType" value="Auth">
<input type="hidden" name="PaymentMethod" value="PAYPAL">
<input type="hidden" name="ProcReturnCode" value="">
<input type="hidden" name="Total" value="9.95">
<input type="hidden" name="Currency" value="PLN">
<input type="hidden" name="OrderId" value="RPAW-65">
<input type="hidden" name="ConsumerName" value="eService">
<input type="hidden" name="ConsumerSurname" value="eService">
<input type="hidden" name="Email" value="adres email wprowadzony przez Merchanta w
konfiguracji PayPal, np. [email protected]">
<input type="hidden" name="rnd" value="9hMrFPljOwzjEqoJJGkA">
<input type="hidden" name="ErrMsg" value="">
<input type="hidden" name="HASHPARAMS"
value="ClientId:OrderId:ProcReturnCode:Response:rnd:">
<input type="hidden" name="HASHPARAMSVAL"
value="720000001111101RPAW-65Pending9hMrFPljOwzjEqoJJGkA">
<input type="hidden" name="HASH" value="0vQrNpM0CIYkZ7MuGqsurFnefQE=">
Przykład HTTP z wymaganymi parametrami dla transakcji PayPal.
41
</form>
<!—Informacje o sprzedającym [Opcjonalne]-->
42
</form>
przekierowanie do strony systemu PayPal. Warunkiem dokończenia transakcji jest
wprowadzenie danych adresu email i hasła umożliwiających logowanie do systemu
płatności PayPal. Przykładowa strona zamieszczona jest poniżej.
43
Po pozytywnej weryfikacji danych logowania system przenosi płatnika do strony
żądające potwierdzenia operacji płatności.
44
Kontynuacja płatności jest możliwa poprzez akceptację na dole strony.
Kolejny krok to wprowadzenie danych karty, na podstawie której realizowana będzie
płatność. Przykładowy formularz poniżej.
Zakończenie procesu płatności PayPal powoduje dodanie transakcji po stronie
systemu
eService,
informacja
dla
Merchanta
będzie
dostępna
w
Panelu
Administracyjnych Merchnata.
4. Przejście do systemu produkcyjnego
Po pozytywnie zakończonym etapie integracji z systemem testowym należy zgłosić
ten fakt na adres [email protected] w celu uzyskania danych do przełączenia
się na produkcję. Ważną daną będzie podanie numeru telefonu kontaktowego, na
który zostanie przekazane hasło dostępu do systemu produkcyjnego dla konkretnego
45
„ClientId”. W informacji zwrotnej e-mail zostaną podane wszystkie pozostałe
niezbędne dane do przejścia na produkcję.
Po uzyskaniu danych produkcyjnych i wprowadzeniu ich w Państwa sklepie
internetowym należy przesłać drogą e-mail ([email protected]), adres strony
www sklepu z zaimplementowaną płatnością elektroniczną oraz krótką informację jak
dokonać operacji płatniczej. Próba płatności, która zostanie przeprowadzona
zostanie odrzucona przez bank lub organizację płatniczą.
Po zweryfikowaniu tej funkcjonalności zostanie wysłany na adres zwrotny e-mail
dokument
„Potwierdzenie
Wdrożenia
Oprogramowania”,
które
należy
podstemplować, podpisać i odesłać skan na adres e-mail [email protected]
Po dopełnieniu wszystkich formalności zostaną Państwo uruchomieni produkcyjnie.
4.1.
Tworzenie konta PayPal dla środowiska produkcyjnego
4.1.1 Załóż konto firmowe PayPal
• Dokonasz tego szybko i bezpłatnie, klikając przycisk Załóż konto na stronie
www.paypal.pl.
• Podczas zakładania konta konieczna będzie akceptacja standardowej Umowy z
Użytkownikiem usługi PayPal, która określa zasady współpracy Twojej firmy z firmą
PayPal.
• Krok związany z dodawaniem karty kredytowej możesz anulować.
• Potwierdź adres e-mail przypisany do konta PayPal Merchanta.
4.1.2 Dodaj rachunek bankowy
• Zaloguj się do swojego konta PayPal.
• Na karcie Moje konto z menu Profil wybierz polecenie Dodaj lub usuń rachunek
bankowy.
• Dodanie rachunku bankowego służy m.in. do weryfikacji konta PayPal Merchanta.
4.1.3. Skonfiguruj swoje konto firmowe PayPal do odbioru płatności za
pośrednictwem platformy eService
• Zaloguj się do swojego konta PayPal.
46
• Na karcie Moje konto z menu Profil wybierz polecenie Więcej opcji.
• Wykonaj następujące instrukcje, w zależności od widoku profilu:
• Wersja klasyczna (opcje główne zgrupowane są w trzech kolumnach,
zatytułowanych: Informacje o koncie, Informacje finansowe i Preferencje
sprzedaży)
• W lewej kolumnie, zatytułowanej Informacje o koncie, kliknij łącze Dostęp do API.
• Wersja nowa (opcje główne zgrupowane są w sekcjach panelu po lewej: Dane
mojej firmy, Moje pieniądze, Moje ustawienia i Moje narzędzia sprzedaży)
• W panelu po lewej kliknij łącze sekcji Moje narzędzia sprzedaży.
• W sekcji Sprzedaż w Internecie (jeśli jest zwinięta, kliknij znak plusa na lewo od jej
tytułu) obok opcji Dostęp do API kliknij łącze Zaktualizuj.
• W sekcji Opcja 1 po lewej kliknij łącze Dodaj lub edytuj uprawnienia dostępu do
API.
• Kliknij przycisk Dodaj nową inną firmę.
•
W
polu
Nazwa
użytkownika
dla
uprawnień
innej
firmy
wprowadź
paypal_api1.eservice.com.pl i kliknij przycisk Sprawdź:
• Na liście dostępnych uprawnień zaznacz opcje wymienione poniżej i kliknij przycisk
Dodaj:
• Przetwarzanie płatności z wykorzystaniem ekspresowej realizacji transakcji
• Dokonywanie zwrotu pieniędzy dla konkretnej transakcji
• Uzyskiwanie informacji dotyczących transakcji
• Przeszukiwanie Twoich transakcji pod kątem przedmiotów spełniających określone
kryteria i wyświetlanie wyników
• Autoryzowanie i pobieranie środków dotyczących Twoich transakcji PayPal
4.1.4. Aktywuj płatności PayPal po stronie eService
• Prześlij adres email przypisany do Twojego konta PayPal do firmy eService na
adres :
[email protected]
• W momencie aktywacji płatności PayPal przez firmę eService konfiguracja PayPal
jest zakończona.
47
5. Zarządzanie transakcjami
Zarządzanie transakcjami dokonanymi przez eService Payment Gateway możliwe
jest na kilka sposobów, w zależności od zaawansowania systemów wewnętrznych
sklepu.
5.1.
Zarządzanie transakcjami przez Panel Administracyjny Akceptanta
(model podstawowy)
Podstawowym i domyślnym narzędziem do obsługi transakcji przez sklep jest Panel
Administracyjny Akceptanta, do którego sklep dostaje dostęp podczas wdrożenia.
Panel jest narzędziem stosowanym przez małe i średnie sklepy internetowe.
Dostęp do Panelu umożliwia dokonywanie poniższych grup operacji związanych
bezpośrednio z transakcjami:
•
operacje uzupełniające dokonywane po transakcji kupującego (Przekazanie
transakcji do rozliczenia, Unieważnienie, Zwrot),
•
pozyskiwanie informacji o statusie operacji,
•
pozyskiwanie informacji o historii operacji.
Ponadto, dzięki dostępowi do Panelu można wykonywać czynności dodatkowe,
w tym m.in.:
•
obsługa transakcji telefonicznych, Call Center,
•
generowanie raportów transakcyjnych,
•
administracja Panelem - tworzenie użytkowników Panelu i nadawanie im
odpowiednich uprawnień (np. dla pracowników sklepu, zarządzających
biznesem),
•
wybór wersji językowych Panelu.
48
5.2.
Zarządzanie transakcjami przez API (model rozszerzony)
Alternatywnym
sposobem
zarządzania
transakcjami
jest
wykorzystanie
zaawansowanych integracji wewnętrznych systemów sklepu z systemem eService za
pomocą interface API.
Metoda integracji przez API jest przeznaczona m.in. dla partnerów, sklepów
obsługujących:
•
dużą liczbę transakcji,
•
transakcje telefoniczne, Call Center, IVR,
•
transakcje cyklicznych zleceń obciążenia karty,
•
transakcje typu one-click shopping.
System eService obsługuje następujące technologie integracji API:
•
XML,
•
Java Jpay,
•
DLL,
•
.NET.
Partnerów zainteresowanych obsługą transakcji przez API prosimy o kontakt
z eService (vide: rozdział „Kontakt”) w celu uzyskania dokumentacji wdrożenia API.
49
6. Natychmiastowe potwierdzanie transakcji
W zależności od rodzaju działalności prowadzonej przez sklep istotny jest parametr
czasowy, w którym status transakcji może być przekazany do sklepu.
eService
zapewnia
natychmiastowe
przekazanie
statusów
transakcji
dla
następujących form płatności:
•
Visa
•
MasterCard
•
Maestro
•
Diners Club, Discover
•
American Express
Lista banków, które informują o dostępności swoich systemów 24/7/365:
•
mBank (mTransfer)
•
MultiBank (MultiTransfer)
•
Nordea
•
BZ WBK
•
Bank Millennium
•
Pekao S.A. (Pekao24Przelew)
•
CitiHandlowy
•
Alior Bank
•
LUKAS BANK
50
Potwierdzenia transakcji dokonywanych z poniższych banków możliwe są do
uzyskania w czasie rzeczywistym poza podanymi niżej godzinami godzinami,
wynikającymi z braku pracy on-line wewnętrznych systemów bankowych.
Nazwa Banku
Dni powszednie
BPH (Przelew z BPH)
Weekendy
21:00 – 7:00 następnego 21:00 w piątek – 7:00 w
dnia
poniedziałek
Raiffeisen Bank (R-
Przelew)
dnia
Kredyt Bank
dnia
INVEST-BANK
poniedziałek
poniedziałek
dnia
Deutsche Bank
poniedziałek
dnia
ING Bank Śląski
poniedziałek
dnia
poniedziałek
Eurobank (Euro Bank)
Codziennie w godzinach: 22:30 – 4:30 następnego dnia
Inteligo (Płacę z
Inteligo)
PKO BP (Płacę z iPKO)
51
7. Kontakt
W razie jakichkolwiek pytań prosimy o kontakt z Zespołem Wdrożeniowym eService:
tel.: +48 22 533 22 44
email: [email protected]
52

Integracja Merchanta - dokumentacja techniczna

Transkrypt

Podobne dokumenty

Technologie internetowe

Ćw.1. Przykładowa walidacja formularza PoniŜsza strona wyświetla

JS - obsługa formularzy

Kurs css - formularze - zmiana wyglądu css input

html> html> Ramy dokumentu html Nagłówek

Integracja frameworku Wicket z serwisem Platnosci.pl.

jak w nagłówku strony lub bloga wstawić formularz autorespondera?

Instrukcja instalacji modułu płatności Transferuj.pl