Intégration des paiements Ethereum pour développeurs

L’intégration des paiements Ethereum consiste à accepter de l’ETH ou des tokens dans votre application : attribuer une adresse unique à chaque client, détecter la transaction à son arrivée, décider quand elle est définitive et la rapprocher de la commande. Vous pouvez la construire sur des nœuds et du JSON-RPC, ou appeler une API qui gère portefeuilles et notifications.

Ce guide couvre les deux approches, pour que vous puissiez choisir en connaissant les compromis.

TL;DR

• Un paiement Ethereum est une transaction signée qui déplace de l’ETH ou des tokens. Soumettre une transaction ne revient pas à la confirmer : vous devez vérifier le reçu.
• Décidez d’abord : ETH seul, stablecoins et tokens ERC-20, ou votre propre token. Ce choix détermine la gestion des événements et votre stratégie de gaz.
• Utilisez une adresse de dépôt par commande ou par utilisateur, et écoutez les événements par webhooks plutôt que par polling.
• Considérez les clés privées, les signatures de webhook et le code des contrats comme les trois principales surfaces de sécurité.
• Une API comme Chaingateway remplace le nœud et le scanner de blocs, avec des plans à partir de 49 € par mois. Les paramètres de gaz et la politique de confirmation restent vos décisions.

Qu’est-ce qu’un paiement Ethereum ?

Un paiement Ethereum est une instruction signée cryptographiquement, émise par un compte, qui met à jour l’état du réseau, par exemple en transférant de l’ETH ou des tokens. Selon la documentation d’ethereum.org sur les transactions, un validateur vérifie ensuite la transaction et l’inclut dans un bloc. L’argent n’existe à l’adresse du destinataire qu’à partir de ce moment.

Pour votre application, cela a une conséquence pratique. Le client ne vous paie pas vous. Il diffuse une transaction sur le réseau, et votre système doit la remarquer. Toute intégration revient à résoudre ce problème d’observation.

Vous rencontrerez deux types de paiement :

1. Les transferts d’ETH natif. La transaction elle-même porte un destinataire et une valeur. C’est simple, et visible directement dans la transaction et son reçu.
2. Les transferts de tokens (ERC-20 et similaires). La transaction est envoyée au contrat du token, qui met à jour les soldes en interne. La norme définit pour cela un événement Transfer, comme l’expose la spécification ERC-20 sur ethereum.org. Votre système apprend le paiement par ce journal d’événements, et non par le champ de valeur de la transaction.

La plupart des paiements en stablecoins sont du second type. Si vous ne surveillez que l’arrivée d’ETH à une adresse, vous les manquerez.

Que faut-il décider avant d’écrire du code ?

Quels actifs accepter ?

Commencez par l’ensemble le plus réduit qui sert vos clients. L’ETH seul est le plus simple à mettre en œuvre. Ajouter un stablecoin supprime la volatilité des prix, ce qui compte pour les factures et les abonnements. Si vous émettez votre propre token, vous devez aussi connaître ses décimales, son adresse de contrat et savoir s’il se comporte comme un ERC-20 standard.

Chaque actif supplémentaire ajoute une adresse de contrat à surveiller, une valeur de décimales à appliquer et une règle de tarification. Gardez une petite liste autorisée et refusez tout le reste, volontairement.

Paiement hébergé, liens de paiement ou API ?

Il existe trois formes d’intégration, qui échangent du contrôle contre de la vitesse :

Approche	Adaptée à	Vous contrôlez	Vous renoncez à
Paiement hébergé ou lien de paiement	Lancement rapide, faible volume	Presque rien du flux	Image de marque, garde des fonds, logique sur mesure
Wallet-connect dans votre propre front-end	Dapps dont les utilisateurs détiennent déjà de l’ETH	L’expérience utilisateur	La détection et le rapprochement restent à votre charge
API backend avec portefeuilles et webhooks	Applications, places de marché, facturation SaaS	Adresses, montants, logique de commande	L’exploitation de votre propre infrastructure

Si vous intégrez des paiements dans un produit en tant que développeur, vous vous retrouverez généralement sur la troisième ligne. Une liste de contrôle utile pour tout fournisseur : propose-t-il un sandbox, des formats d’erreur clairs, des limites de débit documentées et des webhooks adaptés à votre stack ?

