# Wallet Statici

> Indirizzi di deposito permanenti associati a un ordine o a un utente specifico, ideali per pagamenti ricorrenti e a lungo termine.

I wallet statici sono indirizzi permanenti per ricevere pagamenti in criptovaluta. Sono collegati a uno specifico `order_id` e sono univoci dalla combinazione di `project_id + order_id + currency + network`.

Utilizza i wallet statici per:

- Depositi ricorrenti dallo stesso utente
- Indirizzi di pagamento a lungo termine mostrati nel profilo di un utente
- Flussi di deposito ad alto volume in cui desideri un indirizzo stabile per ciascun utente

## Creare un wallet statico

`POST /v1/static-wallet`

### Parametri della richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|----------|-------------|
| `currency` | string | sì | Criptovaluta (USDT, BTC, ETH, ecc.) |
| `network` | string | sì | Codice di rete |
| `order_id` | string | sì | Il tuo ID ordine/utente (fino a 255 caratteri) |
| `label` | string | no | Etichetta del wallet (fino a 255 caratteri) |
| `url_callback` | string | sì | URL per le notifiche webhook |
| `invite_code` | string | no | Codice del referrer |

### Esempio di richiesta

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

### Esempio di risposta

```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..."
  }
}
```

## Informazioni sul wallet

Ottieni le informazioni sul wallet statico tramite `uuid` o `address`.

`POST /v1/static-wallet/info`

### Parametri della richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|----------|-------------|
| `uuid` | string | sì* | UUID del wallet statico |
| `address` | string | sì* | Indirizzo del wallet blockchain |

> **INFO:** È richiesto almeno uno tra `uuid` e `address`.

### Esempio di risposta

```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` — somma di tutti i depositi ricevuti da questo wallet, in `currency`.
- `transactions_count` — numero di depositi ricevuti finora.
- `qr` — data URI QR codificato in Base64 dell'indirizzo di deposito (sempre presente per i wallet statici, l'indirizzo viene assegnato alla creazione).

## Elenco dei wallet

`POST /v1/static-wallet/list`

### Parametri della richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|----------|-------------|
| `status` | string | no | Filtra per stato (`active`, `inactive`) |
| `currency` | string | no | Filtra per valuta |
| `network` | string | no | Filtra per rete |
| `order_id` | string | no | Filtra per order_id |
| `page` | int | no | Numero di pagina (default: 1) |
| `per_page` | int | no | Elementi per pagina (default: 20, max: 100) |

### Esempio di risposta

```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
    }
  }
}
```

## Abilitare / disabilitare il wallet

Attiva o disattiva la possibilità che un wallet statico accetti nuovi pagamenti.

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### Richiesta

Entrambi gli endpoint accettano un singolo parametro:

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

### Esempio di risposta

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

Per `enable`, `status` è `"active"` e `message` recita `"Static wallet enabled successfully"`.

## Transazioni del wallet

Ottieni un elenco di tutti i depositi ricevuti da un wallet statico.

`POST /v1/static-wallet/transactions`

### Parametri della richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|----------|-------------|
| `uuid` | string | sì | UUID del wallet statico |
| `date_from` | date | no | Data di inizio (YYYY-MM-DD) |
| `date_to` | date | no | Data di fine (YYYY-MM-DD) |
| `page` | int | no | Numero di pagina (default: 1) |
| `per_page` | int | no | Elementi per pagina (default: 15, max: 5000) |

### Esempio di risposta

```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` — commissione di piattaforma detratta da questo deposito, in `currency`.
- `net_amount` — importo accreditato sul saldo merchant dopo la commissione.

## Webhook dei wallet statici

Quando un pagamento viene ricevuto su un wallet statico, il sistema invia un webhook a `url_callback`.

> **WARNING:** Il formato del webhook per i wallet statici è diverso da quello dei normali webhook di pagamento. In particolare, i webhook dei wallet statici includono un campo `merchant_amount` che dovresti utilizzare per l'accredito.

### Payload del webhook

```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",
  "tx_explorer_url": "https://tronscan.org/#/transaction/8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}
```

