Docs
Powered by

Portfel, Płatności i Sklep (Billing & Shop API)

In 

Interfejs programistyczny do zarządzania wirtualnym portfelem wPLN, generowania intencji doładowań płatniczych (Stripe, krypto LTC), przelewów P2P między użytkownikami oraz pobierania aktualnego katalogu produktów ze sklepu.

1. Saldo portfela i historia transakcji (/v1/wallet)

Zwraca bieżące saldo wPLN konta, status użytkownika oraz stronicowaną historię transakcji (doładowania, zakupy, odnowienia, przelewy).

  • Metoda: GET
  • Ścieżka: /v1/wallet
  • Wymagany scope: account:read lub account:billing
  • Parametry query (opcjonalne):
    • cursor — ID transakcji jako kursor do paginacji (np. ?cursor=120)

Przykład zapytania cURL

curl -X GET "https://api.blackhost.pl/v1/wallet" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "wpln": 150.00,
  "status": "active",
  "transactions": [
    {
      "id": 142,
      "user_id": 12,
      "amount": 50.00,
      "type": "deposit",
      "description": "Doładowanie portfela Stripe",
      "stripe_session_id": "cs_live_a1b2c3...",
      "created_at": "2026-10-30T14:20:00.000Z"
    },
    {
      "id": 141,
      "user_id": 12,
      "amount": -29.00,
      "type": "service_renewal",
      "description": "Odnowienie serwera VPS vps-8f92a1",
      "stripe_session_id": null,
      "created_at": "2026-10-28T10:15:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null,
    "pageSize": 20
  }
}

2. Rozpoczęcie doładowania portfela (/v1/wallet/topup)

Inicjalizuje proces doładowania salda konta i zwraca adres przekierowania do płatności lub dane transakcji.

  • Metoda: POST
  • Ścieżka: /v1/wallet/topup
  • Wymagany scope: account:billing
  • Nagłówek: Content-Type: application/json

Parametry w ciele zapytania:

Pole Typ Wymagane Opis
amount Liczba Tak Kwota doładowania w PLN (np. 50.00, maks. 2 miejsca po przecinku)
provider String Nie Identyfikator bramki płatności: stripe (domyślnie) lub crypto_ltc
code String Nie Opcjonalny kod rabatowy / promocyjny / kod polecającego

Przykład zapytania cURL

curl -X POST "https://api.blackhost.pl/v1/wallet/topup" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "provider": "stripe"
  }'

3. Przelew wewnętrzny P2P (/v1/wallet/transfer)

Umożliwia błyskawiczne przekazanie środków wPLN innemu zarejestrowanemu użytkownikowi platformy BlackHost bez prowizji.

  • Metoda: POST
  • Ścieżka: /v1/wallet/transfer
  • Wymagany scope: account:billing
  • Nagłówek: Content-Type: application/json

Parametry w ciele zapytania:

Pole Typ Wymagane Opis
amount Liczba Tak Kwota przelewu w wPLN (min. 1.00 wPLN)
recipientEmail String Opcjonalnie* Adres e-mail odbiorcy w platformie BlackHost
recipientId Liczba Opcjonalnie* ID numeryczne konta odbiorcy (*wymagany co najmniej jeden z identyfikatorów)

Przykład zapytania cURL

curl -X POST "https://api.blackhost.pl/v1/wallet/transfer" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "[email protected]",
    "amount": 25.00
  }'

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "message": "Przelew w kwocie 25.00 wPLN został pomyślnie zrealizowany.",
  "newBalance": 125.00
}

4. Dostępne bramki i metody płatności (/v1/payments/providers)

Pobiera listę aktualnie włączonych bramek płatniczych wraz z limitami minimalnych i maksymalnych kwot.

  • Metoda: GET
  • Ścieżka: /v1/payments/providers
  • Wymagany scope: account:read lub account:billing

Przykład zapytania cURL

curl -X GET "https://api.blackhost.pl/v1/payments/providers" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "providers": [
    {
      "id": "stripe",
      "name": "Karty płatnicze, BLIK i Przelewy24 (Stripe)",
      "type": "fiat",
      "currency": "PLN",
      "minAmount": 5.00,
      "maxAmount": 2000.00,
      "available": true
    },
    {
      "id": "crypto_ltc",
      "name": "Litecoin (LTC)",
      "type": "crypto",
      "currency": "LTC",
      "minAmount": 10.00,
      "maxAmount": 5000.00,
      "available": true
    }
  ]
}

5. Katalog pakietów i sklep (/v1/shop/packets)

Zwraca kompletną ofertę sklepu: dostępne plany serwerów gier oraz maszyn VPS, specyfikacje sprzętowe, przydziały CPU/RAM/NVMe, lokalizacje serwerów oraz aktywne zniżki i promocje (w tym najniższą cenę z ostatnich 30 dni – Omnibus).

  • Metoda: GET
  • Ścieżka: /v1/shop/packets
  • Wymagany scope: account:read

Przykład zapytania cURL

curl -X GET "https://api.blackhost.pl/v1/shop/packets" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN"

Struktura odpowiedzi:

  • categories — grupy ofertowe (vps, minecraft, bot, itp.)
  • locations — dostępne centra danych (np. Polska Warszawa WAW-1, Frankfurt FRA)
  • packets — lista pakietów zawierająca:
    • id — unikalny identyfikator pakietu (niezbędny przy składaniu zamówień i uaktualnieniach)
    • name — nazwa pakietu (np. VPS NVMe #2, Minecraft Dirt)
    • ram_mb, cpu, disk_gb — zasoby sprzętowe
    • price — cena bazowa w wPLN
    • promotionalPrice — obniżona cena przy aktywnych akcjach promocyjnych
    • omnibusLowestPrice30d — najniższa cena w ostatnich 30 dniach