Bac à sable API crypto : tester les paiements en sécurité

Un bac à sable d’API crypto est une copie isolée d’une API de paiement ou de portefeuille. Vous y créez des portefeuilles, envoyez des transactions et recevez des notifications sans déplacer d’argent réel. Le passage en production se fait en changeant les identifiants et les paramètres réseau. Selon le fournisseur, le terme désigne des soldes simulés ou un testnet public.

Ce guide explique la différence, détaille un plan de test de la première clé au premier webhook, et liste ce qu’il faut vérifier avant le lancement.

TL;DR

• Un bac à sable est une copie isolée d’une API, gérée par le fournisseur. Un testnet est une blockchain publique distincte dont les jetons n’ont aucune valeur. De nombreuses équipes utilisent les deux.
• Testez la boucle complète : créez un portefeuille, alimentez-le, envoyez une transaction, confirmez-la, recevez le webhook, gérez un échec.
• Les webhooks sont l’endroit où se cachent la plupart des bugs de paiement. Testez la vérification des signatures, les nouvelles tentatives, les doublons et les événements hors ordre.
• Ne réutilisez jamais des clés de production ou des secrets de portefeuille dans du code de test, et ne laissez jamais des adresses de test passer dans la configuration de production.
• Avant le lancement, comparez entre le test et la production les réseaux et actifs pris en charge, le comportement des frais et les délais de confirmation.

Qu’est-ce qu’un bac à sable d’API crypto ?

Le terme est employé de façon approximative, alors partons d’une définition de travail. En conception d’API, un mock renvoie des réponses prédéfinies. Un bac à sable complet est différent : Redocly le décrit comme un environnement isolé, avec état, qui conserve les enregistrements, exécute la logique métier et permet de tester des actions destructrices sans risquer les données de production. Cette distinction compte pour la crypto. Si vous créez un portefeuille puis demandez son solde, un mock répond ce qu’on lui a dit de répondre. Un bac à sable se souvient du portefeuille que vous avez créé.

Un bac à sable crypto fait généralement trois choses :

1. Il délivre des clés API de test distinctes, qui ne peuvent pas toucher aux fonds réels.
2. Il vous permet de créer des comptes ou des portefeuilles et de leur attribuer des soldes de test.
3. Il simule les transactions et les notifications que vous verriez en production, ou les relaie vers un testnet.

Bac à sable, testnet ou devnet : quelle différence ?

Un testnet de blockchain n’est pas la même chose qu’un bac à sable d’API. Un testnet est un réseau public distinct qui imite le mainnet, afin que les développeurs puissent expérimenter sans les enjeux de la cryptomonnaie réelle. La documentation d’Ethereum décrit les testnets comme l’équivalent d’un serveur de préproduction. Elle cite Sepolia comme testnet par défaut recommandé pour le développement d’applications, et indique que la plupart des gens obtiennent des ETH de testnet gratuitement auprès de faucets.

Les pièces de testnet sont censées n’avoir aucune valeur réelle. Si quelqu’un vous demande de les payer, considérez-le comme un signal d’alerte.

L’essentiel à retenir : un bac à sable teste votre intégration avec l’API, tandis qu’un testnet teste le comportement de votre code sur une vraie chaîne, même si elle ne vaut rien. Chaque chaîne documente ses propres réseaux de test : Tron propose Shasta et Nile, et le guide du développeur Bitcoin explique les modes testnet et regtest.

Comment tester un paiement crypto, étape par étape ?

Les fournisseurs diffèrent dans les détails, mais la séquence ci-dessous tient presque partout.

1. Obtenir des identifiants de test

Créez un compte et cherchez un mode test ou bac à sable distinct, ou une URL de base distincte. Les bons fournisseurs délivrent des clés différentes pour chaque environnement : une clé de test échoue alors simplement contre la production. Stockez la clé dans une variable d’environnement ou un gestionnaire de secrets dès la première ligne de code, pas dans le dépôt.

