this guide

Homepay Sp. z o.o.
ul. Grzybowska 87
00-844 Warszawa
tel./fax: +48.22 266 85 25/24
[email protected]
http://homepay.pl
Dokumentacja techniczna usług paysafecard dla serwisu http://homepay.pl
(wersja: 1.0.1; ostatnia modyfikacja: 9 czerwiec 2016)
Dokumentacja techniczna
1. Tworzenie nowej płatności
W celu utworzenia nowej płatności należy na swojej stronie umieścić odpowiedni formularz
wysyłany metodą HTTP/POST, który przekieruje klienta do serwisu Homepay (patrz: Adres
aplikacji Homepay). Lista parametrów oraz ich znaczenie zawarta jest w punkcie: Parametry
płatności paysafecard.
Po zakończonej płatności Klient zostanie przekierowany na adres HTTP Adres powrotny (płatność
OK) lub Adres powrotny (błąd płatności). Może się też zdarzyć, że Klient nie powróci wcale do
aplikacji Partnera, dlatego informacja przekazywana za pomocą tych adresów nie ma znaczenia
wiążącego, nie można na jej podstawie podejmować żadnych decyzji dotyczących płatności.
Sposób przekazywania informacji o transakcjach jest opisany na podstronie: Odbiór informacji o
płatności.
Przykładowy formularz z minimalną liczbą parametrów:
<form method="post" name="paysafecard" action="https://ssl.homepay.pl/paysafecard/">
<input type="hidden" name="uid" value="1">
<input type="hidden" name="public_key" value="d41d8cd98f00b204e9800998ecf8427e">
<input type="hidden" name="amount" value="100">
<input type="hidden" name="crc" value="71b9e2e31162837a421d3e3a8e41d828">
</form>
2. Parametry płatności paysafecard
Parametr Wymagany
Typ
Znaczenie
uid
Tak
INT
identyfikator użytkownika – odbiorcy płatności w
systemie Homepay
public_key
Tak
STR {32}
klucz publiczny dla płatności paysafecard nadany przez
Homepay1 służący do wygenerowania podpisu
amount
Tak
INT
label
Nie
STR {0,64}
control
Nie
STR {0,200} dowolna informacja zdefiniowana przez Partnera lub
aplikację Partnera przekazywana pod Adres powiadomień
o przebiegu płatności
success_url
Nie
STR {0,700} adres2 powrotny (płatność OK) na który Klient zostanie
przekierowany po poprawnej płatności
failure_url
Nie
STR {0,700} adres2 powrotny (błąd płatności) na który Klient zostanie
przekierowany w przypadku błędu
notify_url
Nie
STR {0,700} adres2 do odbioru informacji o płatności
crc
Tak
STR {32}
kwota w groszach
opis transakcji widoczny na wyciągach
suma kontrolna przesyłanych parametrów formularza 3
Wszelkie wartości tekstowe z powyższego formularz przekazywane do Homepay należy kodować
w UTF-8.
1/4
Homepay Sp. z o.o.
ul. Grzybowska 87
00-844 Warszawa
tel./fax: +48.22 266 85 25/24
[email protected]
http://homepay.pl
1
Klucz publiczny paysafecard dostępny jest w panelu partnera Homepay w zakładce paysafecard
→ Ustawienia. Więcej informacji w punkcie: Podpisywanie formularza.
2
Wszystkie adresy przekazywane do Homepay należy, ze względu na znaki specjalne, poddać
kodowaniu URL (URL encoding, application/x-www-form-urlencoded, znak spacji zamieniany na
'+'), np. w PHP służy do tego funkcja urlencode.
3
Więcej informacji w punkcie: Podpisywanie formularza.
3. Statusy transakcji
Status
Opis
0
nowa
1
rozpoczęta
2
zakończona
3
przetestowana (tylko dla trybu testowego)
4
odrzucona
5
wygasła
4. Adres aplikacji Homepay
Adres URL dla aplikacji Homepay dla płatności paysafecard to:
https://ssl.homepay.pl/paysafecard/
5. Podpisywanie formularza
Aplikacja Partnera musi dodać do formularza płatności paysafecard sumę kontrolną wszystkich
przekazywanych parametrów. W tym celu do formularza dodajemy specjalny parametr: crc.
Algorytm generowania podpisu formularza:
a) Posortuj wszystkie pola formularza zgodnie z tabelą Parametry płatności paysafecard.
b) Dokonaj konkatenacji wartości wszystkich pól formularza zgodnie z wcześniej
wyznaczonym porządkiem.
c) Do tak powstałego ciągu znaków dodaj na końcu swój klucz prywatny paysafecard.
Klucz prywatny paysafecard dostępny jest w panelu partnera Homepay w zakładce
paysafecard → Ustawienia. UWAGA! Klucza prywatnego nie należy podawać w żaden
sposób do widoku publicznego (np. jako pole formularza w HTML), służy on wyłącznie
do ostatecznego podpisania formularza, a ujawnienie go naraża Partnera na możliwość
oszustwa.
d) Cały ciąg należy poddać haszowaniu algorytmem MD5.
W przypadku, gdy wartość crc zostanie błędnie wyliczona lub zostaną zmienione wartości innych
przekazywanych parametrów płatność zostanie odrzucona przez Homepay, a Klientowi zostanie
wyświetlony błąd przebiegu płatności.
Pseudokod algorytmu generowania podpisu parametrów formularza:
generate_crc(form, privateKey) {
content = ""
foreach value in form {
content = content + value
}
content = content + privateKey
return md5(content)
}
2/4
Homepay Sp. z o.o.
ul. Grzybowska 87
00-844 Warszawa
tel./fax: +48.22 266 85 25/24
[email protected]
http://homepay.pl
Podpis przykładowego formularza
Dokonanie konkatenacja wartości wszystkich pól formularza z dodanym na końcu swoim kluczem
prywatnym.
W
tym
przykładzie
użyjemy
fałszywego
klucza
publicznego
d41d8cd98f00b204e9800998ecf8427e oraz prywatnego 098f6bcd4621d373cade4e832627b4f6:
1d41d8cd98f00b204e9800998ecf8427e100098f6bcd4621d373cade4e832627b4f6
Powyższa wartość jest użyta do podpisu po wykonaniu haszowania MD5, którego wynik to:
71b9e2e31162837a421d3e3a8e41d828
Element formularza HTML zawierający wygenerowany podpis:
<input type="hidden" name="crc" value="71b9e2e31162837a421d3e3a8e41d828">
6. Odbiór płatności
Podając w formularzu wartości dla parametru Adres odbioru informacji o płatności każde
zakończenie płatności (niezależnie od statusu) raportowane jest przez żądanie HTTP/POST pod
wskazany adres (np. do aplikacji Partnera). Powiadomienia wysyłane są natychmiast po zmianie
statusu płatności. Wszelkie informacje dotyczące płatności znajdują się w parametrze tablicy POST
żądania o nazwie: json, który zawiera dane w tabeli w formacie JSON:
Parametr
Typ
Znaczenie
psc_id
INT
identyfikator transakcji Homepay
psc_usr_id
INT
identyfikator Partnera w Homepay
psc_time
INT
znacznik czasu (UNIX timestamp) ostatniej zmiany statusu
transakcji
psc_status
ENUM
status transakcji, patrz punkt: Statusy transakcji
psc_amount
DECIMAL(10,2) kwota transakcji
psc_provision
DECIMAL(1,3) procent prowizji Homepay
psc_email
STR {1,100}
adres e-mail klienta dokonującego płatności podany na
stronie wpłaty paysafecard Homepay
psc_merchant_label
STR {0,64}
opis transakcji widoczny na wyciągach
psc_merchant_data
STR {0,200}
dowolna informacja zdefiniowana przez Partnera lub
aplikację Partnera w formularzu
Przykładowe dane wysyłane przez Homepay:
[{"psc_id":123,"psc_usr_id":1,"psc_time":1234567890,"psc_status":3,"psc_amount":1.23,"psc_provision":0.15,"psc_
email":"[email protected]","psc_merchant_label":"Test","psc_merchant_data":10}]
Dane JSON należy konwertować w sposób czytelny dla aplikacji Partnera, np. w PHP przez funkcję
json_decode do tablicy (array) lub obiektu PHP.
Homepay oczekuje od aplikacji Partnera potwierdzenia odbioru i prawidłowego odczytu danych
poprzez zwrócenie pustej strony zawierającej wyłącznie tablicę JSON z parametrami:
Parametr
psc_id
psc_return
Typ
Znaczenie
INT
identyfikator transakcji Homepay przekazany przez Homepay
w żądaniu przychodzącym
INT, STATIC
1 – w przypadku prawidłowego odbioru
0 – w przypadu błędu
3/4
Homepay Sp. z o.o.
ul. Grzybowska 87
00-844 Warszawa
tel./fax: +48.22 266 85 25/24
[email protected]
http://homepay.pl
Przykładowe dane oczekiwane przez Homepay:
[{"psc_id":123,"psc_return":1}]
W przypadku nieodebrania powiadomienia, błędnego odbioru powiadomienia lub zwrócenia błędu
przy odbiorze powiadomienia Homepay podejmie 50 prób ponownego powiadomienia, gdzie każde
kolejne będzie wysyłane w 60 sekundowym odstępie od poprzedniego. Po przekroczeniu limitu
błędnych prób Homepay zaniecha dalszej wysyłki powiadomień niezależnie od stanu transakcji
oraz informacji odebranych przez klienta i statusu ich przetworzenia.
UWAGA! Aplikacja Partnera jest zobowiązana do sprawdzenia adresu IP z którego pochodzą
przychodzące informacje oraz potwierdzenie, czy adres pochodzi z puli adresacji IP Homepay
dostępnej pod adresem: http://get.homepay.pl (adresy oddzielane znakiem przecinka)
7. Tryb testowy
Homepay udostępnia swoim Partnerom tryb symulacji płatności, tzw. „tryb testowy”, który pozwala
na przetestowanie integracji na linii Partner ↔ Homepay. W trybie testowym wszystkie płatności są
automatycznie akceptowane bez kontaktu z paysafecard i konieczności podawania kodów kart.
Tryb testowy można włączyć w Panelu Partnera Homepay w zakładce paysafecard → Ustawienia.
Aby wyłączyć tryb testowy należy wykonać identyczną czynność.
UWAGA! Tryb testowy można włączyć i wyłączyć wyłącznie manualnie. Pozostawienie
włączonego trybu testowego może narazić Partnera na straty w związku z brakiem poboru opłat.
8. Przykładowy skrypt PHP
Przykładowy skrypt obustronnej komunikacji dla integracji paysafecard w Homepay w języku PHP
dostępny jest w Panelu Partnera Homepay w zakładce Homepay → Dokumentacje w tabeli
„Przykładowe skrypty – pozostałe”.
W przypadku problemów z integracją należy kontaktować się z działem technicznym pod nr tel
+48.22 266 85 27 lub pod adresem e-mail [email protected]
4/4