На цій сторінці
- 1. Saldo portfela i historia transakcji (`/v1/wallet`)
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 2. Doładowanie portfela (`/v1/payments/create`)
- Parametry w ciele zapytania:
- Dostępność według metody uwierzytelnienia:
- Przykład zapytania cURL (Stripe)
- Przykład odpowiedzi (200 OK) - Stripe
- Przykład odpowiedzi (200 OK) - Litecoin
- 3. Status intencji płatności (`/v1/payments/{id}/status`)
- Cykl życia intencji:
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 4. Przelew wewnętrzny P2P (`/v1/wallet/transfer`)
- Parametry w ciele zapytania:
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- 5. Dostępne bramki i metody płatności (`/v1/payments/providers`)
- Przykład zapytania cURL
- Przykład odpowiedzi (200 OK)
- Opis pól:
- 6. Katalog pakietów i sklep (`/v1/shop/packets`)
- Przykład zapytania cURL
- Struktura odpowiedzi:
- Przykład odpowiedzi (200 OK, skrócona):
- Mapowanie pól przy zakupie:
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:readlubaccount: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:
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
provider | String | Nie | Dostawca płatności: stripe (domyślnie) lub crypto_ltc |
amount | Liczba | Tak | Kwota doładowania w PLN (dla Stripe od 2.00 do 10000.00; maks. 2 miejsca po przecinku) |
code | String | Nie | Opcjonalny kod rabatowy / promocyjny / kod polecającego |
Dostępność według metody uwierzytelnienia:
| Dostawca | Sesja 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 jednakPOST /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 (intentIdz odpowiedzi na utworzenie) - Wymagany scope:
account:readlubaccount:billing - Dostęp: właściciel intencji; administrator widzi intencje wszystkich użytkowników
Cykl życia intencji:
| Status | Opis |
|---|---|
pending | Intencja oczekuje na płatność |
detected | Środki odebrane, ale jeszcze nie rozliczone (krypto: czekanie na potwierdzenia; Stripe: opłacone, webhook w trakcie księgowania) |
settled | Rozliczone - portfel wPLN został uznany |
expired | Upł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),txHashicryptoAddress. Dla Stripe rozliczenie wykonuje webhook po stronie serwera - statusdetectedoznacza 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:
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
recipient_email | String | Tak | Adres e-mail odbiorcy w platformie BlackHost |
amount | Liczba | Tak | Kwota przelewu w wPLN (od 1.00 do 1000.00) |
totp_code | String | Nie* | 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
400z kodem błęduwallet.missing2fai polemrequires2fa: true- wtedy powtórz zapytanie z aktualnym kodemtotp_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:readlubaccount: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:
| Pole | Opis |
|---|---|
id | Identyfikator bramki (stripe, crypto_ltc) |
name / description | Nazwa i opis wyświetlane w panelu |
iconName | Nazwa ikony (interfejs panelu) |
type | Typ bramki: fiat lub crypto |
enabled | Czy bramka jest aktualnie włączona (np. false, gdy brak klucza API) |
minAmountPln / maxAmountPln | Minimalna 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 jakoofferIdprzy zakupie i uaktualnieniach)title- nazwa oferty (np.Minecraft Java)category- kategoria oferty:gamelubvpsdescriptionPL,descriptionEN,imageURL- opisy i grafika ofertyinstallations- lista dostępnych systemów / silników (np.Paper,Vanilla,Fabric) - wartość przekazywana jakosystemprzy 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 jakopackageNameprzy zakupie, np.Start)price/pricePL/pricePL2- cena w wPLN: bazowa, dla lokalizacjiPL_PREMIUMiPL_BASElocations- dostępne lokalizacje wariantu:PL_BASEi/lubPL_PREMIUMspecifications- lista specyfikacji (CPU, RAM, NVMe itp.)ports- zakres portów podstawowych ofertypromotion- 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 katalogu | Pole w POST /v1/servers/game/purchase |
|---|---|
packets[].uniqueId | offerId |
packets[].servers[].name | packageName |
packets[].servers[].locations[] | node |
packets[].installations[] | system |
ℹ️ Uwaga: Katalog nie zwraca identyfikatorów
eggId,nestIdani 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.