Wprowadzenie/Referencje

Wartości referencyjne

Kody sieci, mapowania waluta-sieć oraz wartości statusów płatności używane w API 2328.io.

Ta strona zawiera wszystkie wartości referencyjne używane w żądaniach i odpowiedziach API.

Kody sieci

Te kody są używane wszędzie, gdzie występuje pole network:

Kod	Sieć
`TRX-TRC20`	Tron TRC-20
`BSC-BEP20`	BNB Smart Chain
`ETH-ERC20`	Ethereum (ERC-20)
`BASE`	Base
`AVAX-C`	Avalanche C-Chain
`POL-MATIC`	Polygon (Matic)
`TON`	TON
`BTC`	Bitcoin
`LTC`	Litecoin
`DASH`	Dash
`SOL`	Solana
`DOGE`	Dogecoin
`ZEC`	Zcash
`XRP`	XRP Ledger
`XMR`	Monero

Mapowanie waluta-sieć

Każda waluta jest dostępna tylko w wybranym podzbiorze sieci. Skorzystaj z poniższej tabeli, aby wybrać poprawną kombinację:

Waluta	Dozwolone sieci
`USDT`	TRX-TRC20, BSC-BEP20, ETH-ERC20, BASE, AVAX-C, POL-MATIC, TON, SOL
`USDC`	BSC-BEP20, ETH-ERC20, BASE, AVAX-C, POL-MATIC, SOL
`BTC`	BTC
`ETH`	ETH-ERC20, BASE
`BNB`	BSC-BEP20
`TRX`	TRX-TRC20
`LTC`	LTC
`DASH`	DASH
`GRAM`	TON
`AVAX`	AVAX-C
`POL`	POL-MATIC
`SOL`	SOL
`DOGE`	DOGE
`ZEC`	ZEC
`XRP`	XRP
`XMR`	XMR

GRAM to kanoniczny kod aktywu dla natywnej waluty TON. Interfejsy API do płatności, statycznego portfela i tworzenia wypłat obecnie akceptują starsze dane wejściowe TON i normalizują je do GRAM; integracje powinny przechowywać i obsługiwać wartość kanoniczną zwracaną przez API. Natywnym aktywem Polygon jest POL, podczas gdy jego kod sieci to POL-MATIC. Nigdy nie wysyłaj MATIC jako kodu sieci.

Włączone kierunki są konfiguracją operacyjną i mogą zmieniać się niezależnie od tego katalogu. Zapytaj /v1/directions przed przedstawieniem opcji; traktuj tę tabelę jako prawidłową mapę kodów, a nie gwarancję, że każda para jest obecnie włączona.

Statusy płatności

Pole payment_status w płatnościach oraz filtr /v1/payment/list przyjmują następujące wartości:

Status	Opis
`pending`	Utworzona, oczekuje na inicjalizację
`check`	Oczekuje na płatność od klienta
`paid`	Opłacona pomyślnie
`underpaid_check`	Niedopłacona (możliwe uzupełnienie)
`underpaid`	Niedopłacona
`overpaid`	Nadpłacona (zaksięgowana)
`cancel`	Anulowana / wygasła
`aml_lock`	Transakcja zablokowana z powodu AML

Nasłuchując udanej płatności, traktuj zarówno paid, jak i overpaid jako stany powodzenia i księguj zamówienie klienta.

Polityka obsługi statusów

Status	Zrealizować zamówienie?	Kontynuować oczekiwanie?	Działanie operacyjne
`pending` / `check`	Nie	Tak, do wygaśnięcia	Wyświetl stan oczekujący i dokonaj normalnego uzgodnienia.
`underpaid_check`	Domyślnie nie	Tak, doładowanie może nadejść	Przechowuj każde ID txid idempotentnie i pokaż proces pozostałej płatności.
`paid`	Tak, raz	Nie	Zrealizuj atomowo z weryfikowanego zdarzenia.
`overpaid`	Tak, raz	Nie	Spełniaj i zachowuj nadwyżki/rzeczywiste kwoty zgodnie z polityką sprzedawcy.
`underpaid`	Specyficzne dla produktu	Nie	Stosuj wyraźną politykę częściowej płatności/przeglądu ręcznego.
`cancel`	Nie	Nie	Oznacz jako wygasłe/anulowane, ale eskaluj wszelkie późniejsze dowody on-chain.
`aml_lock`	Nie	Brak automatycznego realizowania	Przegląd zgodności/wsparcia; nie uwalniaj wartości automatycznie.

Statusy opisują widok platformy na płatność. Nie zastępują lokalnego stanu realizacji. Przechowuj oba, aby zwrócone, ręcznie sprawdzone lub już zrealizowane zamówienie nie mogło zostać uszkodzone przez starszy webhook.

Filtr żądań /v1/payment/list obecnie akceptuje pending, check, paid, underpaid_check, underpaid, overpaid i cancel. Nie akceptuje aml_lock jako filtra, mimo że płatność zablokowana przez AML może zostać zwrócona przez inne punkty końcowe płatności.

Statusy wypłat

Pole status w /v1/payout oraz /v1/payout/status/{uuid} przyjmuje jedną z wartości:

Status	Opis
`pending`	Utworzona, oczekuje na przetworzenie
`completed`	Zakończona pomyślnie — `txid` jest ustawione
`failed`	Błąd wysyłki — zobacz `error_type`
`cancelled`	Anulowana

Typy błędów wypłat

Gdy wypłata ma status = failed, pole error_type opisuje przyczynę:

Kod	Opis
`aml_risk`	Wypłata zablokowana przez kontrole ryzyka AML (adres odbiorcy oznaczony jako wysokiego ryzyka)