На цій сторінці1. Saldo portfela i historia transakcji (`/v1/wallet`)

Portfel, Płatności i Sklep

Останнє оновлення 21 листопада 2026 р.

Ця стаття ще недоступна вашою мовою - показуємо польську версію.

Interfejs programistyczny do zarządzania wirtualnym portfelem wPLN, inicjowania doładowań przez zunifikowany endpoint płatności (Stripe, krypto LTC) wraz ze śledzeniem statusu intencji, przelewów P2P między użytkownikami oraz pobierania aktualnego katalogu produktów ze sklepu.

ℹ️ Szukasz instrukcji płatności z poziomu panelu klienta, bez API? Zobacz Płatności i portfel wPLN.


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. Doładowanie portfela (/v1/payments/create)

Jednolity endpoint inicjowania doładowania dla wszystkich dostępnych dostawców płatności. Obsługuje przekierowania do bramki Stripe oraz intencje krypto Litecoin.

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

Parametry w ciele zapytania:

PoleTypWymaganeOpis
providerStringNieDostawca płatności: stripe (domyślnie) lub crypto_ltc
amountLiczbaTakKwota doładowania w PLN (dla Stripe od 2.00 do 10000.00; maks. 2 miejsca po przecinku)
codeStringNieOpcjonalny kod rabatowy / promocyjny / kod polecającego

Dostępność według metody uwierzytelnienia:

DostawcaSesja panelu (ciasteczko)Klucz API (PAT)
stripe✅✅
crypto_ltc✅❌ (403 payments.providerPanelOnly)

⚠️ Płatności krypto mogą być inicjowane wyłącznie z panelu klienta - każda intencja LTC derYWuje nowy adres on-chain, więc automatyzacja przez API jest celowo zablokowana. Przez PAT dostępny jest wyłącznie provider stripe.

Przykład zapytania cURL (Stripe)

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

Przykład odpowiedzi (200 OK) - Stripe

{
  "success": true,
  "intentId": 1042,
  "provider": "stripe",
  "currency": "PLN",
  "amountSource": 50,
  "amountWpln": 50,
  "bonusWpln": 0,
  "exchangeRate": 1,
  "expiresAt": "2026-11-10T13:00:00.000Z",
  "redirectUrl": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3..."
}

Pole redirectUrl to jednorazowy adres sesji Stripe Checkout (ważny 60 minut) - przekieruj na niego użytkownika, aby dokończył płatność. Rozliczenie (uznanie portfela wPLN) następuje automatycznie po stronie serwera przez webhook Stripe; postęp możesz śledzić endpointem /v1/payments/{id}/status (#3-status-intencji-p%C5%82atno%C5%9Bci-v1paymentsidstatus).

Przykład odpowiedzi (200 OK) - Litecoin

{
  "success": true,
  "intentId": 1043,
  "provider": "crypto_ltc",
  "currency": "LTC",
  "amountSource": 0.74310615,
  "amountWpln": 50,
  "bonusWpln": 0,
  "exchangeRate": 67.28,
  "expiresAt": "2026-11-10T12:30:00.000Z",
  "cryptoAddress": "LTC1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "qrCodeValue": "litecoin:LTC1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX?amount=0.74310615"
}

Dla krypto wyślij dokładnie amountSource LTC na cryptoAddress w ciągu 30 minut (potrzebne 2 potwierdzenia sieci). Status sprawdzaj pollingiem endpointu /v1/payments/{id}/status (#3-status-intencji-p%C5%82atno%C5%9Bci-v1paymentsidstatus).

ℹ️ Kompatybilność wstecz: endpoint POST /v1/wallet/topup (tylko Stripe, zawsze zwraca { success, url }) pozostaje utrzymany jako alias - zalecamy jednak POST /v1/payments/create.


3. Status intencji płatności (/v1/payments/{id}/status)

Zwraca aktualny stan intencji doładowania utworzonej przez /v1/payments/create. Obsługiwane zarówno dla płatności Stripe, jak i krypto.

  • Metoda: GET
  • Ścieżka: /v1/payments/{id}/status
  • Parametr {id}: identyfikator intencji (intentId z odpowiedzi na utworzenie)
  • Wymagany scope: account:read lub account:billing
  • Dostęp: właściciel intencji; administrator widzi intencje wszystkich użytkowników

Cykl życia intencji:

StatusOpis
pendingIntencja oczekuje na płatność
detectedŚrodki odebrane, ale jeszcze nie rozliczone (krypto: czekanie na potwierdzenia; Stripe: opłacone, webhook w trakcie księgowania)
settledRozliczone - portfel wPLN został uznany
expiredUpłynął czas ważności intencji bez płatności

Przykład zapytania cURL

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

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "intentId": 1042,
  "status": "settled",
  "amountSource": 50,
  "amountReceived": 50,
  "amountWpln": 50,
  "bonusWpln": 0,
  "currency": "PLN",
  "isSettled": true,
  "settledAt": "2026-11-10T12:05:33.000Z",
  "timeRemainingSeconds": 0
}

ℹ️ Dla krypto odpowiedź zawiera dodatkowo confirmations, requiredConfirmations (2), txHash i cryptoAddress. Dla Stripe rozliczenie wykonuje webhook po stronie serwera - status detected oznacza opłaconą sesję w trakcie księgowania.


4. 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:

PoleTypWymaganeOpis
recipient_emailStringTakAdres e-mail odbiorcy w platformie BlackHost
amountLiczbaTakKwota przelewu w wPLN (od 1.00 do 1000.00)
totp_codeStringNie*6-cyfrowy kod 2FA z aplikacji uwierzytelniającej (*wymagany, gdy na koncie włączone jest 2FA i nie wykonano świeżego step-upu w panelu)

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 '{
    "recipient_email": "[email protected]",
    "amount": 25.00
  }'

