Intégration des paiements TRON : guide développeur 2026

Une intégration de paiements TRON regroupe ce qui permet d’accepter et d’envoyer des TRX et des tokens TRC-20 comme l’USDT : adresses, transactions signées, détection des dépôts et contrôles de confirmation. Vous pouvez la bâtir sur les API de nœud, ou appeler une API REST qui crée des portefeuilles et envoie des transferts. Ce guide couvre les deux voies.

TL;DR

• Les paiements en TRX sont des transferts natifs de compte à compte. Les paiements TRC-20 (comme l’USDT) sont des appels de smart contract : ils consomment donc de l’Energy en plus de la Bandwidth.
• Chaque opération qui modifie l’état suit trois étapes : construire une transaction non signée, la signer avec la clé de l’expéditeur, la diffuser à un nœud.
• Ne créditez les dépôts qu’à partir de blocs solidifiés, uniquement pour les transactions réussies, et pour le TRC-20 uniquement depuis les contrats de tokens que vous avez approuvés.
• Les frais dépendent des ressources stakées ou déléguées. Anticipez-les avant le lancement, sinon des TRX sont brûlés à chaque transfert.
• Vous pouvez vous passer de faire tourner des nœuds et des analyseurs de blocs en utilisant une API de portefeuille, de transfert et de webhooks comme celle de Chaingateway. Ses webhooks ne sont pas relancés automatiquement : prévoyez donc une réconciliation.

Table des matières

• Comment fonctionnent les paiements TRON ?
• Faut-il construire sur les API de nœud ou utiliser une API ?
• Comment construire, signer et diffuser une transaction ?
• Comment détecter les paiements entrants ?
• Quand un paiement TRON est-il final ?
• Comment protéger les portefeuilles et les clés privées ?
• Combien coûtent l’Energy et la Bandwidth ?
• Comment gérer les paiements échoués, retardés et en double ?
• Puis-je accepter des paiements dans mon propre token ?
• Comment envoyer des paiements TRON via Chaingateway ?
• FAQ
• Sources

Comment fonctionnent les paiements TRON ?

TRX est le token natif de TRON. Il paie les frais de réseau, et le staker donne accès aux ressources du réseau et aux droits de vote, selon la documentation TRON sur TRX. Le gros du volume de paiement sur TRON passe pourtant par des tokens comme l’USDT-TRC20. Il faut donc comprendre les deux types de transfert.

Un paiement en TRX est un simple transfert de compte à compte sur la chaîne. Un paiement TRC-20 est différent : l’expéditeur appelle la fonction de transfert du contrat du token, qui met à jour les soldes à l’intérieur du contrat et émet un événement Transfer. Les deux finissent enregistrés sur TRON, mais les transferts TRC-20 demandent une exécution de smart contract. Ils consomment donc Bandwidth et Energy, comme le décrit le livre blanc de TRON.

Cette différence façonne toute votre intégration :

Faut-il construire sur les API de nœud ou utiliser une API ?

La documentation d’intégration de TRON liste ce que comprend une intégration type : connecter les portefeuilles des utilisateurs finaux, construire et signer les transactions, surveiller les dépôts et les retraits, et utiliser soit TronGrid, soit un nœud complet auto-hébergé. Les opérateurs d’échanges et de portefeuilles custodiaux gèrent la surveillance des dépôts, les retraits et les requêtes de soldes et d’historique sur la même base.

Cela vous laisse deux voies réalistes.

Voie un : construire sur les API de nœud. Vous gardez le contrôle total. Mais vous assumez aussi la dérivation des adresses, l’analyse des blocs, la logique de relance, la gestion des ressources et, si vous auto-hébergez, la maintenance du nœud. Notre guide d’installation d’un nœud TRON couvre la voie Lite FullNode, avec un jar ou Docker si vous la choisissez.