Si le fournisseur utilise des requêtes signées, comme le font les API fondées sur HMAC, implémentez la fonction de signature une seule fois. Écrivez-en un test unitaire avec une entrée et une sortie connues. Un saut de ligne mal placé dans la chaîne que vous signez produit pendant des heures des erreurs qui ressemblent à des échecs d’authentification.

2. Créer un portefeuille

Appelez l’endpoint de création de portefeuille et notez ce qui revient : l’adresse, un identifiant, et si le fournisseur conserve la clé privée ou vous la remet. Ce dernier point détermine votre modèle de sécurité, alors consignez-le. Créez plusieurs portefeuilles sur chaque réseau que vous prévoyez de prendre en charge, car les formats d’adresse diffèrent d’une chaîne à l’autre et sont une source fréquente de bugs de validation.

3. L’alimenter avec des actifs de test

C’est là que les bacs à sable divergent le plus. Certains permettent de créditer un solde par un appel d’API ou un bouton du tableau de bord. D’autres attendent que vous demandiez des pièces à un faucet public du testnet concerné, puis que vous les envoyiez à votre nouvelle adresse. Les faucets peuvent être limités en débit ou vides : demandez les fonds tôt dans la journée, pas dix minutes avant une démo. Gardez un portefeuille de test bien approvisionné comme « banque » et rechargez les plus petits à partir de lui.

4. Envoyer une transaction

Commencez par le cas le plus simple : un transfert de pièce native entre deux de vos portefeuilles. Passez ensuite aux transferts de jetons (jetons de type ERC-20, BEP-20 ou TRC-20), car les jetons ajoutent des appels de contrat, des mécanismes de frais différents et, sur certaines chaînes, une devise de frais distincte. Notez l’ID de transaction renvoyé par l’API et comparez-le avec ce qu’affiche l’explorateur de blocs de ce réseau de test.

5. Vérifier le résultat

Une transaction passe par plusieurs états, et votre application doit les modéliser plutôt que de se contenter d’un seul indicateur « payé » :

• Soumise : acceptée par l’API, pas encore sur la chaîne.
• En attente : vue dans le mempool ou dans un bloc, avec trop peu de confirmations.
• Confirmée : assez de confirmations pour votre tolérance au risque.
• Échouée ou abandonnée : rejetée, à court de gas, remplacée ou jamais minée.

Pour le suivi du chiffre d’affaires, comptez les paiements réglés, pas les tentatives. Il en va de même pour les confirmations sur une chaîne : une transaction en attente n’est pas encore du chiffre d’affaires.

Comment tester les webhooks et les cas d’échec ?

Les webhooks transforment une API de paiement : au lieu de l’interroger, vous êtes prévenu quand l’argent arrive. C’est aussi là que les intégrations cassent le plus souvent, car c’est l’expéditeur qui contrôle le moment de l’envoi.

Recevoir une notification de bout en bout

Il vous faut une URL HTTPS publique qui atteigne votre machine de développement. Un outil de tunnel ou un serveur de préproduction convient. Enregistrez l’URL, envoyez une transaction de test vers une adresse surveillée et vérifiez que votre gestionnaire reçoit l’événement avec les champs attendus. Notre article sur l’utilisation des webhooks pour traiter automatiquement les dépôts décrit la structure habituelle.

Une liste de contrôle pour tester les webhooks

• Vérifiez la signature. Rejetez toute requête dont la signature ne correspond pas, et testez-le en modifiant la valeur signée. Avec Chaingateway, la valeur signée est le txid : contrôlez donc aussi le montant et le destinataire par rapport à vos attentes. L’article sur les secrets personnels l’explique.
• Testez l’idempotence. Livrez deux fois le même événement. Votre système doit créditer l’utilisateur une seule fois, donc stockez un ID d’événement ou de transaction et vérifiez-le avant d’agir.
• Testez la livraison hors ordre. Un événement « confirmé » peut arriver avant « en attente ». Ne laissez pas un état plus ancien écraser un état plus récent.
• Testez un récepteur lent ou défaillant. Renvoyez une erreur ou bloquez pendant 30 secondes, et observez ce que fait le fournisseur. Chaingateway ne réessaie pas automatiquement : les notifications échouées sont listées, et vous demandez le renvoi de chacune.
• Accusez réception rapidement. Répondez vite avec un code de succès et faites le gros du travail dans une file d’attente. Les gestionnaires longs provoquent des timeouts et des livraisons en double.
• Rejouez après une interruption. Éteignez votre récepteur, envoyez des transactions, rallumez-le. Sachez comment vous récupérerez les événements manqués, par exemple à partir de la liste des notifications échouées ou de l’historique des transactions.

