Przejdź do treści

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 jako SEKRET przy 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.