Garde des fonds et conformité

Qui détient les clés ? Si votre plateforme génère des portefeuilles de dépôt pour les clients, vous manipulez des fonds. Selon votre juridiction et votre modèle économique, cela peut entraîner des obligations de licence ou de déclaration. Consultez un avocat qui connaît votre marché avant le lancement, pas après. Ce guide traite de l’ingénierie, pas de conseil juridique.

Comment fonctionne le flux de paiement, étape par étape ?

Voici la séquence qui tient en production, que vous la construisiez ou que vous l’achetiez.

1. Créer une demande de paiement

Quand le client arrive à la caisse, créez un enregistrement de commande avec un montant, un actif et une expiration. Attribuez ensuite une adresse de réception unique à cette commande. Une adresse unique par commande permet de rattacher un transfert entrant au bon client, sans lui demander de coller un mémo ou une référence.

Fixez le prix de la commande dans une unité stable. Si vous acceptez des actifs volatils, verrouillez un montant en ETH pour une courte fenêtre. Stockez les deux montants.

2. Le client signe et soumet

Si le client paie depuis un portefeuille de navigateur, votre front-end demande l’autorisation d’utiliser son compte, construit un objet de transaction et le soumet. La référence eth_sendTransaction de MetaMask décrit cet ordre : obtenir l’autorisation du compte, soumettre la transaction, conserver le hash retourné. Si le client envoie plutôt depuis une plateforme d’échange ou un portefeuille mobile vers l’adresse que vous affichez, vous ne voyez jamais cette étape. Vous ne voyez que le résultat on-chain.

Dans les deux cas, le hash de transaction est le numéro de reçu du paiement. Stockez-le.

3. Détecter la transaction

Vous avez trois options pour remarquer un paiement :

• Le polling. Demandez à un nœud le reçu ou le solde de l’adresse toutes les quelques secondes. C’est simple, mais coûteux en requêtes et fragile à grande échelle.
• Les abonnements. Ouvrez un WebSocket vers un nœud et abonnez-vous aux nouveaux blocs ou aux journaux des contrats. La documentation de go-ethereum sur les événements en temps réel décrit eth_subscribe précisément pour cet usage. Vous devez gérer vous-même les connexions interrompues et le rejeu des blocs manqués.
• Les webhooks. Un service surveille la chaîne et appelle votre serveur quand un événement pertinent se produit. C’est l’option qui demande le moins de maintenance, et celle que la plupart des équipes choisissent.

Pour les tokens, vous surveillez les journaux d’événements. La documentation d’Ethereum indique que les applications peuvent écouter les événements d’un contrat via l’API JSON-RPC et réagir aux journaux qu’ils émettent.

4. Confirmer le résultat

Soumettre n’est pas confirmer. Le guide d’envoi de transactions de MetaMask montre le schéma : interrogez le reçu par son hash. L’absence de reçu signifie que la transaction est encore en attente, le statut 0x1 signifie un succès et 0x0 un échec. La référence eth_getTransactionReceipt précise que le reçu contient le numéro de bloc, le gaz utilisé et les journaux.

La machine à états de votre commande doit refléter cela explicitement :

1. awaiting_payment : adresse émise, rien de vu.
2. pending : une transaction correspondante est visible, mais pas encore dans un bloc.
3. confirmed : reçu trouvé, statut réussi, montant et actif conformes.
4. final : assez de blocs supplémentaires se sont écoulés pour votre tolérance au risque.
5. failed, underpaid, overpaid ou expired : les cas qui demandent une règle, pas un haussement d’épaules.

Le nombre de blocs à attendre avant de livrer les biens est une décision métier. Les biens numériques de quelques dollars peuvent partir dès la première confirmation. Les commandes de forte valeur méritent une attente plus longue, car un bloc peut parfois être réorganisé avant que le réseau ne se stabilise.

5. Rapprocher

Comparez chaque jour la somme des paiements confirmés dans votre base de données avec ce que la chaîne indique comme arrivé à vos adresses. Tout écart est un bug, un webhook manqué ou un client qui a payé avec le mauvais actif. La section données et analyses d’ethereum.org liste des indexeurs qui servent l’historique des journaux d’événements, ce qui peut réduire la part que vous devez maintenir vous-même.

Comment fonctionnent le gaz, les transactions échouées et les remboursements ?