Voie deux : utiliser une API de portefeuille et de webhooks. Vous appelez un endpoint REST pour créer un portefeuille, un autre pour envoyer un transfert, et vous recevez un webhook signé lorsqu’un dépôt arrive. Notre API TRON est conçue pour cela : transferts USDT-TRC20 et webhooks de dépôt, sans exploiter de nœuds. Les endpoints figurent dans la définition OpenAPI.

Une règle empirique utile : si les paiements sont le principal atout différenciant de votre produit et que vous avez une équipe pour exploiter l’infrastructure, construisez. Si les paiements ne sont qu’une fonction d’autre chose, une API vous amène plus vite en production et laisse vos ingénieurs sur votre produit.

Comment construire, signer et diffuser une transaction ?

Que vous utilisiez des appels bruts au nœud ou un SDK, toute opération TRON qui modifie l’état suit le même flux en trois étapes : construire une transaction non signée via une API de nœud, la signer côté client avec la clé privée de l’expéditeur, puis diffuser la transaction signée à un nœud.

Deux détails méritent attention :

• TAPOS. Chaque transaction référence un bloc récent, ce qui limite le rejeu sur les branches de la chaîne qui ne contiennent pas ce bloc, selon la documentation du protocole sur les transactions. En pratique, construisez et signez au plus près du moment de la diffusion. Une transaction signée puis mise de côté longtemps peut expirer.
• Utilisez les helpers SDK pour la signature. Le guide du développeur de portefeuilles recommande les helpers SDK en production plutôt que des primitives de signature écrites à la main, pour éviter les cas limites liés à la sérialisation protobuf et à la récupération de signature. N’écrivez pas les vôtres.

Pour les flux dans le navigateur où l’utilisateur paie depuis son propre portefeuille, le guide d’intégration DApp décrit deux options : TronWallet Adapter pour un support unifié de plusieurs portefeuilles, ou une intégration directe de TronLink, qui injecte un provider dans window.tron. Les paiements marchands qui génèrent une adresse de dépôt par commande n’ont généralement pas besoin de cela. Le client paie depuis le portefeuille qu’il utilise déjà.

Comment détecter les paiements entrants ?

Le modèle marchand typique est une adresse de dépôt par commande ou par client. Votre travail consiste alors à repérer l’arrivée des fonds sur ces adresses.

Le guide d’intégration pour les échanges et portefeuilles custodiaux décrit deux méthodes de détection : interroger toutes les quelques secondes les API d’historique de compte de TronGrid, ou analyser les blocs séquentiellement. Si vous analysez les blocs, utilisez la dernière hauteur solidifiée, et récupérez les logs d’événements et les transactions internes séparément des résultats d’exécution, en les traitant comme des enregistrements distincts.

Ne pas manquer les transactions internes

C’est le trou le plus courant dans les intégrations maison. Des utilisateurs peuvent recevoir des TRX ou des tokens TRC-10 via un appel de smart contract, et ces transferts n’apparaissent pas comme des transactions de premier niveau. Le même guide indique d’analyser les transactions internes lorsque vous créditez des dépôts. Si votre écouteur ne surveille que les transferts de premier niveau, certains clients paieront sans jamais être crédités.

Vérifier correctement les dépôts TRC-20

Pour les dépôts de tokens, un hash de transaction ne prouve rien à lui seul. Le guide d’intégration de portefeuille d’échange demande de vérifier que la transaction a réussi, et de ne lire les logs Transfer que depuis les contrats de tokens approuvés, en validant l’expéditeur, le destinataire et le montant. Ne créditez jamais des transactions échouées. Une fois la transaction TRC-20 solidifiée, le guide d’interaction TRC-20 demande de confirmer l’exécution avec getTransactionInfoById et, pour transfer et transferFrom, de vérifier aussi l’événement Transfer émis par le contrat du token.

Une liste de vérification minimale pour chaque dépôt TRC-20 :

1. L’adresse du contrat figure sur votre liste blanche (le vrai contrat USDT, pas un token au nom similaire).
2. Le résultat de la transaction est un succès.
3. Un événement Transfer existe, avec votre adresse de dépôt comme destinataire.
4. Le montant correspond à la commande, avec les décimales du token correctement appliquées.
5. Vous n’avez pas déjà crédité cet identifiant de transaction.

