Integrazione pagamenti TRON: guida per sviluppatori 2026

Un’integrazione dei pagamenti TRON è l’insieme dei componenti che permette alla Sua applicazione di accettare e inviare TRX e token TRC-20 come USDT: indirizzi, transazioni firmate, rilevamento dei depositi e controlli di conferma. Si può costruire sulle API dei nodi TRON, oppure chiamare una REST API che crea wallet, invia trasferimenti e invia webhook. Questa guida tratta entrambe le strade.

TL;DR

• I pagamenti TRX sono trasferimenti nativi da account ad account. I pagamenti TRC-20 (come USDT) sono chiamate a smart contract, quindi consumano Energy oltre a Bandwidth.
• Ogni operazione che modifica lo stato segue tre passaggi: costruire una transazione non firmata, firmarla con la chiave del mittente, trasmetterla a un nodo.
• Accrediti i depositi solo da blocchi solidificati, solo per transazioni riuscite e, per i TRC-20, solo da contratti token approvati.
• Le commissioni dipendono dalle risorse in stake o delegate. Pianifichi per loro prima del lancio, altrimenti i TRX vengono bruciati a ogni trasferimento.
• Può evitare di gestire nodi e parser di blocchi usando un’API per wallet, trasferimenti e webhook come quella di Chaingateway.

Indice

• Come funzionano i pagamenti TRON?
• Conviene costruire sulle API dei nodi o usare un’API?
• Come costruisco, firmo e trasmetto una transazione?
• Come rilevo i pagamenti in entrata?
• Quando un pagamento TRON è definitivo?
• Come proteggo wallet e chiavi private?
• Quanto costano Energy e Bandwidth?
• Come gestisco pagamenti falliti, ritardati e duplicati?
• Posso accettare pagamenti nel mio token?
• Come invio pagamenti TRON tramite Chaingateway?
• FAQ
• Fonti

Come funzionano i pagamenti TRON?

TRX è il token nativo di TRON. Paga le commissioni di rete, e lo staking fornisce risorse di rete e diritti di voto, secondo la documentazione per sviluppatori TRON su TRX. Il grosso del volume commerciale su TRON, però, è in token come USDT-TRC20, quindi servono entrambi i tipi di trasferimento.

Un pagamento TRX è un semplice trasferimento tra account sulla chain. Un pagamento TRC-20 è diverso: il mittente chiama la funzione di trasferimento del contratto del token, che aggiorna i saldi all’interno del contratto ed emette un evento Transfer. Entrambi finiscono registrati su TRON, ma i trasferimenti TRC-20 richiedono l’esecuzione di uno smart contract, quindi consumano Bandwidth ed Energy, come descritto nel white paper di TRON.

Questa differenza determina l’intera integrazione:

Conviene costruire sulle API dei nodi o usare un’API?

La documentazione di integrazione di TRON elenca che cosa comporta tipicamente un’integrazione: collegare i wallet degli utenti finali, costruire e firmare le transazioni, monitorare depositi e prelievi, e usare TronGrid oppure un nodo completo self-hosted. Gli operatori di exchange e di wallet custodial gestiscono il monitoraggio dei depositi, i prelievi e le query su saldi e cronologia sulla stessa base.

Si presentano quindi due strade realistiche.

Prima strada: costruire sulle API dei nodi. Si ha il pieno controllo. Ma si è anche responsabili della derivazione degli indirizzi, del parsing dei blocchi, della logica di nuovo tentativo, della gestione delle risorse e, se il nodo è self-hosted, della sua manutenzione. La nostra guida alla configurazione di un nodo TRON descrive la via del Lite FullNode con jar o Docker, se sceglie questa strada.

Seconda strada: usare un’API per wallet e webhook. Si chiama un endpoint REST per creare un wallet, un altro per inviare un trasferimento, e si riceve un webhook firmato quando arriva un deposito. La nostra API TRON è pensata per questo: trasferimenti USDT-TRC20 e webhook di deposito senza gestire nodi. Gli endpoint sono nella definizione OpenAPI.