Cas d’échec à provoquer

Cassez volontairement des choses dans le bac à sable : c’est à cela qu’il sert.

• Envoyez plus que le solde du portefeuille.
• Envoyez vers une adresse mal formée ou une adresse d’un autre réseau.
• Envoyez un jeton vers un portefeuille qui n’a pas de pièce native pour payer les frais.
• Fixez des frais trop bas et regardez la transaction rester bloquée.
• Envoyez un montant minime, sous votre seuil de paiement minimal.
• Payez un peu moins ou un peu plus que ce qu’attend une facture. Les paiements insuffisants et excédentaires sont courants dans le paiement crypto : définissez votre règle et testez-la.

Quelles différences entre le bac à sable et la production ?

Un bac à sable est un modèle, et un modèle laisse des choses de côté. Avant de passer aux clés de production, vérifiez explicitement ces points.

Effectuez ensuite un paiement canari en production : un petit transfert réel sur tout le parcours, de la création du portefeuille au webhook, puis à l’écriture dans le registre. Il coûte quelques centimes ou quelques dollars et détecte des erreurs de configuration qu’aucun bac à sable ne révèle.

Comment protéger les clés pendant les tests ?

Les environnements de test sont le lieu où naissent les mauvaises habitudes, et les habitudes se retrouvent ensuite en production.

• Utilisez des clés distinctes par environnement. Nommez-les clairement et donnez-leur des préfixes différents dans votre gestionnaire de secrets, pour qu’une confusion se voie.
• Gardez les secrets hors du dépôt. Utilisez des variables d’environnement, un coffre-fort ou le stockage de secrets de votre CI. Si une clé s’est glissée dans l’historique, analysez-le et renouvelez la clé.
• N’importez jamais un vrai portefeuille dans une configuration de test. Si une phrase de récupération ou une clé privée contrôle de vrais fonds, elle n’a sa place ni dans un script de test, ni dans une capture d’écran, ni dans un message de messagerie.
• Limitez le nombre de personnes qui voient les clés. Les prestataires et agences qui travaillent sur votre intégration ne doivent recevoir que des clés de test.
• Fixez les URL de base dans la configuration, pas dans le code. Ajoutez un contrôle au démarrage qui refuse de s’exécuter si une clé de test est associée à l’URL de production, ou l’inverse.
• Renouvelez les clés après les démos. Des clés montrées à l’écran ou dans un enregistrement doivent être considérées comme exposées.

Quelles limites vérifier avant de s’engager ?

Avant de vous engager sur le bac à sable d’un fournisseur, posez quelques questions directes :

1. Quels réseaux couvre-t-il en mode test ? Si votre produit a besoin d’Ethereum, de Tron et de Bitcoin, vérifiez les trois, pas un seul.
2. Quels standards de jetons et quels actifs ? Les pièces natives sont faciles. Les lacunes apparaissent avec les stablecoins et les NFT.
3. Comment obtient-on des fonds de test, et y a-t-il des plafonds ? Les limites des faucets et les maximums quotidiens déterminent la vitesse d’itération de votre équipe.
4. Conserve-t-il l’état ? Un bac à sable avec état permet de construire des scénarios en plusieurs étapes. Un mock sans état, non.
5. Les webhooks sont-ils disponibles en mode test, et peut-on les déclencher à la demande ?
6. Quelle est sa stabilité ? Les testnets sont réinitialisés ou abandonnés, ce qui peut effacer vos portefeuilles de test. Gardez la configuration scriptée pour pouvoir tout reconstruire en quelques minutes.

