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

ZmiennePHP

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
$FORMULARZ = [
"SEKRET" => "XXX,",
"KWOTA" => "1",
"NAZWA_USLUGI" => "XXX",
"ADRES_WWW" => "https://hotpay.pl",
"ID_ZAMOWIENIA" => "XXX",
"EMAIL" => "",
"DANE_OSOBOWE" => "",
];

echo '<form id="order" action="https://platnosc.hotpay.pl/" method="post">';
foreach ($FORMULARZ as $klucz=>$value){
    echo '<input name="'.$klucz.'" value="'.$value.'" type="hidden">';
}
// HASH funkcji skrótu sha256, składającej się z hash("sha256","HASLOZUSTAWIEN".";" . $FORMULARZ["KWOTA"] . ";" . $FORMULARZ["NAZWA_USLUGI"] . ";" . $FORMULARZ["ADRES_WWW"] . ";" . $FORMULARZ["ID_ZAMOWIENIA"] . ";" . $FORMULARZ["SEKRET"])

echo '<input name="HASH" required value="'.hash("sha256", "HASLOZUSTAWIEN".";" . $FORMULARZ["KWOTA"] . ";" . $FORMULARZ["NAZWA_USLUGI"] . ";" . $FORMULARZ["ADRES_WWW"] . ";" . $FORMULARZ["ID_ZAMOWIENIA"] . ";" . $FORMULARZ["SEKRET"]).'" 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.

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

ZmiennePHP

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

ZmiennePHP CURLNODEJS

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" => "XXX",
"EMAIL" => "",
"DANE_OSOBOWE" => "",
"TYP" => "INIT",
];

$FORMULARZ["HASH"]=hash("sha256", $HASLO_Z_USTAWIEN . ";" . $FORMULARZ["KWOTA"] . ";" . $FORMULARZ["NAZWA_USLUGI"] . ";" . $FORMULARZ["ADRES_WWW"] . ";" . $FORMULARZ["ID_ZAMOWIENIA"] . ";" . $FORMULARZ["SEKRET"]);
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,"https://platnosc.hotpay.pl/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,$FORMULARZ);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec($ch);
curl_close ($ch);
if(!empty($server_output)){
    $JSON=json_decode($server_output,true);
    if(!empty($JSON["STATUS"])){
    if($JSON["STATUS"] == true){
        echo '<a href="'.$JSON["URL"].'">Zapłać</a>';
    }else{
        // BŁĄD
        echo $JSON["WIADOMOSC"];
    }
    }
}

import axios from "axios";
import { createHash } from 'node:crypto'

let FORMULARZ = {
    "SEKRET" : "XXX,",
    "KWOTA" : "1",
    "NAZWA_USLUGI" : "XXX",
    "ADRES_WWW" : "https://hotpay.pl",
    "ID_ZAMOWIENIA" : "XXX",
    "EMAIL" : "",
    "DANE_OSOBOWE" : "",
    "TYP" : "INIT"
};

const form = new FormData();
form.append("KWOTA", FORMULARZ.KWOTA);
form.append("NAZWA_USLUGI", FORMULARZ.NAZWA_USLUGI);
form.append("ADRES_WWW", FORMULARZ.ADRES_WWW);
form.append("ID_ZAMOWIENIA", FORMULARZ.ID_ZAMOWIENIA);
form.append("SEKRET", FORMULARZ.SEKRET);
form.append("TYP", "INIT");
form.append("HASH", createHash('sha2-256').update("HASLO_Z_USTAWIEN"+";"+FORMULARZ.KWOTA+";"+FORMULARZ.NAZWA_USLUGI+";"+FORMULARZ.ADRES_WWW+";"+FORMULARZ.ID_ZAMOWIENIA+";"+FORMULARZ.SEKRET).digest('hex'));
const options = {
method: 'POST',
url: 'https://platnosc.hotpay.pl/',
headers: {'Content-Type': 'multipart/form-data;'},
data: '[form]'
};
axios.request(options).then(function (response) {
    try {
    var ob = JSON.parse(response.data);
        if (ob && typeof ob === "object") {
           if(ob.STATUS){
            console.log("ADRES PLATNOSCI: "+ob.URL);
           }
        }
    }
    catch (e) {
        console.log(response.data);
        console.log(e);
    }


}).catch(function (error) {
console.error(error);
});

Odbiór notyfikacji

Notyfikacje są wysyłane metodą POST typu form-data na adres WWW podany w ustawieniach usługi.

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

ZmiennePHP

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

ZmienneHTML

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.

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

ZmiennePHP

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