# 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 |

> **INFO:** 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) |