API blockchain pour les paiements e-commerce
Comment une boutique accepte des cryptomonnaies et verse des fonds via une API blockchain : une adresse par commande, webhooks, confirmations et remboursements.
Relu par Maurice Sobiera
Une API blockchain pour l’e-commerce est une interface REST qui permet à une boutique de créer des adresses de paiement, de détecter les paiements crypto entrants et d’envoyer des remboursements ou des versements, sans faire tourner ses propres nœuds. La boutique communique en HTTPS et reçoit des webhooks à l’arrivée d’un paiement. Les clés et les règles de confirmation restent sous son contrôle.
Comment une boutique en ligne accepte-t-elle des paiements crypto via une API ?
Attribuez à chaque commande sa propre adresse de dépôt, surveillez-la avec un webhook et marquez la commande comme payée lorsque le montant confirmé correspond. Le processus comporte cinq étapes :
- Créez une adresse pour la commande avec
POST /api/v2/{blockchain}/addresses. - Enregistrez un webhook pour cette adresse avec
POST /api/v2/{blockchain}/webhooks, et placez l’identifiant de votre commande dans le champreference. - Affichez au client l’adresse, le montant et une date d’expiration.
- Lorsque le webhook arrive, vérifiez l’en-tête
X-Signatureet contrôlez le montant et le token sur la chaîne. - Libérez les produits une fois le nombre de confirmations que vous avez défini atteint.
Une adresse par commande supprime toute incertitude : chaque paiement reçu sur cette adresse appartient à cette commande. Le guide des webhooks de paiement montre le code du récepteur, et le tutoriel Laravel présente le même flux dans un framework PHP.
Que doit enregistrer la fiche de commande ?
Stockez assez de données pour décider vous-même si un paiement est complet. Le webhook vous indique qu’un événement s’est produit. La fiche de commande vous indique ce qui aurait dû se produire.
| Champ | Rôle |
|---|---|
| Identifiant de commande | Envoyé aussi comme reference du webhook, pour faire correspondre l’événement |
| Réseau et token | La chaîne et le contrat que le client doit utiliser |
| Adresse de dépôt | L’adresse créée pour cette commande |
| Montant attendu | Converti à partir du prix de la boutique au moment de l’émission de la facture |
| Expiration de la facture | Délai au-delà duquel le prix n’est plus valable |
| Confirmations requises | La règle que vous avez choisie pour ce réseau et la taille de la commande |
| Statut | En attente, partiellement payée, payée, expirée ou remboursée |
Avec ces champs, le traitement du webhook se résume à une comparaison. Recherchez la commande par reference, vérifiez que le réseau et le token correspondent, ajoutez le montant reçu jusqu’ici et mettez à jour le statut. Un paiement d’un mauvais token sur la bonne adresse est un cas courant que le traitement doit détecter, car une adresse peut recevoir n’importe quel token de son réseau.
Combien de confirmations une boutique doit-elle attendre ?
Cela dépend du réseau et de la valeur de la commande. La documentation pour développeurs de Bitcoin sur le traitement des paiements indique qu’une transaction sans confirmation ne doit pas être considérée comme fiable sans analyse de risque. Elle précise qu’un logiciel traitant des transactions de forte valeur doit attendre au moins six confirmations, soit environ une heure. Sur TRON, un bloc est solidifié dès qu’au moins 19 des 27 Super Représentants ont construit dessus. La documentation sur le consensus de TRON situe ce délai à environ une minute dans des conditions normales.
Choisissez une règle par réseau et par taille de commande, notez-la et appliquez-la dans le code. Un article numérique de faible valeur peut être livré après une seule confirmation. Un article physique de grande valeur doit attendre plus longtemps.
Que faire face aux variations de prix ?
Fixez le prix dans votre propre devise, convertissez-le au moment d’émettre la facture et laissez la facture expirer. La documentation Bitcoin indique que les taux de change varient, que les factures indexées sur une monnaie fiduciaire doivent expirer et que la plupart des systèmes de paiement les font expirer au bout de 10 à 20 minutes. Une fenêtre plus courte réduit le risque de change, mais augmente la probabilité qu’un client paie en retard.
Décidez à l’avance de ce qui se passe pour un paiement tardif ou partiel. La plupart des boutiques le remboursent, ou demandent au client de payer la différence à la même adresse.
Comment fonctionnent les remboursements et les versements ?
Envoyez-les sous forme de transactions ordinaires depuis une adresse que vous contrôlez. Utilisez POST /api/v2/{blockchain}/transactions pour la monnaie native, et les points de terminaison dédiés aux tokens, comme transactions/erc20, transactions/bep20 ou transactions/trc20. Un remboursement nécessite l’adresse de retour du client, que vous devez demander séparément, car l’expéditeur d’un paiement n’est pas toujours le portefeuille qui doit recevoir l’argent en retour, par exemple lorsque le paiement provient d’une plateforme d’échange.
Ne laissez pas les fonds d’une adresse de commande y séjourner longtemps. Transférez les paiements entrants vers un portefeuille que vous détenez hors ligne, et n’utilisez les adresses de commande que pour encaisser. Nos conseils de sécurité expliquent comment conserver les clés.
Comment maîtriser les frais de réseau ?
Prévoyez les frais côté émetteur. Sortir des tokens d’une adresse de commande coûte du gas sur les réseaux EVM, et de l’Energy ou de la Bandwidth sur TRON, et l’adresse de commande doit disposer de suffisamment de monnaie native pour cela. Sur TRON, sponsoriser ou louer de l’énergie réduit le coût des transferts TRC-20. Notre documentation sur TronFuel et le Paymaster déprécié explique l’option actuelle. TronFuel est un service distinct, qui dispose de sa propre documentation.
Comment tester l’intégration avant le lancement ?
Utilisez les testnets. Ajoutez l’en-tête X-Network: testnet à n’importe quelle requête et le même appel s’exécute sur un réseau de test, sans fonds réels. Testez une commande complète, un paiement insuffisant, un paiement excédentaire, un paiement tardif et un webhook qui n’atteint pas votre serveur. Les webhooks en échec ne sont pas relancés automatiquement. Ils apparaissent dans GET /webhooks/notifications/failed et peuvent être renvoyés, donc votre boutique doit vérifier cette liste.
Faut-il vérifier l’identité de vos clients ?
Cela dépend de votre juridiction et de votre modèle commercial, et l’API ne tranche pas à votre place. Chaingateway est non-dépositaire. Lisez notre article sur le KYC pour les paiements crypto avant de décider quels contrôles s’appliquent à votre boutique.
Comment nous rédigeons ces articles
Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.