L’étape de la liste blanche compte plus qu’il n’y paraît. N’importe qui peut déployer un token qui s’appelle « USDT ». Votre code doit vérifier le contrat, et non le symbole.

Quand un paiement TRON est-il final ?

Une transaction TRON traverse quatre phases : création et signature, diffusion et validation, inclusion dans un bloc par un Super-Représentant, puis solidification. Selon la documentation du protocole, elle est entièrement confirmée lorsqu’au moins 19 Super-Représentants actifs distincts ont produit des blocs à son bloc ou au-delà. Cela prend généralement une minute environ.

Pour votre logique de paiement, cela signifie :

• Lisez à partir de la hauteur de bloc solidifiée, et non de la tête de chaîne, afin qu’un retour arrière de fork ne puisse pas annuler un paiement déjà crédité. Le guide d’intégration pour les échanges indique que la solidification se situe à environ une minute derrière la tête.
• Montrez au client un état « paiement vu » tôt, et un état « paiement confirmé » uniquement à la solidification. Le passage en caisse reste ainsi instantané, sans risquer une annulation.
• Rendez le crédit idempotent. Clé sur l’identifiant de transaction et l’index du log, un webhook relancé ou un bloc analysé à nouveau ne peut pas créditer deux fois une commande.

Comment protéger les portefeuilles et les clés privées ?

Le même guide d’échange donne des consignes claires sur les clés. Utilisez une dérivation conforme à BIP-44 pour les adresses de dépôt, et effectuez la signature des retraits hors ligne, dans un HSM ou sur un portefeuille matériel, jamais avec une clé stockée en clair sur un serveur applicatif.

En pratique :

• Dérivez les adresses de dépôt à partir d’une seule graine protégée, afin de ne pas avoir des milliers de clés indépendantes à sauvegarder.
• Séparez l’environnement de signature de l’application exposée sur le web.
• Journalisez chaque demande de retrait avec le nom de la personne qui l’a approuvée. Imposez des plafonds et une approbation pour les montants élevés.

Avec Chaingateway, POST /api/v2/tron/addresses crée un portefeuille. Si vous envoyez un password, la clé privée est stockée chiffrée avec lui, et vous transmettez le mot de passe au lieu de la clé lors de l’envoi. Chaingateway ne stocke pas le mot de passe et ne peut pas restaurer un portefeuille si vous le perdez. Pour en savoir plus, lisez notre guide des portefeuilles TRON protégés par mot de passe.

Combien coûtent l’Energy et la Bandwidth ?

Les frais sont le point où TRON surprend les nouvelles équipes. Selon le guide d’intégration pour les échanges, les retraits consomment de la Bandwidth, tandis que les transferts TRC-20 et les autres appels de contrat consomment aussi de l’Energy. Les ressources proviennent du staking ou de la délégation ; lorsqu’elles viennent à manquer, des TRX sont brûlés à la place. Le staking est recommandé pour les opérateurs à fort volume, et fee_limit plafonne le budget d’Energy côté appelant pour les appels de smart contract.

Les chiffres à garder en tête, tirés de la documentation de tokenomics de TRON :

• Taux de combustion : 0,001 TRX par octet de Bandwidth et 0,0001 TRX par unité d’Energy. Ces taux peuvent être modifiés par des propositions : lisez-les donc sur la chaîne plutôt que de les coder en dur.
• Staker des TRX fournit de la Bandwidth ou de l’Energy et produit du TRON Power pour voter. Le déstaking déclenche une période d’attente fixée par le paramètre de chaîne getUnfreezeDelayDays.

Chaque compte activé reçoit aussi une allocation renouvelable de 600 octets de Bandwidth gratuits, qui se reconstitue progressivement sur 24 heures après usage. Des TRX sont brûlés en repli lorsque la Bandwidth ou l’Energy ne suffisent pas, selon la comparaison TRON et Ethereum.