Le gaz est le point sur lequel de nombreuses premières intégrations sont surprises. Chaque transaction paie des frais composés d’un frais de base et d’un frais de priorité, et c’est l’expéditeur qui les paie, comme l’explique la documentation sur les transactions. Trois conséquences en découlent pour vous.

• Les clients peuvent sous-payer ou bloquer leur transaction. S’ils fixent des frais trop bas, la transaction reste en attente. Votre commande ne doit pas expirer tant qu’une transaction valide est en cours.
• Les transactions échouées coûtent quand même du gaz. Un transfert de token annulé produit un reçu au statut d’échec, et les fonds du client ne bougent pas. Ne marquez pas la commande comme payée parce que vous avez vu un hash.
• Envoyer de votre côté a un coût. Les remboursements, les balayages des adresses de dépôt vers un portefeuille de trésorerie et les paiements sortants demandent tous du gaz, et les adresses de tokens ont besoin d’ETH pour déplacer des tokens. Estimez les frais avant d’envoyer, et prévoyez-les dans votre budget.

Dans l’API Chaingateway, gas, gasprice, maxFeePerGas et maxPriorityFeePerGas sont des champs facultatifs des endpoints de transaction ERC-20 et ETH, et GET /api/v2/ethereum/gasprice retourne le prix actuel du gaz. Notre guide sur l’estimation des frais de gaz sur Ethereum et d’autres chaînes détaille les méthodes d’estimation.

Si vous voulez que les clients paient sans détenir d’ETH, l’abstraction de compte permet aux développeurs de sponsoriser les transactions, comme le décrit le tutoriel d’ethereum.org sur le sponsoring des frais de gaz. Elle ajoute de la complexité côté contrat. Réservez-la aux produits où la friction du gaz vous coûte réellement des conversions.

Pour les remboursements, décidez de la politique à l’avance. Remboursez à l’adresse d’envoi seulement après avoir vérifié qu’il ne s’agit pas d’une adresse de dépôt d’une plateforme d’échange que vous ne pouvez pas contrôler, ou demandez une adresse de remboursement au client. Déduisez ouvertement les frais de réseau ou absorbez-les, mais consignez la règle par écrit.

Comment sécuriser les clés, les signatures et les contrats ?

Clés privées

Celui qui détient la clé contrôle les fonds. Générez les clés dans un environnement renforcé, ne les journalisez jamais, ne les commitez jamais, et séparez les hot wallets (petits soldes, utilisés pour les paiements sortants) du stockage à froid (l’essentiel des fonds). Balayez les adresses de dépôt vers le stockage à froid selon un calendrier.

Authenticité des webhooks

Un endpoint de webhook est une URL publique qui peut marquer des commandes comme payées. Quiconque la trouve peut donc poster un faux événement. Protégez-le de quatre manières :

• Vérifiez une signature sur chaque requête. La signature HMAC est l’approche courante. Si le schéma inclut un horodatage, rejetez les horodatages périmés.
• Rendez le gestionnaire idempotent, pour qu’une livraison en double ne crédite pas deux fois une commande.
• Confirmez le montant et le destinataire par une recherche directe avant de livrer les biens.
• L’en-tête X-Signature de Chaingateway ne couvre que l’ID de transaction, comme l’explique l’article sur la vérification de signature : la recherche directe est donc nécessaire.

Code des Smart Contracts

Si vous écrivez vos propres contrats de paiement, le risque se déplace vers le code. Le rapport de sécurité d’Ethereum lui-même note que les audits, les bibliothèques testées, la vérification formelle et l’analyse statique améliorent tous la sécurité des contrats, et que du code sur mesure pour des contrôles avancés peut accroître le risque de vulnérabilité. La règle pratique : ne déployez pas de contrat sur mesure quand une adresse simple et les événements de token standard suffisent à votre cas d’usage.

Faut-il le construire soi-même ou utiliser une API ?

La voie du « faites-le vous-même » consiste à exploiter ou louer des nœuds et à écrire un générateur d’adresses. Vous construisez aussi le décodeur de journaux pour chaque token accepté, vous estimez le gaz, vous gérez les réorganisations et vous maintenez le tout en service. C’est une voie raisonnable pour une équipe dont le produit est l’infrastructure de paiement.

