Sign in
Płatności i wypłaty/Payout API

Payout API

Wysyłaj wypłaty z salda sprzedawcy na dowolny adres blockchain.

Payout API umożliwia programowe wypłacanie środków z salda sprzedawcy na dowolny adres blockchain.

Dla wszystkich endpointów Payout musisz używać osobnego Payout API key do generowania podpisu sign. Klucz ten różni się od zwykłego klucza API i należy go wygenerować w ustawieniach projektu.

Utwórz wypłatę

Tworzy żądanie wypłaty z Twojego salda sprzedawcy.

POST/v1/payout

Parametry żądania

PoleTypWymaganeOpis
currencystringtakWaluta wypłaty (zobacz References)
networkstringtakKod sieci (zobacz References)
amountstringtakKwota wypłaty
to_addressstringtakAdres blockchain odbiorcy
order_idstringnieKlucz idempotentności — unikalny w obrębie projektu. Powtórne POST z tym samym order_id nie tworzy nowej wypłaty — zamiast tego zwracana jest istniejąca
url_callbackstringnieURL webhooków wypłaty. Pomiń, aby wyłączyć webhooki dla tej wypłaty
memostring | nullnieTag docelowy / memo. Obecnie używany wyłącznie przez sieci TON i SOL; maks. 255 znaków
from_currencystringnieSaldo źródłowe, z którego pobrane środki zostaną automatycznie przeliczone na currency w momencie wypłaty. Pozwala wypłacać w aktywach o dużej zmienności (BTC, ETH, …) przy jednoczesnym utrzymywaniu salda w stablecoinie takim jak USDT — nie musisz sam trzymać zmiennej kryptowaluty. Przekaż "USDT", aby obciążyć saldo USDT
fee_optionstringnieSposób naliczania opłat. deduct (domyślnie) — opłaty sieciowe i opłaty platformy odejmowane są od amount, odbiorca otrzymuje amount - fees. add — opłaty doliczane są na wierzch, sprzedawca obciążany jest kwotą amount + fees, a odbiorca otrzymuje dokładnie amount

Idempotentność. W obrębie projektu wypłata jest unikalna względem order_id. Ponowne wysłanie tego samego żądania POST z tym samym order_id jest bezpieczne — API zwraca istniejącą wypłatę zamiast tworzyć duplikat. Dla wypłat produkcyjnych zawsze przekazuj order_id.

Przykłady żądań

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

Przykład odpowiedzi

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

Opłaty. Domyślnie fee_option: deduct — opłaty sieciowe oraz opłaty platformy odejmowane są od amount (odbiorca otrzymuje amount - fees). Przekaż fee_option: add, aby naliczyć opłaty na wierzch — odbiorca otrzymuje dokładnie amount, a sprzedawca obciążany jest kwotą amount + fees.

Oblicz wypłatę

Szacuje kwoty i opłaty wypłaty bez tworzenia wypłaty i bez obciążania salda. Użyj, aby pokazać użytkownikowi dokładną kwotę, którą otrzyma (lub zapłaci), zanim potwierdzi.

POST/v1/payout/calc

Parametry żądania

Identyczne jak w Utwórz wypłatę — te same pola, ten sam podpis. Pola order_id, url_callback, to_address i memo są akceptowane, ale ignorowane: żadna wypłata nie jest zapisywana i nie są wysyłane callbacki.

Przykład żądania

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

Przykład odpowiedzi

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

Tylko podgląd. Ten endpoint jest tylko do odczytu — żadne saldo nie jest obciążane i nie tworzy się rekord wypłaty. Wywołuj go tyle razy, ile potrzebujesz, aby pokazać rozbicie opłat w UI.

Status wypłaty

Pobierz status żądania wypłaty.

GET/v1/payout/status/{uuid}

Parametry ścieżki

PoleTypWymaganeOpis
uuidstringtakUUID wypłaty (z pola result.uuid przy tworzeniu)

Przykład odpowiedzi

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

Dla tego żądania GET podpis jest obliczany z pustej treści: hash_hmac('sha256', base64_encode(''), $apiKey)

Pola odpowiedzi

Pola zwracane w result z POST /v1/payout oraz GET /v1/payout/status/{uuid}:

PoleTypOpis
uuidstringUUID wypłaty przypisany przez system
order_idstringTwój wewnętrzny identyfikator wypłaty (unikalny w obrębie projektu)
statusstringAktualny status wypłaty (zobacz poniżej)
currencystringWaluta wypłaty
networkstringKod sieci
amountstringŻądana kwota wypłaty
merchant_amountstringKwota obciążająca saldo sprzedawcy
network_amountstringKwota faktycznie wysłana w sieci (po opłatach sieciowych i opłatach platformy)
amount_usdstringRównowartość kwoty wypłaty w USD
to_addressstringAdres blockchain odbiorcy
memostring | nullTag docelowy / memo (TON, SOL). W przeciwnym razie null
txidstring | nullHash transakcji blockchain. null, dopóki transakcja nie zostanie wysłana
block_numberint | nullNumer bloku, w którym uwzględniono transakcję. null, dopóki transakcja nie zostanie uwzględniona
error_typestring | nullPowód niepowodzenia, gdy status = failed (zobacz „Typy błędów" poniżej). W przeciwnym razie null
created_atstring (ISO 8601)Czas utworzenia wypłaty
updated_atstring (ISO 8601)Czas ostatniej zmiany statusu
from_currencystring | nullSaldo źródłowe, z którego pobrano wypłatę przy użyciu automatycznej konwersji (np. USDT dla wypłaty w BTC). null, jeśli konwersja nie nastąpiła
debited_amountstring | nullKwota faktycznie obciążająca saldo źródłowe po konwersji. Obecne tylko, gdy używana jest automatyczna konwersja
debited_currencystring | nullWaluta debited_amount — saldo, z którego zostały pobrane środki

Statusy wypłat

Pole status może przyjmować następujące wartości:

StatusOpis
pendingUtworzona, oczekuje na przetworzenie
completedZakończona pomyślnie — txid jest ustawione
failedBłąd wysyłki — zobacz error_type
cancelledAnulowana

Typy błędów

Gdy status = failed, pole error_type opisuje przyczynę:

KodOpis
aml_riskWypłata zablokowana przez kontrole ryzyka AML (adres odbiorcy oznaczony jako wysokiego ryzyka)

Powiadomienia webhook

Gdy zmienia się status wypłaty, system wysyła webhook POST pod adres url_callback przekazany w momencie utworzenia wypłaty. Jeśli url_callback nie został podany, dla tej wypłaty nie są wysyłane żadne webhooki.

  • Method: POST
  • Content-Type: application/json
  • Signature: pole sign w treści żądania, obliczone za pomocą Payout API key (tego samego klucza, którym podpisywane są żądania wypłat).

Payload odzwierciedla obiekt result z GET /v1/payout/status/{uuid} wraz z dodatkowym polem sign służącym do weryfikacji.

Payload

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

Weryfikacja podpisu. Użyj tego samego algorytmu co dla webhooków płatności, ale podpisz Payout API key zamiast zwykłego klucza API. Usuń pole sign, zakoduj pozostały payload jako JSON, zakoduj go w base64, następnie oblicz hash_hmac('sha256', $base64, $payoutApiKey) i porównaj z otrzymanym sign.