Planifier votre budget de frais

Avant le lancement, estimez le nombre de transferts mensuels et les ressources que chacun demande, puis décidez combien staker ou déléguer par rapport à ce qui sera brûlé. Notre calculateur d’Energy et de Bandwidth TRON et le calculateur de frais USDT-TRC20 vous aident pour le calcul. Notre guide sur Energy et Bandwidth explique quelle ressource chaque action consomme, et l’article sur la réduction des frais de transactions TRC-20 présente des moyens de réduire la dépense.

Chaingateway propose des endpoints pour le staking et la délégation : POST /api/v2/tron/freeze et POST /api/v2/tron/delegate. L’ancien service de frais Paymaster est déprécié. Utilisez TronFuel si vous voulez que les frais soient pris en charge pour vos utilisateurs. GET /api/v2/tron/chainparameters renvoie les prix actuels de l’Energy et de la Bandwidth.

Une habitude pratique : fixez toujours un fee_limit raisonnable sur les appels de contrat, et vérifiez les ressources disponibles d’un compte avant d’envoyer, afin qu’un retrait ne brûle pas discrètement plus de TRX que votre budget.

Comment gérer les paiements échoués, retardés et en double ?

Les systèmes de paiement de production gagnent leur valeur dans les cas limites. Voici comment traiter chacun sur TRON.

Pour les tests, déroulez d’abord le flux complet sur un réseau de test : créez une adresse, approvisionnez-la, envoyez un transfert TRX et un transfert TRC-20, et observez chaque état que traverse votre système. Déclenchez ensuite délibérément des échecs, comme un appel de contrat à court d’Energy et un webhook rejoué, et vérifiez que votre système se comporte comme l’indique le tableau ci-dessus.

Puis-je accepter des paiements dans mon propre token ?

Si vous émettez un token sur TRON, vous pouvez l’accepter comme n’importe quel TRC-20. TRC-20 est le standard TRON pour les tokens fongibles implémentés par des smart contracts. Son interface requise comprend balanceOf, transfer, transferFrom, approve, allowance, ainsi que les événements Transfer et Approval. Comme ces fonctions et ces événements sont communs, les portefeuilles et les échanges peuvent interagir avec votre token sans code spécifique.

Pour l’acceptation de paiements, cela implique trois choses : ajouter l’adresse de votre contrat à votre liste blanche de dépôts, vérifier que les décimales sont correctement gérées dans les contrôles de montant, et tester avec de petits transferts avant de l’ouvrir aux clients. Votre token se comporte comme l’USDT en matière de détection : un événement Transfer sur un contrat approuvé.

Comment envoyer des paiements TRON via Chaingateway ?

Créez un portefeuille, envoyez un transfert TRC-20 et abonnez-vous aux dépôts avec trois types de requêtes. L’endpoint TRC-20 exige from, to, contractaddress et amount, ainsi que password ou 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 utilise le testnet Nile. Créez un webhook pour une adresse de réception avec POST /api/v2/tron/webhooks, et vérifiez chaque livraison avec l’en-tête X-Signature (guide de signature). La charge utile du webhook contient txid, from, to, amount, contractaddress, blocknumber et type. Commencez par l’API blockchain et les notifications webhook. Les forfaits commencent à 49 € par mois, avec un essai gratuit de 7 jours sans carte (tarifs).

Sources

• TRX, le token natif du réseau TRON
• Livre blanc de TRON
• Documentation d’intégration TRON
• Signer et diffuser : le flux de l’API
• Transactions
• Guide du développeur de portefeuilles
• Intégration DApp avec TronLink
• Intégration pour les échanges et portefeuilles custodiaux
• Intégration d’un portefeuille d’échange avec le réseau TRON
• Interaction avec un contrat TRC-20
• Interface du protocole TRC-20
• Tokenomics
• TRON et Ethereum

Recommandés

• API TRON : transferts USDT-TRC20 et webhooks de dépôt
• Frais TRON : guide complet et calculateur gratuit