Przejdź do treści

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
         }
        }
    }