Przelewy
Wprowadzenie
Niniejsza dokumentacja dotyczy implementacji systemu pay by link (PBL) na zewnętrznej stronie sprzedawcy. PBL umożliwia płatność za pośrednictwem linku. Płatność odbywa się według poniższego schematu:
- Wybór produktu, który interesuje klienta.
- Dodanie produktu do koszyka.
- Przejście na stronę płatności za pośrednictwem linku wyposażonego w odpowiednie zmienne przesyłane kanałem niejawnym do formularza płatności HotPay.
- Uzupełnienie podstawowych danych oraz wybór banku.
- Przeniesienie klienta na stronę banku.
- Zlecenie płatności w banku klienta.
- Zakończenie procesu płatności oraz przekierowanie klienta na stronę sklepu.
Implementacja systemu płatności będzie się zatem odbywała na zasadzie przygotowania odpowiedniego łącza i wyposażenie go w odpowiednie zmienne, które zostaną przekazane do formularza płatności HotPay
Rejestracja konta w HotPay
W celu zgłoszenia serwisu lub sklepu, w ramach którego przyjmowane będą płatności, konieczne jest posiadanie konta w systemie HotPay.pl. W celu założenia konta należy kolejno:
- Otworzyć podstronę: https://hotpay.pl/rejestracja/.
- Wypełnić dane rejestracyjne, tj.: adres e-mail, hasło, typ konta (prywatne, firmowe, charytatywne).
- Uzupełnić dane osobowe i adresowe (poprawność danych będzie weryfikowana w późniejszym etapie).
- Aktywować konto przelewem w wysokości 10 PLN, dokonanym z konta bankowego zarejestrowanego na dane podane w formularzu rejestracyjnym. Aktywacja konta trwa około 24 godzin ze względu na godziny graniczne księgowania przelewów w różnych bankach.
Rejestracja serwisu
Serwis jest miejscem, w którym wykorzystywany będzie system PBL. Przed uzyskaniem dostępu do systemu każdy serwis musi zostać zaakceptowany przez HotPay. Zgłoszenie serwisu odbywa się przy uczestnictwie prostego formularza zlokalizowanego na tej podstronie: https://hotpay.pl/przelewy_sklep_nowy/. Pola, które należy wypełnić to:
- Nazwa serwisu – wewnętrzna nazwa używana w identyfikacji serwisu w HotPay oraz komunikowana klientowi podczas dokonywania płatności;
- Opis – opis usługi na potrzeby weryfikacji serwisu;
- Adres URL serwisu – w ramach którego będzie wykorzystywany system PBL;
- Regulamin serwisu – link do regulaminu sklepu przeznaczony dla konsumentów korzystających z usług sprzedawcy;
- Obsługa klienta – email – adres poczty elektronicznej, gdzie klienci mogą się kontaktować z podmiotem odpowiedzialnym za świadczoną usługę;
- Obsługa klienta – telefon – numer telefonu, pod którym klienci mogą kontaktować się z podmiotem odpowiedzialnym za świadczoną usługę. Po wysłaniu tego formularza system HotPay prześle na adres zarejestrowany przy zakładaniu konta email z linkiem potwierdzającym chęć zawarcia umowy na obsługę przelewów w serwisie. Po potwierdzeniu woli zawarcia umowy – serwis trafi do akceptacji po stronie HotPay.
Lista aktualnych serwisów oraz ich statusy znajdują się na poniżej zalinkowanej podstronie: https://hotpay.pl/przelewy_sklep_lista/.
Konfiguracja serwisu
Przed przystąpieniem do wdrażania systemu w ramach serwisu należy go najpierw skonfigurować. Jeśli serwis został zaakceptowany przez HotPay na podstronie z listą serwisów pojawi się jego pozycja. W celu konfiguracji należy kliknąć znaczek plusa w pierwszej kolumnie tabeli. Ukaże się sekret usługi używany do uwierzytelniania komunikacji oraz łącze „Pokaż więcej”, w które należy kliknąć. W ramach widoku, który ukaże się po kliknięciu na w/w przycisk będą dostępne następujące karty:
- lista transakcji;
- ustawienia:
- adres notyfikacji – adres URL, na który zostaną przesłane notyfikacje o nowych transakcjach;
- hasło notyfikacji – tajne hasło wykorzystane w generowaniu ID uwierzytelniającego pochodzenie notyfikacji oraz samą transakcję;
- API – czysty kod – przykładowy kod implementujący płatność w systemie PBL.
API
API z walidacją parametrów
sequenceDiagram
autonumber
Klient->>Sprzedawca: Zamówienie
Sprzedawca->>HotPay: Jawna inicjalizacja płatności
loop Procesowanie płatności
HotPay->>HotPay: Klient przeprowadza płatność
end
HotPay-->>Sprzedawca: Wysłanie notyfikacji
Note over Sprzedawca: Weryfikacja płatności
HotPay->>Sprzedawca: Powrót klienta do sklepu
Inicjalizacja płatności
Przekierowanie do panelu transakcyjnego
Adres URL: https://platnosc.hotpay.pl/
Content-Type: multipart/form-data
Dostępne metody: POST/GET
Opis użycia
| Zmienna | Wymagane | Opis zmiennej |
|---|---|---|
SEKRET |
TAK | Kod sekret do pobrania z panelu HotPay generowany dla każdego serwisu. |
KWOTA |
TAK | Kwota wywoływanej płatności. |
NAZWA_USLUGI |
TAK | Nazwa usługi/towaru |
ADRES_WWW |
NIE | Adres URL powrotu |
ID_ZAMOWIENIA |
TAK | Identyfikator zamówienia po stronie serwisu – nadawany przez właściciela serwisu. Ciąg znaków przesyłany w tej zmiennej nie może być dłuższy niż 64 znaki. |
EMAIL |
NIE | Email klienta |
DANE_OSOBOWE |
NIE | Dane osobowe klienta |
HASH |
TAK | HASH funkcji skrótu sha256, składającej się z elementów: "HASLOZUSTAWIEN".";" . $FORMULARZ["KWOTA"] . ";" . $FORMULARZ["NAZWA_USLUGI"] . ";" . $FORMULARZ["ADRES_WWW"] . ";" . $FORMULARZ["ID_ZAMOWIENIA"] . ";" . $FORMULARZ["SEKRET"] |
<?php
$HASLO_Z_USTAWIEN = 'XXX';
$FORMULARZ = [
'SEKRET' => 'XXX',
'KWOTA' => '1',
'NAZWA_USLUGI' => 'XXX',
'ADRES_WWW' => 'https://hotpay.pl',
'ID_ZAMOWIENIA' => 'ZAM-123',
'EMAIL' => '',
'DANE_OSOBOWE' => '',
];
$FORMULARZ['HASH'] = hash('sha256', implode(';', [
$HASLO_Z_USTAWIEN,
$FORMULARZ['KWOTA'],
$FORMULARZ['NAZWA_USLUGI'],
$FORMULARZ['ADRES_WWW'],
$FORMULARZ['ID_ZAMOWIENIA'],
$FORMULARZ['SEKRET'],
]));
echo '<form id="order" action="https://platnosc.hotpay.pl/" method="post" enctype="multipart/form-data">';
foreach ($FORMULARZ as $klucz => $wartosc) {
echo '<input name="'
. htmlspecialchars($klucz, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')
. '" value="'
. htmlspecialchars($wartosc, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')
. '" type="hidden">';
}
echo '<button type="submit">DALEJ</button></form>';
Odbiór notyfikacji
Notyfikacje są wysyłane metodą POST typu form-data na adres WWW podany w ustawieniach usługi.
Zasady konfiguracji odbioru, weryfikacji danych i obsługi ponowień opisano na stronie Notyfikacje.
Opis użycia
| Zmienna | Opis zmiennej |
|---|---|
SEKRET |
Kod sekret do pobrania z panelu HotPay generowany dla każdego serwisu. |
KWOTA |
Kwota wywoływanej płatności. |
STATUS |
Status płatności: SUCCESS – płatność zaakceptowana; PENDING – płatność oczekująca; FAILURE – płatność odrzucona. |
ID_ZAMOWIENIA |
Identyfikator zamówienia po stronie serwisu – nadawany przez właściciela serwisu. Ciąg znaków przesyłany w tej zmiennej nie może być dłuższy niż 64 znaki. |
ID_PLATNOSCI |
Unikalny identyfikator płatności |
SECURE |
Identyfikator bezpiecznej transakcji |
HASH |
HASH funkcji skrótu sha256, składającej się z elementów: HASLO_Z_USTAWIEN.";".$_POST["KWOTA"].";".$_POST["ID_PLATNOSCI"].";".$_POST["ID_ZAMOWIENIA"].";".$_POST["STATUS"].";".$_POST["SECURE"].";".$_POST["SEKRET"] |
<?php
$HASLO_Z_USTAWIEN="XXX";
if(!empty($_POST["KWOTA"]) &&
!empty($_POST["ID_PLATNOSCI"]) &&
!empty($_POST["ID_ZAMOWIENIA"]) &&
!empty($_POST["STATUS"]) &&
!empty($_POST["SEKRET"]) &&
!empty($_POST["SECURE"]) &&
!empty($_POST["HASH"])
){
if(hash("sha256",$HASLO_Z_USTAWIEN.";".$_POST["KWOTA"].";".$_POST["ID_PLATNOSCI"].";".$_POST["ID_ZAMOWIENIA"].";".$_POST["STATUS"].";".$_POST["SECURE"].";".$_POST["SEKRET"]) == $_POST["HASH"]){
//komunikacja poprawna
if($_POST["STATUS"]=="SUCCESS"){
//płatność zaakceptowana
}else if($_POST["STATUS"]=="FAILURE"){
//odrzucone
}
}
}
API zaawansowane z walidacją parametrów
sequenceDiagram
autonumber
Klient->>Sprzedawca: Zamówienie
Sprzedawca->>HotPay: Rejestracja transakcji
HotPay->>Sprzedawca: Otrzymanie odpowiedzi
Sprzedawca->>HotPay: Przekierowanie klienta
loop Procesowanie płatności
HotPay->>HotPay: Klient przeprowadza płatność
end
HotPay-->>Sprzedawca: Wysłanie notyfikacji
Note over Sprzedawca: Weryfikacja płatności
HotPay->>Sprzedawca: Powrót klienta do sklepu
Inicjalizacja płatności
Przekierowanie do panelu transakcyjnego
Adres URL: https://platnosc.hotpay.pl/
Content-Type: multipart/form-data
Dostępne metody: POST/GET
Opis użycia
| Zmienna | Wymagane | Opis zmiennej |
|---|---|---|
SEKRET |
TAK | Kod sekret do pobrania z panelu HotPay generowany dla każdego serwisu. |
KWOTA |
TAK | Kwota wywoływanej płatności. |
NAZWA_USLUGI |
TAK | Nazwa usługi/towaru |
ADRES_WWW |
NIE | Adres URL powrotu |
ID_ZAMOWIENIA |
TAK | Identyfikator zamówienia po stronie serwisu – nadawany przez właściciela serwisu. Ciąg znaków przesyłany w tej zmiennej nie może być dłuższy niż 64 znaki. |
TYP |
TAK | Wartość: INIT |
EMAIL |
NIE | Email klienta |
DANE_OSOBOWE |
NIE | Dane osobowe klienta |
HASH |
TAK | HASH funkcji skrótu sha256, składającej się z elementów: "HASLOZUSTAWIEN".";" . $FORMULARZ["KWOTA"] . ";" . $FORMULARZ["NAZWA_USLUGI"] . ";" . $FORMULARZ["ADRES_WWW"] . ";" . $FORMULARZ["ID_ZAMOWIENIA"] . ";" . $FORMULARZ["SEKRET"] |
<?php
$HASLO_Z_USTAWIEN = 'XXX';
$FORMULARZ = [
'SEKRET' => 'XXX',
'KWOTA' => '1',
'NAZWA_USLUGI' => 'XXX',
'ADRES_WWW' => 'https://hotpay.pl',
'ID_ZAMOWIENIA' => 'ZAM-123',
'TYP' => 'INIT',
'EMAIL' => '',
'DANE_OSOBOWE' => '',
];
$FORMULARZ['HASH'] = hash('sha256', implode(';', [
$HASLO_Z_USTAWIEN,
$FORMULARZ['KWOTA'],
$FORMULARZ['NAZWA_USLUGI'],
$FORMULARZ['ADRES_WWW'],
$FORMULARZ['ID_ZAMOWIENIA'],
$FORMULARZ['SEKRET'],
]));
$ch = curl_init('https://platnosc.hotpay.pl/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $FORMULARZ,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
]);
$wynik = curl_exec($ch);
$kodHttp = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($wynik === false) {
$blad = curl_error($ch);
curl_close($ch);
throw new RuntimeException('Błąd połączenia z API HotPay: ' . $blad);
}
curl_close($ch);
if ($kodHttp < 200 || $kodHttp >= 300) {
throw new RuntimeException('API HotPay zwróciło HTTP ' . $kodHttp);
}
$odpowiedz = json_decode($wynik, true, 512, JSON_THROW_ON_ERROR);
if (!is_array($odpowiedz) || !is_bool($odpowiedz['STATUS'] ?? null)) {
throw new UnexpectedValueException('Nieprawidłowy format odpowiedzi API HotPay.');
}
if ($odpowiedz['STATUS'] === true) {
if (!is_string($odpowiedz['URL'] ?? null) || $odpowiedz['URL'] === '') {
throw new UnexpectedValueException('Brak adresu płatności w odpowiedzi.');
}
echo '<a href="'
. htmlspecialchars($odpowiedz['URL'], ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')
. '">Zapłać</a>';
} else {
$wiadomosc = is_string($odpowiedz['WIADOMOSC'] ?? null)
? $odpowiedz['WIADOMOSC']
: 'Nie udało się utworzyć płatności.';
echo htmlspecialchars($wiadomosc, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
}
Przykład wymaga Node.js 20 lub nowszego z natywnym FormData oraz pakietu axios.
import axios from 'axios';
import { createHash } from 'node:crypto';
const HASLO_Z_USTAWIEN = 'XXX';
const FORMULARZ = {
SEKRET: 'XXX',
KWOTA: '1',
NAZWA_USLUGI: 'XXX',
ADRES_WWW: 'https://hotpay.pl',
ID_ZAMOWIENIA: 'ZAM-123',
EMAIL: '',
DANE_OSOBOWE: '',
TYP: 'INIT',
};
const form = new FormData();
for (const [nazwa, wartosc] of Object.entries(FORMULARZ)) {
form.append(nazwa, wartosc);
}
form.append('HASH', createHash('sha256').update([
HASLO_Z_USTAWIEN,
FORMULARZ.KWOTA,
FORMULARZ.NAZWA_USLUGI,
FORMULARZ.ADRES_WWW,
FORMULARZ.ID_ZAMOWIENIA,
FORMULARZ.SEKRET,
].join(';')).digest('hex'));
axios.request({
method: 'POST',
url: 'https://platnosc.hotpay.pl/',
data: form,
responseType: 'json',
timeout: 15000,
}).then(({ data: odpowiedz }) => {
if (!odpowiedz || typeof odpowiedz.STATUS !== 'boolean') {
throw new Error('Nieprawidłowy format odpowiedzi API HotPay.');
}
if (odpowiedz.STATUS !== true) {
throw new Error(odpowiedz.WIADOMOSC || 'Nie udało się utworzyć płatności.');
}
if (typeof odpowiedz.URL !== 'string' || odpowiedz.URL === '') {
throw new Error('Brak adresu płatności w odpowiedzi.');
}
console.log('ADRES PŁATNOŚCI: ' + odpowiedz.URL);
}).catch((blad) => {
console.error(blad.message);
});
Odbiór notyfikacji
Notyfikacje są wysyłane metodą POST typu form-data na adres WWW podany w ustawieniach usługi.
Zasady konfiguracji odbioru, weryfikacji danych i obsługi ponowień opisano na stronie Notyfikacje.
Uwaga
Pamiętaj o weryfikacji danych przychodzących.
Uwaga
Notyfikacje są wysyłane z góry ustalonych adresów IP, prosimy dodać je do whitelisty:
- 18.197.55.26
- 3.126.108.86
- 3.64.128.101
- 18.184.99.42
- 3.72.152.155
- 35.159.7.168
Opis użycia
| Zmienna | Opis zmiennej |
|---|---|
SEKRET |
Kod sekret do pobrania z panelu HotPay generowany dla każdego serwisu. |
KWOTA |
Kwota wywoływanej płatności. |
STATUS |
Status płatności: SUCCESS – płatność zaakceptowana; PENDING – płatność oczekująca; FAILURE – płatność odrzucona. |
ID_ZAMOWIENIA |
Identyfikator zamówienia po stronie serwisu – nadawany przez właściciela serwisu. Ciąg znaków przesyłany w tej zmiennej nie może być dłuższy niż 64 znaki. |
ID_PLATNOSCI |
Unikalny identyfikator płatności |
SECURE |
Identyfikator bezpiecznej transakcji |
HASH |
HASH funkcji skrótu sha256, składającej się z elementów: HASLO_Z_USTAWIEN.";".$_POST["KWOTA"].";".$_POST["ID_PLATNOSCI"].";".$_POST["ID_ZAMOWIENIA"].";".$_POST["STATUS"].";".$_POST["SECURE"].";".$_POST["SEKRET"] |
<?php
$HASLO_Z_USTAWIEN="XXX";
if(!empty($_POST["KWOTA"]) &&
!empty($_POST["ID_PLATNOSCI"]) &&
!empty($_POST["ID_ZAMOWIENIA"]) &&
!empty($_POST["STATUS"]) &&
!empty($_POST["SEKRET"]) &&
!empty($_POST["SECURE"]) &&
!empty($_POST["HASH"])
){
if(hash("sha256",$HASLO_Z_USTAWIEN.";".$_POST["KWOTA"].";".$_POST["ID_PLATNOSCI"].";".$_POST["ID_ZAMOWIENIA"].";".$_POST["STATUS"].";".$_POST["SECURE"].";".$_POST["SEKRET"]) == $_POST["HASH"]){
//komunikacja poprawna
if($_POST["STATUS"]=="SUCCESS"){
//płatność zaakceptowana
}else if($_POST["STATUS"]=="FAILURE"){
//odrzucone
}
}
}
API bez walidacji
sequenceDiagram
autonumber
Klient->>Sprzedawca: Zamówienie
Sprzedawca->>HotPay: Jawna inicjalizacja płatności
loop Procesowanie płatności
HotPay->>HotPay: Klient przeprowadza płatność
end
HotPay-->>Sprzedawca: Wysłanie notyfikacji
Note over Sprzedawca: Weryfikacja płatności
HotPay->>Sprzedawca: Powrót klienta do sklepu
Inicjalizacja płatności
Przekierowanie do panelu transakcyjnego
Adres URL: https://platnosc.hotpay.pl/
Content-Type: multipart/form-data
Dostępne metody: POST/GET
Opis użycia
| Zmienna | Wymagane | Opis zmiennej |
|---|---|---|
SEKRET |
TAK | Kod sekret do pobrania z panelu HotPay generowany dla każdego serwisu. |
KWOTA |
TAK | Kwota wywoływanej płatności. |
NAZWA_USLUGI |
TAK | Nazwa usługi/towaru |
ADRES_WWW |
NIE | Adres URL powrotu |
ID_ZAMOWIENIA |
TAK | Identyfikator zamówienia po stronie serwisu – nadawany przez właściciela serwisu. Ciąg znaków przesyłany w tej zmiennej nie może być dłuższy niż 64 znaki. |
EMAIL |
NIE | Email klienta |
DANE_OSOBOWE |
NIE | Dane osobowe klienta |
<form id="order" action="https://platnosc.hotpay.pl/" method="post">
<input required name="SEKRET" value="SEKRET_USLUGI"
type="hidden">
<input required name="KWOTA" value="1" type="hidden">
<input required name="NAZWA_USLUGI" value="XXX"
type="hidden">
<input required name="ADRES_WWW" value="XXX" type="hidden">
<input required name="ID_ZAMOWIENIA" value="XXX"
type="hidden">
<input name="EMAIL" value="" type="hidden">
<input name="DANE_OSOBOWE" value="" type="hidden">
<button type="submit">DALEJ</button>
</form>
Odbiór notyfikacji
Notyfikacje są wysyłane metodą POST typu form-data na adres WWW podany w ustawieniach usługi.
Zasady konfiguracji odbioru, weryfikacji danych i obsługi ponowień opisano na stronie Notyfikacje.
Uwaga
Pamiętaj o weryfikacji danych przychodzących.
Uwaga
Notyfikacje są wysyłane z góry ustalonych adresów IP, prosimy dodać je do whitelisty:
- 18.197.55.26
- 3.126.108.86
- 3.64.128.101
- 18.184.99.42
- 3.72.152.155
- 35.159.7.168
Opis użycia
| Zmienna | Opis zmiennej |
|---|---|
SEKRET |
Kod sekret do pobrania z panelu HotPay generowany dla każdego serwisu. |
KWOTA |
Kwota wywoływanej płatności. |
STATUS |
Status płatności: SUCCESS – płatność zaakceptowana; PENDING – płatność oczekująca; FAILURE – płatność odrzucona. |
ID_ZAMOWIENIA |
Identyfikator zamówienia po stronie serwisu – nadawany przez właściciela serwisu. Ciąg znaków przesyłany w tej zmiennej nie może być dłuższy niż 64 znaki. |
ID_PLATNOSCI |
Unikalny identyfikator płatności |
HASH |
HASH funkcji skrótu sha256, składającej się z elementów: HASLO_Z_USTAWIEN.";".$_POST["KWOTA"].";".$_POST["ID_PLATNOSCI"].";".$_POST["ID_ZAMOWIENIA"].";".$_POST["STATUS"].";".$_POST["SEKRET"] |
<?php
$HASLO_Z_USTAWIEN="XXX";
if(!empty($_POST["KWOTA"]) &&
!empty($_POST["ID_PLATNOSCI"]) &&
!empty($_POST["ID_ZAMOWIENIA"]) &&
!empty($_POST["STATUS"]) &&
!empty($_POST["SEKRET"]) &&
!empty($_POST["HASH"])
){
if(hash("sha256",$HASLO_Z_USTAWIEN.";".$_POST["KWOTA"].";".$_POST["ID_PLATNOSCI"].";".$_POST["ID_ZAMOWIENIA"].";".$_POST["STATUS"].";".$_POST["SEKRET"]) == $_POST["HASH"]){
//komunikacja poprawna
if($_POST["STATUS"]=="SUCCESS"){
//płatność zaakceptowana
}else if($_POST["STATUS"]=="FAILURE"){
//odrzucone
}
}
}