Si vous devez aussi comprendre quel type de fournisseur convient à quel usage, notre comparaison des API blockchain et du moment où utiliser chaque type est un bon complément.

Comment tester avec Chaingateway ?

Chaingateway ne propose pas de bac à sable simulé séparé avec de faux soldes. Sa documentation d’API décrit des tests sur des testnets publics : ajoutez l’en-tête X-Network: testnet à une requête, ou omettez-le pour le mainnet. Les mêmes endpoints, les mêmes clés et les mêmes formats de réponse valent pour les deux. Chaque chaîne a son propre testnet, listé sur la page des réseaux pris en charge :

Un premier test demande quatre requêtes. Créez une adresse, alimentez-la depuis le faucet de la chaîne, enregistrez un webhook et envoyez un transfert :

# 1. Create an address on Sepolia
curl -X POST https://app.chaingateway.io/api/v2/ethereum/addresses \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"password": "use-a-strong-test-password"}'

# 2. Fund the address from a Sepolia faucet, then register a webhook for it
curl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"to": "0xYourNewAddress", "url": "https://your-tunnel.example/hooks", "type": "ETH", "reference": "test-1"}'

La réponse du premier appel contient la nouvelle adresse. Pour le webhook, type désigne le genre d’actif. Sur Ethereum, les valeurs sont ETH, ERC20 et ERC721 ; les autres chaînes utilisent leurs propres noms, comme TRC20 sur Tron. La référence de l’API les liste. Les webhooks existent sur toutes les chaînes prises en charge sauf Solana : testez donc Solana en interrogeant les transactions.

Chaingateway signe les webhooks avec un en-tête X-Signature dès que vous définissez un secret personnel, et il ne réessaie pas lui-même les notifications échouées. Les deux méritent d’être testés sur testnet. Les forfaits commencent à 49 € par mois pour Plus, avec Pro à 99 €, Premium à 249 € et Enterprise à 499 € par mois. La facturation annuelle est de 490 €, 990 €, 2 490 € et 4 990 € respectivement. Chaque forfait débute par un essai gratuit de 7 jours, sans carte bancaire ni KYC. Consultez la page des tarifs, la page API Blockchain et la page Webhooks Chaingateway pour les détails.

Pour des idées de ce que vous pouvez construire une fois vos tests réussis, notre aperçu des cas d’usage d’une API blockchain est une bonne lecture suivante.

À quoi ressemble un plan de test pratique ?

Utilisez-le comme liste de contrôle d’une page pour une version.

1. Configuration : clés de test stockées dans un gestionnaire de secrets, URL de base dans la configuration, fonction de signature testée unitairement.
2. Portefeuilles : en créer au moins deux par réseau pris en charge, noter les formats d’adresse.
3. Financement : alimenter un portefeuille de test principal, scripter la recharge des autres.
4. Cas nominal : transfert natif, puis transfert de jeton, chacun vérifié avec un explorateur de blocs.
5. Webhooks : contrôle de la signature, livraison en double, événements hors ordre, indisponibilité du récepteur.
6. Échecs : solde insuffisant, adresse d’un autre réseau, devise de frais manquante, frais trop bas, paiement insuffisant, paiement excédentaire.
7. Modèle d’état : votre base de données gère sans ambiguïté les états soumis, en attente, confirmé et échoué.
8. Charge : rafale de transactions dans les limites de débit de votre forfait.
9. Revue de sécurité : aucun secret de production dans le code de test, journaux nettoyés des clés et des phrases de récupération.
10. Canari : un petit paiement réel sur tout le parcours avant d’annoncer le lancement.

Sources

• Networks, Ethereum developer documentation (testnets and faucets)
• Networks, Tron developer documentation (Shasta and Nile)
• Testing applications, Bitcoin developer guide
• What you really need to build an API sandbox, Redocly

Recommandé

• Blockchain API – One REST API for Bitcoin, Ethereum & 5 More
• How to Create a Crypto Wallet with an API: 2026 Guide
• Developer: Ship Recurring Crypto Payments in 90 Days, EIP & 2026
• Receive Crypto Payments in Laravel — How-To