Una regola pratica: se i pagamenti sono il vero elemento distintivo del Suo prodotto e ha un team per gestire l’infrastruttura, costruisca in proprio. Se i pagamenti sono una funzione di un altro prodotto, un’API La porta in produzione più in fretta e tiene il team sul prodotto vero.

Come costruisco, firmo e trasmetto una transazione?

Che si usino chiamate grezze al nodo o un SDK, ogni operazione TRON che modifica lo stato segue lo stesso flusso in tre passaggi: costruire una transazione non firmata tramite un’API del nodo, firmarla lato client con la chiave privata del mittente, poi trasmettere la transazione firmata a un nodo.

Due dettagli meritano attenzione:

• TAPOS. Ogni transazione fa riferimento a un blocco recente, il che limita il replay su rami della chain che non contengono quel blocco, secondo la documentazione del protocollo sulle transazioni. In pratica, costruisca e firmi vicino al momento della trasmissione. Una transazione firmata e lasciata in sospeso per molto tempo può scadere.
• Usi gli helper dell’SDK per la firma. La guida per sviluppatori di wallet raccomanda in produzione gli helper dell’SDK invece di primitive di firma scritte a mano, per evitare casi limite legati alla serializzazione protobuf e al recupero della firma. Non scriva le proprie.

Per i flussi nel browser in cui l’utente paga dal proprio wallet, la guida all’integrazione DApp descrive due opzioni: TronWallet Adapter per un supporto unificato a più wallet, oppure l’integrazione diretta con TronLink, che inietta un provider in window.tron. I checkout dei commercianti che generano un indirizzo di deposito per ogni ordine di solito non ne hanno bisogno. Il cliente paga dal wallet che usa già.

Come rilevo i pagamenti in entrata?

Il modello tipico per i commercianti è un indirizzo di deposito per ordine o per cliente. Il Suo compito è accorgersi quando il denaro arriva su quegli indirizzi.

La guida per exchange e wallet custodial descrive due metodi di rilevamento: interrogare ogni pochi secondi le API della cronologia account di TronGrid, oppure analizzare i blocchi in sequenza. Se analizza i blocchi, usi l’altezza solidificata più recente, e recuperi i log degli eventi e le transazioni interne separatamente dai risultati di esecuzione, trattandoli come record distinti.

Non perda le transazioni interne

È la lacuna più comune nelle integrazioni fatte in casa. Gli utenti possono ricevere TRX o token TRC-10 tramite una chiamata a uno smart contract, e questi trasferimenti non compaiono come transazioni di primo livello. La stessa guida indica di analizzare le transazioni interne quando si accreditano i depositi. Se il Suo listener osserva solo i trasferimenti di primo livello, alcuni clienti pagheranno e non verranno mai accreditati.

Verifichi correttamente i depositi TRC-20

Per i depositi di token, il solo hash di transazione non dimostra nulla. La guida all’integrazione wallet per exchange indica di verificare che la transazione sia riuscita e di analizzare i log Transfer solo dai contratti token approvati, validando mittente, destinatario e importo. Non accrediti mai transazioni fallite. Dopo che una transazione TRC-20 è solidificata, la guida all’interazione con TRC-20 indica di confermare l’esecuzione con getTransactionInfoById e, per transfer e transferFrom, di verificare anche l’evento Transfer emesso dal contratto del token.

Una lista di controllo minima per ogni deposito TRC-20:

1. L’indirizzo del contratto è nella Sua allowlist (il contratto USDT reale, non un token simile con lo stesso nome).
2. Il risultato della transazione è un successo.
3. Esiste un evento Transfer con il Suo indirizzo di deposito come destinatario.
4. L’importo corrisponde all’ordine, usando correttamente i decimali del token.
5. Non ha già accreditato questo ID di transazione.

