Intégration des paiements Polygon : guide du développeur

Une intégration de paiements Polygon est l’ensemble des composants qui permet à votre application d’accepter et d’envoyer des tokens sur le réseau Polygon PoS : portefeuilles, transferts, vérification et notifications. Vous pouvez construire chaque composant sur des nœuds bruts, ou appeler une API REST qui fournit portefeuilles, transferts et webhooks. Ce guide couvre les deux voies.

TL;DR

• Polygon PoS a l’identifiant de chaîne 137 et utilise POL pour le gas. Le testnet Amoy a l’identifiant de chaîne 80002.
• Un paiement n’est acquis que lorsque vous avez vérifié le statut de la transaction, le destinataire, le montant et le contrat du token. Un hash seul ne constitue pas une preuve.
• Utilisez des webhooks, et non l’interrogation, pour suivre les paiements. Vérifiez la signature et rendez votre gestionnaire idempotent.
• Les webhooks Chaingateway ne sont pas relancés automatiquement : réconciliez donc avec la liste des notifications.
• Anticipez le cadre juridique, la garde des clés, les conflits de nonce et les variations du gas avant le lancement, et non après.

Table des matières

• Que comprend une intégration de paiement Polygon ?
• Quel réseau et quel token choisir ?
• Comment configurer les portefeuilles et protéger les clés ?
• Comment envoyer un paiement en token sur Polygon ?
• Comment vérifier qu’un paiement est arrivé ?
• Comment recevoir des notifications avec des webhooks ?
• Comment concevoir le backend ?
• Que vérifier avant le lancement ?
• FAQ
• Sources

Que comprend une intégration de paiement Polygon ?

Une intégration de paiement ne se limite pas à envoyer des tokens. Une passerelle fonctionnelle gère les portefeuilles des utilisateurs, suit l’état de chaque transaction par webhooks, et réconcilie les soldes dans une base de données. La chaîne vous dit seulement ce qui s’est passé. C’est votre backend qui décide ce que cela signifie pour une commande, une facture ou un solde.

En pratique, vous construisez cinq composants :

1. Couche portefeuille : adresses pour recevoir les fonds et clés pour les envoyer.
2. Couche transfert : code qui construit, signe et diffuse les transferts de tokens.
3. Couche de vérification : contrôles qu’un transfert a bien eu lieu comme attendu.
4. Couche de notification : webhooks qui informent votre application des changements de statut.
5. Grand livre : votre propre enregistrement en base de ce qui est dû, payé et réglé.

Les quatre premiers relèvent de la tuyauterie de la chaîne. Le cinquième est votre produit. Moins vous passez de temps sur la tuyauterie, plus vite vous livrez la partie que voient vos clients.

Ai-je besoin d’une licence ?

Déterminez où vous opérez et quelles règles s’appliquent avant d’écrire du code. Dans l’UE, le règlement sur les marchés de crypto-actifs (MiCA) encadre les prestataires de services sur crypto-actifs, comme le décrit la page MiCA de l’ESMA. Aux États-Unis, les directives de FinCEN sur les monnaies virtuelles décrivent quand administrer ou échanger des monnaies virtuelles fait de vous un transmetteur de fonds (money transmitter).

Savoir si votre modèle déclenche une règle dépend de la question de savoir si vous détenez ou transférez des fonds pour le compte d’autres. Cette question relève d’un avocat spécialisé dans les paiements, et non d’une revue de code. Posez-la avant le lancement, car la réponse peut changer le fait même que vous assuriez la garde de fonds.

Quel réseau et quel token choisir ?

Choisissez Polygon PoS avec un stablecoin comme USDC ou USDT pour la plupart des produits de paiement. La documentation Polygon indique l’identifiant de chaîne 137 et POL comme token de gas pour le mainnet, et l’identifiant 80002 pour le testnet Amoy. Codez en dur l’identifiant de chaîne dans votre code de signature, afin qu’une transaction ne puisse jamais être diffusée sur le mauvais réseau.

Les frais sont la raison pour laquelle les équipes choisissent Polygon, mais ils varient avec la congestion et le cours du POL. Concevez la gestion des frais autour de fourchettes, et lisez le prix actuel du gas au moment de l’envoi. Avec Chaingateway, GET /api/v2/polygon/gasprice le renvoie.

Ethereum est l’alternative pour les clients qui préfèrent sa liquidité et son règlement. Si vous avez besoin des deux, une API unique couvrant plusieurs chaînes vous permet d’écrire le flux de paiement une seule fois. Voir l’API Ethereum pour l’autre versant de cette configuration.

Vos portefeuilles d’envoi ont besoin de POL pour le gas, même lorsque l’actif envoyé est un stablecoin. Lorsque vous approvisionnez un portefeuille depuis une plateforme de trading, choisissez Polygon comme réseau de retrait et vérifiez l’étiquette du réseau avant de confirmer. Un retrait sur le mauvais réseau est une façon courante de perdre des fonds pendant la mise en place.