> **INFO:** I webhook dei wallet statici **non** includono `url` o `expires_at` (poiché l'indirizzo è permanente, non è una sessione). Includono invece `exchange_rate` e `created_at`.

### Riferimento dei campi

| Campo | Tipo | Descrizione |
|-------|------|-------------|
| `uuid` | string | UUID della transazione (fattura) per questo deposito |
| `order_id` | string | Il tuo `order_id` del wallet statico |
| `amount` | decimal (8 dp) | Importo crypto ricevuto |
| `currency` | string | Crypto ricevuta (corrisponde alla `currency` del wallet) |
| `amount_usd` | decimal (8 dp) | Valore in USD al momento della ricezione |
| `exchange_rate` | decimal | Tasso crypto / USD utilizzato |
| `payer_currency` | string | Uguale a `currency` per i wallet statici |
| `payer_amount` | decimal (8 dp) | Uguale a `amount` per i wallet statici |
| `network` | string | Rete blockchain |
| `address` | string | Indirizzo del wallet statico |
| `payment_status` | string | Stato attuale del deposito; normalmente `paid`, ma AML pu? produrre `aml_lock`, da non accreditare automaticamente |
| `txid` | string | Hash della transazione blockchain |
| `tx_explorer_url` | string \| null | URL della transazione nell’explorer blockchain. È `null` se `txid` è assente o se il trasferimento è P2P interno. |
| `payment_amount` | decimal (8 dp) | Uguale a `amount` |
| `merchant_amount` | decimal (18 dp) | **Importo dopo la detrazione della commissione** — utilizza questo per l'accredito |
| `created_at` | string (ISO 8601) | Quando è stato ricevuto il deposito |
| `sign` | string (hex) | Firma HMAC-SHA256 del payload |

## Best practice

- **`order_id` univoco** — Utilizza un `order_id` univoco per ciascun utente o ordine
- **Idempotenza** — Verifica `txid` prima di elaborare per evitare accrediti duplicati
- **Verifica le firme** — Verifica SEMPRE la firma `sign` prima di accreditare i fondi
- **Usa `merchant_amount`** — Accredita gli utenti in base a `merchant_amount`, non a `payment_amount`

## Ciclo di vita e idempotenza

Un portafoglio statico è un'identità di deposito riutilizzabile, non una fattura. Non ha un importo previsto e nessuna scadenza. Un indirizzo può produrre un numero qualsiasi di transazioni di deposito nel corso della sua vita.

La creazione è idempotente per lo stesso progetto del commerciante, `order_id`, `currency` e `network`: viene restituito il portafoglio esistente. Mantieni stabile quella tupla e conserva il portafoglio restituito `uuid`; non usare un nuovo `order_id` ogni volta che lo stesso cliente apre lo schermo di deposito.

L'idempotenza del deposito è diversa dall'idempotenza del portafoglio:

- `order_id` identifica la mappatura portafoglio/cliente riutilizzabile;
- wallet `uuid` identifica il record permanente del portafoglio;
- webhook `uuid` identifica una transazione di deposito rilevata;
- `txid` identifica il trasferimento on-chain ed è la chiave primaria di deduplicazione per l'accredito.

Usa un vincolo di unicità del database per l'identità processata chain/network/txid e richiedila nella stessa transazione che accredita il saldo interno del cliente.

## Abilita e disabilita la semantica

Disabilitare un portafoglio impedisce all'applicazione di elaborarlo come destinazione di deposito attiva; non cancella l'indirizzo o la sua cronologia e non può fermare un trasferimento blockchain già inviato da un utente.

> **DANGER:** Non dire mai agli utenti che i fondi inviati a un indirizzo inattivo vengono automaticamente restituiti. I trasferimenti sulla blockchain sono irreversibili. Disabilita solo dopo aver rimosso l'indirizzo dalla tua interfaccia utente e mantieni una procedura operativa di recupero per depositi tardivi.

La riattivazione preserva la stessa identità del wallet e l'indirizzo. Non creare un sostituto solo per cambiare l'etichetta; le etichette non sono identificatori di regolamento.

## Casi particolari di wallet statici

| Situazione | Gestione corretta |
|-----------|------------------|
| Richiesta di creazione duplicata | Accetta il wallet esistente restituito e verifica la sua tupla persistente invece di aspettarti un nuovo indirizzo. |
| Depositi multipli sullo stesso indirizzo | Crea una riga di deposito locale separata per ogni transazione `uuid`/`txid`; non contrassegnare mai il portafoglio stesso come “pagato.” |
| Webhook duplicato | Restituire HTTP 200 dopo aver trovato il txid già confermato; non accreditare di nuovo. |
| Ritardo di conferma o nuova osservazione della catena | Mantenere l'elaborazione idempotente e riconciliare da `/v1/static-wallet/transactions`. |
| Deposito sotto un minimo di auto-conversione | Aspettarsi accredito nella valuta di origine senza blocco `convert` completato. |
| Auto-conversione completata con successo | Memorizzare separatamente i valori di pagamento di origine e il risultato target `convert`. |
| Token sbagliato o rete sbagliata | Non creare un credito. Registra le prove e segnala al supporto/recupero perché la recuperabilità è specifica per ciascuna blockchain. |
| Catena basata su memo/tag | Mostra e convalida ogni campo di destinazione restituito dalla piattaforma; un solo indirizzo potrebbe non essere sufficiente quando è richiesto un memo. |
| Blocco AML | Non accreditare l'utente finale finché lo stato autorizzativo non è rilasciato tramite il processo di conformità. |
| Wallet disabilitato dopo la visualizzazione dell'indirizzo | Rimuovilo dall'interfaccia immediatamente, ma continua a monitorare gli avvisi operativi per trasferimenti tardivi. |

## Modello di riconciliazione

Esegui un lavoro periodico che scorra attraverso `/v1/static-wallet/transactions`, aggiorni o inserisca depositi per txid e confronti il loro `merchant_amount`, stato e risultato di conversione opzionale con il tuo registro interno. La consegna tramite webhook dovrebbe rendere la riconciliazione veloce, ma la riconciliazione deve renderla completa.