# Riferimenti

> Codici di rete, mappature valuta-rete e valori di stato dei pagamenti utilizzati nell'API di 2328.io.

Questa pagina elenca tutti i valori di riferimento utilizzati nelle richieste e nelle risposte dell'API.

## Codici di rete

Questi codici vengono utilizzati ovunque sia presente un campo `network`:

| Codice | Rete |
|------|---------|
| `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 |

## Mappatura valuta-rete

Ogni valuta è disponibile solo su un sottoinsieme di reti. Utilizza questa tabella per scegliere una combinazione valida:

| Valuta | Reti consentite |
|----------|-----------------|
| `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` è il codice asset canonico per la valuta nativa TON. Le API per la creazione di pagamenti, portafogli statici e pagamenti attualmente accettano l'input legacy `TON` e lo normalizzano in `GRAM`; le integrazioni dovrebbero memorizzare e gestire il valore canonico restituito dall'API. L'asset nativo di Polygon è `POL`, mentre il suo codice di rete è `POL-MATIC`. Non inviare mai `MATIC` come codice di rete.

Le direzioni abilitate sono configurazioni operative e possono cambiare indipendentemente da questo catalogo. Interroga `/v1/directions` prima di presentare le scelte; tratta questa tabella come la mappa dei codici valida, non come una garanzia che ogni coppia sia attualmente abilitata.

## Stati dei pagamenti

Il campo `payment_status` sui pagamenti e il filtro `/v1/payment/list` accettano i seguenti valori:

| Stato | Descrizione |
|--------|-------------|
| `pending` | Creato, in attesa di inizializzazione |
| `check` | In attesa del pagamento da parte del cliente |
| `paid` | Pagato con successo |
| `underpaid_check` | Pagamento insufficiente (è possibile integrare) |
| `underpaid` | Pagamento insufficiente |
| `overpaid` | Pagamento in eccesso (accreditato) |
| `cancel` | Annullato / scaduto |
| `aml_lock` | Transazione bloccata per AML |

> **INFO:** Quando ascolti un pagamento andato a buon fine, dovresti trattare sia `paid` sia `overpaid` come stati di successo e accreditare l'ordine del cliente.

### Gestione dello stato

| Stato | Eseguire l'ordine? | Continuare ad attendere? | Azione operativa |
|--------|----------------|-------------------|--------------------|
| `pending` / `check` | No | Sì, fino alla scadenza | Mostra lo stato in sospeso e riconcilia normalmente. |
| `underpaid_check` | No per impostazione predefinita | Sì, il ricarico può arrivare | Memorizza ogni txid in modo idempotente e mostra il flusso di lavoro del pagamento rimanente. |
| `paid` | Sì, una volta | No | Esegui atomisticamente dall'evento verificato. |
| `overpaid` | Sì, una volta | No | Soddisfare e conservare importi eccedenti/reali per la politica del commerciante. |
| `underpaid` | Specifico per prodotto | No | Applicare la politica di pagamento parziale esplicito/revisione manuale. |
| `cancel` | No | No | Segnare come scaduto/annullato, ma segnalare qualsiasi prova successiva sulla blockchain. |
| `aml_lock` | No | Nessuna evasione automatica | Revisione di conformità/supporto; non rilasciare il valore automaticamente. |

Gli stati descrivono la visione della piattaforma sul pagamento. Non sostituiscono il tuo stato di evasione locale. Memorizza entrambi in modo che un ordine rimborsato, revisionato manualmente o già evaso non possa essere compromesso da un webhook più vecchio.

Il filtro di richiesta `/v1/payment/list` accetta attualmente `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid` e `cancel`. Non accetta `aml_lock` come filtro anche se un pagamento bloccato da AML può essere restituito da altri endpoint di pagamento.

## Stati dei prelievi

Il campo `status` su `/v1/payout` e `/v1/payout/status/{uuid}` assume uno dei seguenti valori:

| Stato | Descrizione |
|--------|-------------|
| `pending` | Creato, in attesa di elaborazione |
| `completed` | Completato con successo — `txid` è impostato |
| `failed` | Errore di invio — vedi `error_type` |
| `cancelled` | Annullato |

## Tipi di errore dei prelievi

Quando un prelievo ha `status = failed`, il campo `error_type` ne descrive il motivo:

| Codice | Descrizione |
|------|-------------|
| `aml_risk` | Prelievo bloccato dai controlli di rischio AML (l'indirizzo del destinatario è stato segnalato come ad alto rischio) |