Przykład odpowiedzi (200 OK)

{
  "success": true,
  "message": "Pomyślnie przekazano 25.00 wPLN do użytkownika [email protected].",
  "wpln": 125.00,
  "transactionId": 142
}

⚠️ Gdy konto wymaga weryfikacji 2FA, API zwróci 400 z kodem błędu wallet.missing2fa i polem requires2fa: true - wtedy powtórz zapytanie z aktualnym kodem totp_code.


5. 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

ℹ️ Lista opisuje bramki dostępne na platformie. Nie każda z nich jest dostępna przez klucz API - dla sesji PAT obowiązują ograniczenia opisane w sekcji 2. Doładowanie portfela (#2-do%C5%82adowanie-portfela-v1paymentscreate).

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": "BLIK / Karta / Przelew",
      "description": "Płatności natychmiastowe za pośrednictwem Stripe (BLIK, karty płatnicze, Przelewy24, Revolut Pay).",
      "iconName": "CreditCard",
      "type": "fiat",
      "enabled": true,
      "minAmountPln": 2.00,
      "maxAmountPln": 10000.00
    },
    {
      "id": "crypto_ltc",
      "name": "Litecoin (LTC)",
      "description": "Doładowanie przez natywną sieć Litecoin. Automatyczne księgowanie po potwierdzeniu w blockchainie.",
      "iconName": "Coins",
      "type": "crypto",
      "enabled": true,
      "minAmountPln": 10.00,
      "maxAmountPln": 5000.00
    }
  ]
}

Opis pól:

PoleOpis
idIdentyfikator bramki (stripe, crypto_ltc)
name / descriptionNazwa i opis wyświetlane w panelu
iconNameNazwa ikony (interfejs panelu)
typeTyp bramki: fiat lub crypto
enabledCzy bramka jest aktualnie włączona (np. false, gdy brak klucza API)
minAmountPln / maxAmountPlnMinimalna i maksymalna kwota doładowania w PLN

6. 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
  • Cache: odpowiedź może być cache'owana do 30 minut (nagłówek X-Cache: HIT / MISS)

Przykład zapytania cURL

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

Struktura odpowiedzi:

  • packets - lista pakietów, każdy zawiera:
    • uniqueId - identyfikator oferty (używany jako offerId przy zakupie i uaktualnieniach)
    • title - nazwa oferty (np. Minecraft Java)
    • category - kategoria oferty: game lub vps
    • descriptionPL, descriptionEN, imageURL - opisy i grafika oferty
    • installations - lista dostępnych systemów / silników (np. Paper, Vanilla, Fabric) - wartość przekazywana jako system przy zakupie serwera gry; dla VPS lista szablonów systemowych (np. debian-12, ubuntu-24.04)
    • servers - warianty (tier'y) pakietu, każdy z polami:
      • name - nazwa wariantu (używana jako packageName przy zakupie, np. Start)
      • price / pricePL / pricePL2 - cena w wPLN: bazowa, dla lokalizacji PL_PREMIUM i PL_BASE
      • locations - dostępne lokalizacje wariantu: PL_BASE i/lub PL_PREMIUM
      • specifications - lista specyfikacji (CPU, RAM, NVMe itp.)
      • ports - zakres portów podstawowych oferty
      • promotion - informacja o aktywnej promocji i najniższej cenie z 30 dni (Omnibus), jeśli obowiązuje
  • nodeRamLimits - aktualne limity dostępnej pamięci RAM na węzłach (pakiety chwilowo niedostępne z braku zasobów)

Przykład odpowiedzi (200 OK, skrócona):

{
  "success": true,
  "packets": [
    {
      "uniqueId": "minecraft-java",
      "title": "Minecraft Java",
      "category": "game",
      "installations": ["Vanilla", "Paper", "Purpur", "Fabric", "Forge"],
      "servers": [
        {
          "name": "Start",
          "price": 7.00,
          "pricePL": 7.00,
          "pricePL2": 5.00,
          "locations": ["PL_BASE", "PL_PREMIUM"],
          "specifications": [
            { "name": "vCPU", "value": "2" },
            { "name": "RAM", "value": "4 GB" }
          ],
          "ports": { "from": 25565, "to": 25665 },
          "promotion": null
        }
      ]
    }
  ],
  "nodeRamLimits": {},
  "source": "mongodb"
}

Mapowanie pól przy zakupie:

Pole z kataloguPole w POST /v1/servers/game/purchase
packets[].uniqueIdofferId
packets[].servers[].namepackageName
packets[].servers[].locations[]node
packets[].installations[]system

ℹ️ Uwaga: Katalog nie zwraca identyfikatorów eggId, nestId ani numerów fizycznych węzłów - nie są one potrzebne przy zamówieniu. Egg, nest i konkretny węzeł (w ramach wybranej lokalizacji) dobiera automatycznie panel po stronie serwera.