Płatności i wypłaty/Portfele statyczne

Statyczne portfele

Trwałe adresy depozytowe powiązane z konkretnym zamówieniem lub użytkownikiem, idealne do płatności cyklicznych i długoterminowych.

Pokaż jako Markdown·llms.txt

Statyczne portfele to trwałe adresy do otrzymywania płatności kryptowalutowych. Są one powiązane z konkretnym order_id i są unikalne dla kombinacji project_id + order_id + currency + network.

Statycznych portfeli używaj do:

Cyklicznych depozytów od tego samego użytkownika
Długoterminowych adresów płatności wyświetlanych w profilu użytkownika
Procesów depozytowych o dużym wolumenie, w których zależy Ci na stabilnym adresie dla każdego użytkownika

Utwórz statyczny portfel

POST/v1/static-wallet

Parametry żądania

Pole	Typ	Wymagane	Opis
`currency`	string	tak	Kryptowaluta (USDT, BTC, ETH itp.)
`network`	string	tak	Kod sieci
`order_id`	string	tak	Twój identyfikator zamówienia/użytkownika (do 255 znaków)
`label`	string	nie	Etykieta portfela (do 255 znaków)
`url_callback`	string	tak	URL powiadomień webhook
`invite_code`	string	nie	Kod osoby polecającej

Przykład żądania

JSON

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

Przykład odpowiedzi

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Informacje o portfelu

Pobierz informacje o statycznym portfelu po uuid lub address.

POST/v1/static-wallet/info

Parametry żądania

Pole	Typ	Wymagane	Opis
`uuid`	string	tak*	UUID statycznego portfela
`address`	string	tak*	Adres portfela blockchain

Wymagany jest co najmniej jeden z parametrów uuid lub address.

Przykład odpowiedzi

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

total_received — suma wszystkich depozytów otrzymanych przez ten portfel, w walucie currency.
transactions_count — liczba dotychczas otrzymanych depozytów.
qr — kod QR (data URI) zakodowany w base64, prezentujący adres depozytowy (zawsze obecny w przypadku statycznych portfeli, ponieważ adres jest przypisywany w momencie utworzenia).

Lista portfeli

POST/v1/static-wallet/list

Parametry żądania

Pole	Typ	Wymagane	Opis
`status`	string	nie	Filtrowanie według statusu (`active`, `inactive`)
`currency`	string	nie	Filtrowanie według waluty
`network`	string	nie	Filtrowanie według sieci
`order_id`	string	nie	Filtrowanie według order_id
`page`	int	nie	Numer strony (domyślnie: 1)
`per_page`	int	nie	Liczba elementów na stronę (domyślnie: 20, maks.: 100)

Przykład odpowiedzi

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

Włącz / wyłącz portfel

Przełącz, czy statyczny portfel akceptuje nowe płatności.

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

Żądanie

Oba endpointy przyjmują pojedynczy parametr:

JSON

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

Przykład odpowiedzi

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

W przypadku enable, status ma wartość "active", a message brzmi "Static wallet enabled successfully".

Transakcje portfela

Pobierz listę wszystkich depozytów otrzymanych przez statyczny portfel.

POST/v1/static-wallet/transactions

Parametry żądania

Pole	Typ	Wymagane	Opis
`uuid`	string	tak	UUID statycznego portfela
`date_from`	date	nie	Data początkowa (YYYY-MM-DD)
`date_to`	date	nie	Data końcowa (YYYY-MM-DD)
`page`	int	nie	Numer strony (domyślnie: 1)
`per_page`	int	nie	Liczba elementów na stronę (domyślnie: 15, maks.: 5000)

Przykład odpowiedzi

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

fee_amount — opłata platformy potrącona z tego depozytu, w walucie currency.
net_amount — kwota zaksięgowana na saldzie sprzedawcy po potrąceniu opłaty.

Webhooki statycznych portfeli

Gdy na statyczny portfel wpłynie płatność, system wysyła webhook pod adres url_callback.

Format webhooka dla statycznych portfeli różni się od standardowych webhooków płatności. W szczególności webhooki statycznych portfeli zawierają pole merchant_amount, którego należy używać do księgowania.

Payload webhooka

JSON

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Webhooki statycznych portfeli nie zawierają pól url ani expires_at (ponieważ adres jest trwały, a nie sesyjny). Zawierają natomiast exchange_rate oraz created_at.

Opis pól

Pole	Typ	Opis
`uuid`	string	UUID transakcji (faktury) tego depozytu
`order_id`	string	Twój `order_id` statycznego portfela
`amount`	decimal (8 dp)	Otrzymana kwota w kryptowalucie
`currency`	string	Otrzymana kryptowaluta (zgodna z `currency` portfela)
`amount_usd`	decimal (8 dp)	Wartość w USD w chwili otrzymania
`exchange_rate`	decimal	Użyty kurs krypto / USD
`payer_currency`	string	Tożsame z `currency` dla statycznych portfeli
`payer_amount`	decimal (8 dp)	Tożsame z `amount` dla statycznych portfeli
`network`	string	Sieć blockchain
`address`	string	Adres statycznego portfela
`payment_status`	string	Zawsze `paid` dla statycznych portfeli
`txid`	string	Hash transakcji blockchain
`payment_amount`	decimal (8 dp)	Tożsame z `amount`
`merchant_amount`	decimal (18 dp)	Kwota po potrąceniu opłaty — używaj jej do księgowania
`created_at`	string (ISO 8601)	Moment otrzymania depozytu
`sign`	string (hex)	Podpis HMAC-SHA256 payloadu

Dobre praktyki

Unikalny order_id — używaj unikalnego order_id dla każdego użytkownika lub zamówienia
Idempotentność — sprawdzaj txid przed przetworzeniem, aby uniknąć podwójnych zaksięgowań
Weryfikuj podpisy — ZAWSZE weryfikuj podpis sign przed zaksięgowaniem środków
Używaj merchant_amount — księguj użytkownikom kwotę z merchant_amount, a nie payment_amount