Comment configurer les portefeuilles et protéger les clés ?

Deux schémas sont courants :

• Une adresse par client ou par facture. Chaque paiement reçoit sa propre adresse de dépôt. Associer un transfert entrant à une commande devient alors trivial, car l’adresse du destinataire l’identifie. Le coût : davantage d’adresses à gérer et, plus tard, le transfert des fonds vers un portefeuille de trésorerie.
• Une adresse partagée avec des références. C’est plus simple à exploiter, mais un transfert de token classique ne porte aucun champ de référence. Vous finissez par rapprocher les paiements sur le montant et le moment, ce qui casse lorsque deux clients paient le même montant.

Pour la plupart des flux commerciaux, des adresses par commande sont le design le plus propre. Quel que soit votre choix, gardez ces habitudes :

• Ne conservez jamais de clés privées dans un système de contrôle de version, des journaux ou du code côté client.
• Séparez les portefeuilles de réception de la trésorerie qui détient votre solde, afin qu’une compromission de l’un n’expose pas l’autre.
• Limitez qui et ce qui peut déclencher un transfert sortant, et journalisez chaque demande.
• Sauvegardez le matériel de clés de façon à survivre à la perte d’une personne ou d’un serveur.

Chaingateway est non dépositaire. POST /api/v2/polygon/addresses crée un portefeuille. Si vous envoyez un password, la clé privée est stockée chiffrée avec lui, et vous utilisez le mot de passe au lieu de la clé pour envoyer une transaction. Chaingateway ne stocke pas le mot de passe et ne peut pas restaurer un portefeuille si vous le perdez. Voir créer un portefeuille crypto avec une API pour l’enchaînement des appels.

Comment envoyer un paiement en token sur Polygon ?

Polygon PoS est compatible EVM, si bien que les transferts de tokens suivent le standard ERC-20. La spécification ERC-20 définit deux schémas de paiement :

• Paiement direct : le payeur appelle transfer(recipient, amount), ce qui émet un événement Transfer.
• Paiement par prélèvement via contrat : le payeur appelle d’abord approve(spender, amount), puis le contrat autorisé appelle transferFrom(sender, recipient, amount).

Pour un paiement simple en caisse, un transfert direct suffit. Les approbations comptent lorsqu’un smart contract encaisse l’argent, comme pour les abonnements ou un séquestre (escrow). Gardez les approbations restreintes : approuvez le montant nécessaire, et non une allocation illimitée.

Comment envoyer avec du code de nœud brut ?

Envoyer directement signifie construire la transaction, estimer le gas, définir le nonce, signer, diffuser et surveiller son inclusion. C’est gérable pour un prototype. En production, il vous faut aussi un fournisseur RPC fiable, une logique de relance et un moyen de remplacer les transactions bloquées. Notre guide sur l’envoi de tokens ERC-20 compare les méthodes portefeuille, code et API.

Comment envoyer avec un seul appel REST ?

Avec Chaingateway, un transfert de token est une seule requête authentifiée. Elle nomme l’expéditeur, le contrat du token, le destinataire et le montant. Les champs de gas sont facultatifs. La définition OpenAPI rend obligatoires from, contractaddress, to et amount.

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSenderAddress",
    "contractaddress": "0xTokenContract",
    "to": "0xRecipientAddress",
    "amount": 25.5,
    "password": "wallet-password"
  }'

X-Network: testnet exécute la requête sur Amoy. Omettez l’en-tête pour le mainnet. Le même schéma fonctionne sur les autres chaînes EVM : ajouter une seconde chaîne plus tard modifie le chemin, pas le flux. Voir la page API Polygon et le fichier OpenAPI pour la liste complète des endpoints.

Comment vérifier qu’un paiement est arrivé ?

Un hash de transaction prouve seulement qu’une transaction a été soumise. Avant de marquer une commande comme payée, vérifiez le statut de la transaction, le destinataire, le montant du transfert de token et le contrat du token. Les transferts ERC-20 sont enregistrés dans les logs d’événements Transfer, comme le définit la spécification ERC-20 : le log est donc l’endroit où lire le transfert réel.

Le contrôle du contrat est celui que les équipes oublient. N’importe qui peut déployer un token nommé « USDC » qui ne vaut rien. Comparez l’adresse du contrat dans le log avec celle que vous avez mise sur liste blanche. Votre routine de vérification doit confirmer tous les points suivants :

1. La transaction a réussi, et pas seulement été minée.
2. L’événement Transfer provient du contrat de token attendu.
3. Le destinataire correspond à l’adresse émise pour cette commande.
4. Le montant est au moins égal à ce qui a été facturé, dans la plus petite unité du token.
5. Suffisamment de blocs ont passé, selon votre tolérance au risque, avant de livrer les biens.