Il passaggio dell’allowlist conta più di quanto sembri. Chiunque può pubblicare un token chiamato «USDT». Il Suo codice deve controllare il contratto, non il simbolo.

Quando un pagamento TRON è definitivo?

Una transazione TRON attraversa quattro fasi: creazione e firma, trasmissione e validazione, inclusione in un blocco da parte di un Super Representative, e solidificazione. Secondo la documentazione del protocollo, è confermata in modo completo quando almeno 19 Super Representative attivi distinti hanno prodotto blocchi a partire dal suo blocco o oltre, il che di norma richiede circa un minuto.

Per la logica di pagamento significa questo:

• Legga dall’altezza di blocco solidificata, non dalla head della chain, così che un rollback di fork non possa annullare un pagamento già accreditato. La guida all’integrazione per exchange indica che la solidificazione avviene circa un minuto dopo la head.
• Mostri al cliente uno stato «pagamento visto» in anticipo, e uno stato «pagamento confermato» solo alla solidificazione. Così il checkout resta immediato senza rischiare un annullamento.
• Renda idempotente l’accredito. Con chiave sull’ID di transazione e sull’indice del log, un webhook ritentato o un blocco analizzato di nuovo non possono accreditare due volte un ordine.

Come proteggo wallet e chiavi private?

La stessa guida per exchange dà indicazioni chiare sulle chiavi. Usi una derivazione conforme a BIP-44 per gli indirizzi di deposito, ed esegua la firma dei prelievi offline, in un HSM o su un hardware wallet, mai con una chiave memorizzata in chiaro su un server applicativo.

In pratica:

• Derivi gli indirizzi di deposito da un unico seed protetto, così da non avere migliaia di chiavi indipendenti da custodire.
• Tenga l’ambiente di firma separato dall’applicazione esposta sul web.
• Registri ogni richiesta di prelievo con chi l’ha approvata. Richieda limiti e approvazione per gli importi elevati.

Con Chaingateway, POST /api/v2/tron/addresses crea un wallet. Se invia una password, la chiave privata viene memorizzata cifrata con essa, e per inviare passa la password al posto della chiave. Chaingateway non memorizza la password e non può ripristinare un wallet se la perdete. Per saperne di più, legga la nostra guida ai wallet TRON protetti da password.

Quanto costano Energy e Bandwidth?

Le commissioni sono il punto in cui TRON sorprende i team nuovi. Secondo la guida all’integrazione per exchange, i prelievi consumano Bandwidth, mentre i trasferimenti TRC-20 e le altre chiamate a contratti consumano anche Energy. Le risorse provengono dallo staking o dalla delega, e quando scarseggiano i TRX vengono bruciati al loro posto. Lo staking è consigliato per gli operatori ad alto volume, e fee_limit limita il budget di Energy lato chiamante per le chiamate a smart contract.

I numeri da tenere a mente, dalla documentazione sulla tokenomics di TRON:

• Tasso di bruciatura: 0,001 TRX per byte di Bandwidth e 0,0001 TRX per unità di Energy. Questi tassi possono cambiare tramite proposte, quindi li legga dalla chain invece di fissarli nel codice.
• Lo staking di TRX fornisce Bandwidth o Energy e produce TRON Power per il voto. Lo unstake avvia un periodo di attesa fissato dal parametro di chain getUnfreezeDelayDays.

Ogni account attivato riceve anche un’allowance rinnovabile di 600 Bandwidth gratuiti, che si ricarica gradualmente nell’arco di 24 ore dopo l’uso. Se Bandwidth o Energy non bastano, i TRX vengono bruciati come riserva, secondo il confronto tra TRON ed Ethereum.

Pianificare il budget delle commissioni

