Konto
Wprowadzenie
API konta umożliwia pobieranie informacji o transakcjach przelewowych oraz wykonywanie ich zwrotów. Pobranie danych transakcji jest możliwe na podstawie identyfikatora płatności nadanego przez HotPay lub własnego identyfikatora zamówienia.
Opis inicjowania płatności i odbierania notyfikacji znajduje się na stronie Przelewy.
Dane dostępowe
Do wykonania obu operacji wymagane są:
API_KEY– klucz API dostępny w ustawieniach konta HotPay.USLUGA– sekret usługi, której dotyczy transakcja. Jest to sekret wykorzystywany jakoSEKRETprzy inicjowaniu płatności przelewowej.
API
Przelewy
Pobieranie
Pobieranie transakcji
Adres URL: https://api.hotpay.pl/KONTO/PRZELEW/
Content-Type: multipart/form-data
Dostępne metody: POST
Format odpowiedzi: JSON
W żądaniu należy przekazać dane dostępowe oraz jeden z identyfikatorów: ID_PLATNOSCI lub ID_ZAMOWIENIA.
Opis użycia
| Zmienna | Wymagane | Opis zmiennej |
|---|---|---|
API_KEY |
TAK | Klucz API dostępny w ustawieniach konta HotPay. |
USLUGA |
TAK | Sekret usługi, której dotyczy transakcja. |
ID_PLATNOSCI |
Warunkowo | Identyfikator płatności nadany przez HotPay. Wymagany, jeśli nie przekazano ID_ZAMOWIENIA. |
ID_ZAMOWIENIA |
Warunkowo | Własny identyfikator zamówienia przekazany przy inicjowaniu płatności. Stosowany zamiast ID_PLATNOSCI. |
<?php
$ch = curl_init("https://api.hotpay.pl/KONTO/PRZELEW/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'API_KEY' => 'XXX',
'USLUGA' => 'XXX',
'ID_PLATNOSCI' => 'XXX'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
$result = curl_exec($ch);
if ($result === false) {
$blad = curl_error($ch);
curl_close($ch);
throw new RuntimeException('Błąd połączenia z API HotPay: ' . $blad);
}
curl_close($ch);
$odpowiedz = json_decode($result, true, 512, JSON_THROW_ON_ERROR);
if (($odpowiedz['STATUS'] ?? false) !== true) {
throw new RuntimeException(
$odpowiedz['WIADOMOSC'] ?? 'Nie udało się pobrać transakcji.'
);
}
$transakcje = $odpowiedz['TRANSAKCJE'];
// Dane transakcji są dostępne w tablicy $transakcje.
Aby pobrać dane na podstawie własnego identyfikatora zamówienia, w przykładzie PHP zamień tablicę przekazywaną do CURLOPT_POSTFIELDS na:
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'API_KEY' => 'XXX',
'USLUGA' => 'XXX',
'ID_ZAMOWIENIA' => 'ZAM-123'
]);
Identyfikator ID_PLATNOSCI potrzebny do zwrotu odczytasz z pola ID_PLATNOSCI w odpowiednim elemencie tablicy TRANSAKCJE.
Odpowiedź
Odpowiedź API
{
"STATUS": true,
"WIADOMOSC": "",
"TRANSAKCJE": [
{
"ID_PLATNOSCI": "xxx",
"ID_ZAMOWIENIA": "ZAM-123",
"DATA_START": "xxx",
"DATA_AKTUALIZACJA": "xxx",
"KWOTA": 10,
"KWOTA_SALDO": 10,
"STATUS": "xxx",
"EMAIL": "[email protected]",
"DANE_OSOBOWE": "xxx"
}
]
}
Wartości są przykładowe. Zapis xxx zastępuje dane zwracane przez API, w tym daty oraz status transakcji.
| Zmienna | Opis zmiennej |
|---|---|
STATUS |
Wynik wykonania zapytania. Wartość true oznacza poprawne pobranie danych. |
WIADOMOSC |
Komunikat zwrócony przez API. |
TRANSAKCJE |
Tablica zawierająca dane transakcji. |
Każdy element tablicy TRANSAKCJE zawiera następujące pola:
| Zmienna | Opis zmiennej |
|---|---|
ID_PLATNOSCI |
Identyfikator płatności nadany przez HotPay. Wykorzystywany przy wykonywaniu zwrotu. |
ID_ZAMOWIENIA |
Własny identyfikator zamówienia przekazany przy inicjowaniu płatności. |
DATA_START |
Data rozpoczęcia transakcji. |
DATA_AKTUALIZACJA |
Data aktualizacji transakcji. |
KWOTA |
Kwota transakcji. |
KWOTA_SALDO |
Kwota salda zwrócona przez API dla transakcji. |
STATUS |
Status transakcji. |
EMAIL |
Adres e-mail powiązany z transakcją. |
DANE_OSOBOWE |
Dane osobowe powiązane z transakcją. |
Wynik zapytania a status płatności
Pole STATUS na poziomie odpowiedzi określa wynik zapytania do API. Status samej płatności znajduje się w polu STATUS wewnątrz elementu tablicy TRANSAKCJE. Poprawne pobranie danych nie oznacza, że płatność została zaakceptowana.
Zwrot
Do wykonania zwrotu wymagany jest identyfikator płatności ID_PLATNOSCI oraz kwota zwrotu. Jeżeli znasz wyłącznie własny identyfikator zamówienia, najpierw pobierz informacje o transakcji, przekazując ID_ZAMOWIENIA do endpointu pobierania transakcji.
Zwrot transakcji
Adres URL: https://api.hotpay.pl/KONTO/PRZELEW/ZWROT
Content-Type: multipart/form-data
Dostępne metody: POST
Format odpowiedzi: JSON
Opis użycia
| Zmienna | Wymagane | Opis zmiennej |
|---|---|---|
API_KEY |
TAK | Klucz API dostępny w ustawieniach konta HotPay. |
USLUGA |
TAK | Sekret usługi, której dotyczy transakcja. |
ID_PLATNOSCI |
TAK | Identyfikator płatności nadany przez HotPay. |
KWOTA |
TAK | Kwota zwrotu w PLN w formacie dziesiętnym. Dla zwrotu 10 PLN należy przekazać wartość 10. |
<?php
$ch = curl_init("https://api.hotpay.pl/KONTO/PRZELEW/ZWROT");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'API_KEY' => 'XXX',
'USLUGA' => 'XXX',
'ID_PLATNOSCI' => 'XXX',
'KWOTA' => '10'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
$result = curl_exec($ch);
if ($result === false) {
$blad = curl_error($ch);
curl_close($ch);
throw new RuntimeException('Błąd połączenia z API HotPay: ' . $blad);
}
curl_close($ch);
$odpowiedz = json_decode($result, true, 512, JSON_THROW_ON_ERROR);
if (($odpowiedz['STATUS'] ?? false) !== true) {
throw new RuntimeException(
$odpowiedz['WIADOMOSC'] ?? 'Nie udało się wykonać zwrotu.'
);
}
// API potwierdziło poprawny zwrot transakcji.
Odpowiedź
Odpowiedź API
{
"STATUS": true,
"WIADOMOSC": "xxx"
}
Wartość true oznacza poprawny zwrot transakcji. Zapis xxx zastępuje treść komunikatu zwróconego przez API.
| Zmienna | Opis zmiennej |
|---|---|
STATUS |
Wynik przyjęcia zwrotu. Wartość true oznacza poprawne przyjęcie. |
WIADOMOSC |
Komunikat zwrócony przez API. |