Une clé API de paiement fonctionne comme une carte de retrait sans code PIN. Quiconque la présente peut créer des factures, lire vos données de paiement et, si vous utilisez les versements, faire sortir des fonds de votre solde. La sécurité des API de paiement repose donc sur trois réflexes : conserver la clé sur vos propres serveurs, n'accepter la clé que depuis les adresses de ces serveurs, et confirmer chaque webhook en relisant le paiement avant d'agir.
Ce guide s'adresse aux responsables techniques et aux directeurs des paiements des PSP, des établissements de monnaie électronique (EME), des banques et des marchands qui connectent une API de paiement crypto réglée en euros. Il montre comment restreindre une clé par adresse IP et plage CIDR, où la clé doit être conservée, comment vérifier les webhooks et quels contrôles encadrer autour des versements. Les exemples utilisent l'API et le tableau de bord ItisPay (données de démonstration).
Moments clés
En bref
- Une clé API est un identifiant au porteur. GitGuardian a recensé 28,65 millions de nouveaux secrets codés en dur dans les commits publics de GitHub en 2025 ; partez donc du principe qu'une clé peut fuir, et pas seulement qu'il faut la protéger.
- Une liste d'autorisation IP rend une clé divulguée inutilisable en dehors de votre réseau. Listez les plus petites plages IPv4 ou IPv6 qui couvrent vos adresses sortantes réelles ; une liste vide autorise toutes les adresses.
- Un webhook est une notification, pas une preuve. Relisez la facture par son identifiant, avec votre clé, avant d'expédier des marchandises ou de créditer un compte.
- Les versements exigent des contrôles humains de votre côté : connexion en deux étapes, IBAN et portefeuilles des bénéficiaires enregistrés, et un second approbateur au-delà d'un montant défini.
Pourquoi une clé API de paiement divulguée est-elle si dangereuse ?#
Une clé API de paiement divulguée est dangereuse, car elle représente à elle seule l'identité de votre intégration. L'API ItisPay, comme la plupart des API de paiement, authentifie chaque requête au moyen d'un seul en-tête, Api-key, et la même authentification couvre les factures, les versements vers un IBAN ou un portefeuille, ainsi que les retraits crypto vers une adresse externe. C'est pourquoi la documentation demande que la clé « ne soit pas exposée dans le code côté client ni dans les dépôts publics ».
En pratique, les clés fuient par des voies ordinaires : le code, les journaux et les messageries. Selon le rapport GitGuardian's State of Secrets Sprawl 2026 (mars 2026), 28,65 millions de nouveaux secrets codés en dur ont été ajoutés aux commits publics de GitHub en 2025, soit 34 % de plus qu'un an auparavant. Lorsque GitGuardian a retesté des secrets divulgués en 2022, plus de 64 % étaient encore valides en janvier 2026. Les équipes publient des clés, puis oublient de les remplacer.
Le classement OWASP API Security Top 10 (2023) place « Broken Authentication » au deuxième rang et avertit que « le mécanisme d'authentification est une cible facile pour les attaquants, puisqu'il est exposé à tout le monde ». Le rapport Data Breach Investigations Report 2025 de Verizon désigne l'utilisation abusive d'identifiants comme le vecteur d'attaque initial le plus fréquent, à 22 %. Une chaîne secrète seule offre une défense mince ; le reste de ce guide ajoute donc des couches qui tiennent même une fois la chaîne sortie.
Comment une liste d'autorisation IP protège-t-elle une clé API ?#
Une liste d'autorisation IP, parfois appelée liste blanche IP, protège la clé en la liant à des lieux autant qu'à une chaîne de caractères. L'API n'accepte la clé que lorsque la requête provient d'une adresse que vous avez listée ; une copie de la clé sur l'ordinateur d'un développeur, dans un journal CI ou sur un site de partage de code ne fonctionne pas.
Dans le tableau de bord ItisPay, le paramètre se trouve sous Projects, puis Settings, puis Security, dans le champ API Allowed IPs. Ce champ accepte une liste d'adresses uniques et de blocs CIDR séparés par des virgules. Son texte d'aide indique : "Leave empty to allow all IPs. Both IPv4 and IPv6 are supported." La même liste peut être définie à la création d'un projet via l'API, dans le champ api_allowed_ips, et une entrée invalide telle que 256.256.256.256 est refusée avec une erreur de validation au lieu d'être enregistrée.
La valeur vide par défaut compte. Un nouveau projet accepte sa clé depuis n'importe où tant que personne n'a rempli le champ ; placez donc cette étape sur la liste de mise en production, et non sur la liste des choses à ranger plus tard. Les valeurs de démonstration de la capture d'écran, 203.0.113.10 et 198.51.100.0/24, proviennent de plages que la RFC 5737 réserve à la documentation ; votre liste contiendra vos propres adresses publiques. Chaque projet dispose de sa propre clé de 64 caractères et de sa propre liste, de sorte que la production peut rester limitée à deux ou trois serveurs, tandis qu'un projet de test accepte un ensemble plus large.
Comment écrire des plages CIDR pour IPv4 et IPv6 ?#
Écrivez la plus petite plage qui couvre chaque adresse que vos serveurs utilisent réellement pour atteindre l'API. La plupart des problèmes de liste d'autorisation viennent d'une plage beaucoup trop large ou d'un chemin sortant que quelqu'un a oublié.
Lire un préfixe#
Un bloc CIDR est une adresse suivie d'une barre oblique et d'une longueur de préfixe. La RFC 4632 définit la longueur de préfixe comme le nombre de bits significatifs : 192.168.99.0/24 fixe les 24 premiers bits et laisse 8 bits libres, soit 256 adresses. Chaque bit retiré au préfixe double le bloc. Un /32 correspond à une adresse IPv4, un /29 à 8 adresses, un /24 à 256 et un /16 à 65 536.
IPv6 fonctionne de la même manière avec 128 bits. Un /128 correspond à une seule adresse. La RFC 4291 fixe la partie interface de la plupart des adresses IPv6 à 64 bits ; le réseau d'un serveur est donc normalement un /64, et l'hôte peut changer d'adresse à l'intérieur de celui-ci, par exemple lorsque le système d'exploitation génère des adresses temporaires. Si l'adresse IPv6 de votre hôte change et que ce /64 vous appartient exclusivement, listez le /64 plutôt qu'un seul /128. La plage de documentation pour les exemples IPv6 est 2001:db8::/32 (RFC 3849) ; ne la recopiez donc jamais dans une liste d'autorisation réelle.
Trouver votre adresse sortante réelle#
L'adresse qui compte est celle que voit l'API, et non celle que votre serveur annonce à propos de lui-même. Derrière une passerelle NAT cloud ou un pare-feu d'entreprise, de nombreuses machines partagent une ou deux adresses publiques. Les fonctions serverless sortent souvent depuis un pool partagé, sauf si vous les faites passer par une sortie fixe. Vérifiez depuis chaque environnement en appelant un service « quelle est mon IP », ou lisez l'adresse source dans les journaux de votre pare-feu, puis listez exactement cette adresse.
| Configuration | Quoi déclarer | Verdict |
|---|---|---|
| Un serveur avec une adresse IPv4 publique statique | Cette adresse au format /32 ou sans suffixe | Fonctionne |
| Plusieurs serveurs derrière une passerelle NAT cloud | Les adresses publiques de la passerelle NAT | Fonctionne |
| Hôte IPv6 aux adresses changeantes | Le /64 de l'hôte, si personne d'autre ne l'utilise | Selon le cas |
| Réseau de bureau pour les tests manuels | L'adresse fixe du bureau, si le fournisseur la garantit | Selon le cas |
| Fonctions serverless sans sortie fixe | Les faire passer d'abord par une NAT dotée d'une adresse statique | Non |
| Toute la plage régionale d'un fournisseur cloud | Rien ; elle couvre aussi d'autres clients | Non |
Avant d'enregistrer une modification, ajoutez d'abord la nouvelle adresse, déployez, vérifiez que le trafic circule, et ne supprimez l'ancienne qu'ensuite. Enregistrer une liste qui omet vos serveurs en production bloque vos propres paiements.
Où doit se trouver la clé API, et qui peut la voir ?#
La clé doit se trouver sur vos serveurs, dans un coffre-fort de secrets, et nulle part ailleurs. Ne l'intégrez jamais dans une page de navigateur ou une application mobile, car n'importe qui peut la lire à cet endroit. Ne la placez pas non plus dans les URL : le OWASP REST Security Cheat Sheet avertit qu'une clé présente dans une URL peut être capturée dans les journaux du serveur web. Votre page de paiement communique avec votre back-end ; le back-end communique avec l'API de paiement.
Chargez la clé depuis un gestionnaire de secrets ou des variables d'environnement au démarrage, et non depuis un fichier de configuration du dépôt. Si vous hébergez votre code sur GitHub, activez la protection contre les envois (push protection) : selon la documentation de GitHub, lorsqu'elle « détecte un secret potentiel lors d'une tentative d'envoi, elle bloquera l'envoi ».
Utilisez une clé par environnement. Chaque projet ItisPay possède sa propre clé et sa propre liste d'autorisation ; des projets distincts pour la production et la préproduction signifient qu'une clé de préproduction divulguée ne peut pas toucher aux paiements réels. Limitez le nombre de personnes qui peuvent voir la clé de production. Les lignes directrices de 2019 de l'ABE (Autorité bancaire européenne) sur la sécurité des TIC posent la règle du « besoin d'en connaître » avec des « droits d'accès minimaux », y compris pour les utilisateurs techniques ; depuis 2025, DORA impose cette obligation à la plupart des établissements de paiement.
Rédigez ensuite la procédure de remplacement de la clé, avant d'en avoir besoin. Le OWASP Cryptographic Storage Cheat Sheet recommande de renouveler les clés après une période déterminée et dès qu'une compromission est suspectée, et de s'assurer que « le code et les processus nécessaires à la rotation d'une clé sont en place avant qu'ils ne soient requis ».
Comment vérifier les webhooks d'une API de paiement ?#
Considérez un webhook comme une notification indiquant qu'un changement a eu lieu, jamais comme la preuve que vous avez été payé. Quiconque apprend l'URL de rappel de votre serveur peut lui envoyer un faux message « terminé ». Le schéma sûr consiste à relire la facture depuis l'API avec votre propre clé, puis à agir selon ce que l'API renvoie.
Lors de la création d'une facture ItisPay, le champ callback_url définit l'adresse des mises à jour de statut. Lorsqu'un webhook arrive, récupérez-y l'ID de la facture, appelez GET sur la facture par son ID, et ne livrez ou ne créditez que si cette réponse affiche le statut attendu et le montant que vous avez fixé. La documentation décrit ce point de terminaison comme renvoyant le statut de paiement et les détails de la blockchain « à afficher aux utilisateurs ou à des fins de vérification ».
Quelques règles gardent le gestionnaire propre :
- N'acceptez les webhooks qu'en HTTPS et rejetez le HTTP simple.
- Rendez le gestionnaire idempotent. Enregistrez l'ID et le statut de chaque facture traitée, et ignorez les répétitions, car les fournisseurs renvoient les notifications.
- Répondez rapidement et confiez le travail à une file d'attente, afin qu'une base de données lente ne déclenche pas de nouvelles tentatives.
- Si un fournisseur signe ses webhooks avec HMAC, un hachage à clé défini dans la RFC 2104, recalculez la signature et comparez-la à l'aide d'une fonction à temps constant. Le OWASP Webhook Security Cheat Sheet est catégorique : « N'utilisez jamais ==, cela divulgue des informations de temps et peut transformer le point de terminaison en oracle de signature. » Rejetez les messages dont l'horodatage signé est trop ancien.
Testez avant la mise en production. ItisPay propose un point de terminaison qui simule un changement de statut pour une vraie facture de test, et un autre qui renvoie le dernier webhook d'une facture ou d'un ID de commande, afin que vous puissiez vérifier les nouvelles tentatives et les doublons sans argent réel.
Comment verrouiller les versements et l'accès au tableau de bord ?#
Les versements sont l'endroit où une clé volée se transforme en perte d'argent ; ajoutez donc des contrôles humains autour d'eux. Via le point de terminaison des versements d'ItisPay, un versement en monnaie fiduciaire est envoyé à un IBAN bénéficiaire et un versement en cryptomonnaie à une adresse de portefeuille, tous deux depuis votre solde disponible. L'API exécute ce que la requête demande ; décider si une requête est légitime relève de votre responsabilité.
Contrôles efficaces de votre côté :
- Authentification en deux étapes pour toute personne ayant accès au tableau de bord ou aux versements. Le droit européen des paiements applique déjà cette idée aux utilisateurs de services de paiement : les règles PSD2 sur l'authentification forte du client exigent au moins deux éléments indépendants parmi la connaissance, la possession et l'inhérence. Appliquez la même norme à votre propre personnel.
- Bénéficiaires enregistrés. Tenez votre propre liste d'IBAN et d'adresses de portefeuille approuvés, et ne laissez votre service de versement envoyer des fonds qu'aux entrées de cette liste. Un nouveau bénéficiaire passe par une approbation distincte, idéalement assortie d'un délai de carence.
- Un second approbateur au-delà d'un seuil. Une personne prépare, une autre approuve. Fixez le montant en fonction de votre propre appétence au risque.
- Un service de versement distinct. Exécutez les versements depuis un service dédié, avec sa propre adresse fixe inscrite sur la liste d'autorisation, séparé des serveurs de paiement qui créent les factures.
| Contrôle | Ce qu'il empêche | Verdict |
|---|---|---|
| Liste blanche d'adresses IP sur la clé | Utilisation d'une clé divulguée depuis l'extérieur de votre réseau | Fonctionne |
| Clé uniquement sur le serveur | Vol de clé depuis les navigateurs, les applications et les dépôts | Fonctionne |
| Relecture de la facture après un webhook | Fausses notifications « payé » | Fonctionne |
| Bénéficiaires enregistrés et second approbateur | Versements vers l'IBAN ou le portefeuille de l'attaquant | Fonctionne |
| L'un de ces contrôles seul, face à un serveur piraté figurant sur la liste | Vol par une personne déjà présente à l'intérieur | Non |
Qu'attendent DORA et PCI DSS de l'accès aux API ?#
Si vous êtes un établissement financier réglementé dans l'UE, ces contrôles ne sont pas des options facultatives. Le règlement sur la résilience opérationnelle numérique (DORA, règlement (UE) 2022/2554) est applicable depuis le 17 janvier 2025, selon l'EBA. Son article 9 demande aux entreprises de « mettre en œuvre des politiques qui limitent l'accès physique ou logique » aux actifs TIC et de « mettre en œuvre des politiques et des protocoles pour les mécanismes d'authentification forte ». Une clé placée sur liste blanche, réservée au serveur et assortie d'un plan de rotation est le type de preuve qu'un auditeur demande à voir.
PCI DSS couvre les données de carte, et non les factures en crypto-actifs. Si la même équipe gère aussi les paiements par carte, l'exigence 8.4.2 impose une authentification multifacteur pour tout accès à l'environnement de données du titulaire de carte, et les exigences à effet différé de la version 4.0 sont devenues obligatoires le 31 mars 2025.
Où les contrôles de sécurité des API de paiement cessent-ils de fonctionner ?#
Ces contrôles réduisent les voies d'accès. Ils ne suffisent pas à rendre une intégration sûre à eux seuls. Même pour les émetteurs de webhooks, la fiche OWASP sur les webhooks qualifie la liste blanche d'adresses IP de « simple couche supplémentaire », car « une adresse IP de sortie partagée n'est pas une preuve d'identité ».
Dans quels cas cela n'aide pas
- Un serveur piraté figurant sur la liste. L'attaquant envoie des requêtes depuis une adresse de confiance avec la vraie clé.
- Adresses de sortie partagées. Si d'autres locataires sortent du cloud depuis la même adresse NAT, la liste ne peut pas les distinguer de vous.
- Un mot de passe de tableau de bord volé sans connexion en deux étapes. L'attaquant contourne entièrement l'API.
- Données personnelles dans les champs de facture. Le point d'accès public aux factures d'ItisPay renvoie l'ensemble des informations relatives aux factures ouvertes sans clé ; ne mettez donc pas les noms et adresses e-mail des clients dans le nom de la commande.
Comment mettre en place une intégration sécurisée en un après-midi ?#
Vous pouvez achever la partie technique d'une intégration sécurisée en un après-midi si vous suivez un ordre fixe. Les étapes ci-dessous utilisent ItisPay ; le même ordre fonctionne avec tout prestataire.
- Créez un projet de test et un projet de production distinct, chacun avec sa propre clé.
- Conservez les deux clés dans votre gestionnaire de secrets et chargez-les uniquement sur le serveur.
- Identifiez l'adresse de sortie publique de chaque environnement et saisissez-la dans le champ « API Allowed IPs ».
- Créez une facture depuis le back end : requête POST vers https://api.itispay.com/api/v1/invoices avec l'en-tête Api-key, un order_id unique, fiat_amount avec fiat_currency EUR, la crypto-monnaie dans currency et votre callback_url.
- Développez le gestionnaire de webhooks : HTTPS uniquement, idempotent, et relecture de la facture par son ID avant toute action.
- Lancez la simulation de webhook pour chaque statut que vous gérez, puis le point d'accès de renvoi pour tester les doublons.
- Activez les versements en dernier, avec des bénéficiaires enregistrés et un second approbateur.
Pour un démarrage rapide, l'assistant Ask AI du tableau de bord rédige sur demande des exemples de code, comme un appel de création de facture en Node.js avec l'en-tête Api-key déjà en place. Considérez-le comme un brouillon : vérifiez les noms de champs dans la référence de l'API avant la mise en production, car c'est la référence, et non un exemple généré, qui fait foi. ItisPay publie aussi un client TypeScript officiel sur npm, @itispay/typescript-client.
Si vous intégrez ceci à une architecture plus large d'orchestration des paiements, dotez chaque prestataire de sa propre clé, de sa propre liste blanche et de son propre gestionnaire de webhooks. Le même enregistrement relu par ID alimente aussi le rapprochement des paiements crypto pour votre équipe financière.
Si vous souhaitez accepter des paiements en stablecoins et recevoir des euros sans construire vous-même l'infrastructure, ItisPay fournit l'API, la facturation, les webhooks et le rapprochement, ainsi que la première couche de sécurité des API de paiement : des clés que vous pouvez restreindre à vos propres adresses IP. L'agrément, le KYC et le règlement vers votre IBAN passent par notre partenaire agréé dans l'UE en tant que prestataire de services sur crypto-actifs (CASP) et établissement de paiement, et la plupart des équipes passent de la KYB à la première transaction en moins d'une semaine.
Cet article est fourni à titre informatif uniquement et ne constitue pas un conseil juridique ou réglementaire.