Prima del lancio, stimi il numero mensile di trasferimenti e le risorse che ciascuno richiede, poi decida quanto mettere in stake o delegare rispetto a quanto bruciare. Il nostro calcolatore di Energy e Bandwidth TRON e il calcolatore delle commissioni USDT-TRC20 aiutano nei calcoli. La nostra guida su Energy e Bandwidth spiega quale risorsa usa ciascuna azione, e l’articolo su come ridurre le commissioni delle transazioni TRC-20 illustra come abbassare la spesa.

Chaingateway ha endpoint per lo staking e la delega: POST /api/v2/tron/freeze e POST /api/v2/tron/delegate. Il vecchio servizio di commissioni Paymaster è deprecato. Usi TronFuel se vuole che le commissioni siano sponsorizzate per i suoi utenti. GET /api/v2/tron/chainparameters restituisce i prezzi attuali di Energy e Bandwidth.

Un’abitudine pratica: imposti sempre un fee_limit sensato nelle chiamate a contratti, e controlli le risorse disponibili di un account prima di inviare, così che un prelievo non bruci in silenzio più TRX di quelli previsti.

Come gestisco pagamenti falliti, ritardati e duplicati?

I sistemi di pagamento in produzione si giudicano dai casi limite. Ecco come gestire ciascuno su TRON.

Per i test, esegua prima l’intero flusso su una rete di test: crei un indirizzo, lo finanzi, invii un trasferimento TRX e uno TRC-20, e osservi ogni stato attraversato dal Suo sistema. Poi provochi di proposito dei fallimenti, come una chiamata a contratto senza Energy e un webhook riprodotto, e verifichi che il sistema si comporti come indicato nella tabella.

Posso accettare pagamenti nel mio token?

Se emette un token su TRON, può accettarlo come qualsiasi altro TRC-20. TRC-20 è lo standard TRON per i token fungibili implementati da smart contract. La sua interfaccia richiesta include balanceOf, transfer, transferFrom, approve, allowance, e gli eventi Transfer e Approval. Poiché queste funzioni ed eventi sono comuni, wallet ed exchange possono interagire con il Suo token senza codice speciale.

Per accettare pagamenti questo significa tre cose: aggiungere l’indirizzo del contratto alla allowlist dei depositi, verificare che i decimali siano gestiti correttamente nei controlli degli importi, e testare con piccoli trasferimenti prima di aprirlo ai clienti. Per il rilevamento, il Suo token si comporta come USDT: un evento Transfer su un contratto approvato.

Come invio pagamenti TRON tramite Chaingateway?

Si crea un wallet, si invia un trasferimento TRC-20 e ci si iscrive ai depositi con tre tipi di richiesta. L’endpoint TRC-20 richiede from, to, contractaddress e amount, più password o privatekey.

curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"from": "T...", "to": "T...", "contractaddress": "T...", "amount": 10, "password": "wallet-password"}'

X-Network: testnet usa la testnet Nile. Crei un webhook per un indirizzo ricevente con POST /api/v2/tron/webhooks, e verifichi ogni consegna con l’header X-Signature (guida alle firme). Il payload del webhook contiene txid, from, to, amount, contractaddress, blocknumber e type. Inizi dalla Blockchain API e dalle notifiche webhook. I piani partono da 49 € al mese, con una prova gratuita di 7 giorni che non richiede carta (prezzi).

Fonti

• TRX, il token nativo della rete TRON
• White paper di TRON
• Documentazione di integrazione TRON
• Firma e trasmissione: il flusso API
• Transazioni
• Guida per sviluppatori di wallet
• Integrazione DApp con TronLink
• Integrazione per exchange e wallet custodial
• Integrazione wallet per exchange con la rete TRON
• Interazione con contratti TRC-20
• Interfaccia del protocollo TRC-20
• Tokenomics
• TRON vs Ethereum

Consigliati

• API TRON: trasferimenti USDT-TRC20 e webhook di deposito
• Commissioni TRON: guida completa e calcolatore gratuito