Lire les logs bruts oblige à décoder les topics et les données à la main. Notre explication de l’événement Transfer ERC-20 montre la structure. Chaingateway renvoie aussi les transactions décodées avec GET /api/v2/polygon/transactions/{txid}/decoded.

Comment recevoir des notifications avec des webhooks ?

Interroger une adresse toutes les quelques secondes gaspille des requêtes et reste en retard. Avec un webhook, le service appelle votre endpoint lorsqu’une transaction correspondante est détectée. Créez-en un avec POST /api/v2/polygon/webhooks. Le champ url est obligatoire, et vous filtrez par to, from ou contractaddress. Voir webhooks Polygon pour le fonctionnement.

Comment construire le récepteur en toute sécurité ?

Ces règles valent pour tout fournisseur :

• Vérifiez la signature. Chaingateway ajoute un en-tête X-Signature une fois que vous avez défini un secret personnel. C’est un HMAC-SHA256 encodé en Base64 de l’identifiant de transaction, avec votre secret comme clé. Voir vérifier les signatures des webhooks.
• Comparez en temps constant. Utilisez la fonction de comparaison sécurisée de votre langage, et non ==.
• Répondez vite. Renvoyez immédiatement un statut 2xx, et effectuez le gros du travail dans une file d’attente.
• Attendez-vous aux doublons. Vous pouvez recevoir deux fois le même événement, par exemple après avoir renvoyé une notification. Enregistrez l’identifiant de transaction et ignorez les répétitions.
• Attendez-vous aux événements manqués. Chaingateway ne relance pas automatiquement les notifications échouées. Listez-les avec GET /api/v2/polygon/webhooks/notifications/failed, et renvoyez chacune avec POST /api/v2/polygon/webhooks/notifications/{id}/retry.

Quels états de paiement stocker ?

Gardez des états de paiement petits et explicites : awaiting_payment, pending, confirmed, failed, expired. Chaque webhook correspond à au plus une transition. Si un événement failed arrive pour un paiement déjà confirmé, consignez-le et alertez une personne au lieu d’écraser l’état.

Comment concevoir le backend ?

Gardez le code propre à la chaîne en périphérie. Placez une interface interne devant la chaîne, avec des méthodes telles que createDepositAddress, sendPayment et getPaymentStatus, et gardez la logique de commande de l’autre côté. Ajouter une chaîne revient alors à ajouter une implémentation de cette interface, sans réécrire le cœur.

Le grand livre doit vous appartenir. Ne considérez jamais la chaîne ou le tableau de bord d’un fournisseur comme votre registre de référence. Enregistrez chaque paiement attendu, chaque transfert observé et le lien entre les deux, afin de pouvoir réconcilier en fin de journée et expliquer tout écart.

Que vérifier avant le lancement ?

Testez trois choses en particulier : les transactions échouées, les conflits de nonce et les variations du prix du gas.

Avant le lancement

• Déroulez le flux complet sur le testnet Amoy : créez une adresse, payez-la, recevez le webhook, marquez la commande comme payée.
• Rejouez chaque webhook deux fois, et vérifiez que la seconde livraison ne change rien.
• Envoyez un paiement dans le mauvais token, avec un mauvais montant (inférieur et supérieur) et vers une commande expirée. Décidez et testez ce qui se passe dans chaque cas.
• Cassez votre endpoint volontairement avec une erreur 500 et un délai dépassé, puis listez les notifications échouées et renvoyez-les.
• Lancez deux transferts simultanés depuis le même portefeuille pour révéler les conflits de nonce.

Au lancement

• Commencez avec des plafonds bas et un seul token.
• Alertez sur tout transfert qui reste en attente au-delà de votre seuil.
• Surveillez le solde du portefeuille de gas, car un solde POL vide arrête tous les paiements sortants.
• Renouvelez votre secret personnel selon un calendrier, et mettez à jour votre récepteur en même temps.

Erreurs fréquentes

• Faire confiance au hash plutôt qu’au log d’événement.
• Faire confiance à un webhook avant d’avoir vérifié la signature.
• Coder en dur un prix du gas.
• Sauter la vérification du contrat du token.
• Garder ensemble les clés du portefeuille chaud et celles de la trésorerie.

Les forfaits commencent à 49 € par mois (490 € par an), avec un essai gratuit de 7 jours sans carte. Voir la page tarifs.

Sources

• Documentation Polygon : endpoints RPC et identifiants de chaîne
• ERC-20 : standard de token
• ESMA : règlement sur les marchés de crypto-actifs (MiCA)
• FinCEN : directives sur les personnes qui administrent, échangent ou utilisent des monnaies virtuelles

Recommandés

• API blockchain Polygon : paiements USDC et USDT via REST
• API blockchain : une API REST pour Bitcoin, Ethereum et 5 autres