Wallet Statici

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

Parametri della richiesta

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Parametri della richiesta

Esempio di risposta

{
  "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

Parametri della richiesta

Esempio di risposta

{
  "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.

Richiesta

Entrambi gli endpoint accettano un singolo parametro:

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

Esempio di risposta

{
  "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.

Parametri della richiesta

Esempio di risposta

{
  "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.

Payload del webhook

{
  "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"
}

Riferimento dei campi

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.

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

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.