Pour tous les autres, le coût est le temps et la maintenance continue. La question d’architecture est de savoir s’il faut recevoir les événements au fil de l’eau ou rapprocher par lots plus tard. Pour des paiements, recevoir les événements au fil de l’eau est le meilleur choix par défaut.

Notre comparaison des types d’API blockchain et de leurs cas d’usage présente les catégories. La présentation d’Ethereum explique l’ETH, le gaz et les tokens ERC-20 aux équipes qui découvrent la chaîne.

Comment Chaingateway s’intègre-t-il dans une intégration Ethereum ?

L’API Ethereum permet d’envoyer des tokens ERC-20 via REST, sans web3.js. Trois endpoints couvrent l’essentiel d’un flux de paiement :

Étape	Endpoint
Créer une adresse de dépôt	POST /api/v2/ethereum/addresses
La surveiller pour l’ETH ou les tokens entrants	POST /api/v2/ethereum/webhooks avec to, url et type (ETH, ERC20 ou ERC721)
Envoyer l’ETH ou un token ERC-20 plus loin	POST /api/v2/ethereum/transactions ou .../transactions/erc20

Un paiement sortant en ERC-20 demande l’expéditeur, le destinataire, contractaddress et amount, plus le password du portefeuille pour les portefeuilles que l’API a créés avec un mot de passe. L’erreur 422 pour un solde insuffisant en frais est insufficient funds for gas * price + value. Testez d’abord sur Sepolia en ajoutant l’en-tête X-Network: testnet. La page Webhooks Chaingateway et la Blockchain API couvrent les autres réseaux pris en charge avec les mêmes appels.

Les notifications de webhook échouées ne sont pas renvoyées automatiquement. Listez-les avec GET /api/v2/ethereum/webhooks/notifications/failed et renvoyez-les une par une.

Les plans sont facturés selon l’usage et les fonctionnalités : Plus à 49 € par mois, Pro à 99 €, Premium à 249 € et Enterprise à 499 €, ou 490 €, 990 €, 2 490 € et 4 990 € par an en facturation annuelle. Chaque plan démarre par un essai gratuit de 7 jours, sans carte ni KYC. Consultez la page des tarifs pour le détail de chaque plan.

Comment tester et surveiller une intégration de paiement Ethereum ?

Une intégration de paiement n’est pas terminée quand la démo fonctionne. Parcourez cette liste d’abord sur un réseau de test, puis de nouveau avec de petits montants réels :

• Paiement exact, sous-paiement et surpaiement, à la fois en ETH et pour chaque token accepté.
• Paiement tardif après l’expiration de la commande, et double paiement vers la même adresse.
• Une transaction échouée avec une limite de gaz basse, pour voir un reçu d’échec et vérifier que la commande ne se finalise pas.
• Webhooks en double et hors ordre, rejoués volontairement.
• Votre propre indisponibilité : arrêtez votre serveur dix minutes, envoyez un paiement, redémarrez et vérifiez que rien n’est perdu.
• Les flux de portefeuille dans le front-end. Les équipes QA peuvent les tester en non-régression sans détenir de clés privées, avec des outils comme celui présenté sur la page Impersonator.xyz d’ethereum.org.

Après le lancement, déclenchez des alertes sur trois signaux : les commandes bloquées en pending au-delà d’un seuil, un écart entre les totaux de la base de données et les totaux on-chain, et les échecs de livraison de webhooks. Le premier révèle les problèmes de frais, le deuxième les événements manqués, le troisième vos propres pannes.

Sources

• Transactions, ethereum.org
• ERC-20 Token Standard, ethereum.org
• eth_sendTransaction, MetaMask documentation
• eth_getTransactionReceipt, MetaMask documentation
• Send transactions, MetaMask documentation
• Real-time Events, go-ethereum
• Logging data from smart contracts with events, ethereum.org
• Sponsoring gas fees, ethereum.org
• Security Challenges Overview, ethereum.org
• Data and analytics, ethereum.org
• Impersonator.xyz, ethereum.org

Recommandé

• Ethereum API – Send ERC-20 Tokens via REST, No web3.js
• Ethereum Overview: ETH, Gas Fees and ERC-20 Tokens Explained
• Blockchain API – One REST API for Bitcoin, Ethereum & 5 More
• Receive Crypto Payments in Laravel — How-To