La signature ne se vérifie jamais
Collez le corps brut du webhook dans le vérificateur de signature. Il montre chaque étape intermédiaire et marque la première différence ; dites à votre IA exactement ce qui diffère.
Aucun code à écrire. Choisissez votre site et votre outil d’IA, donnez-lui le prompt que nous générons, et il s’intègre à partir de notre documentation puis vérifie son propre travail point par point.
Prompt universel · aucun choix à faire
Aide-moi à accepter des paiements en crypto sur mon site web avec blockwallets (les clients paient en USDT, USDC, BTC et plus ; je suis crédité en dollars américains). 1. Lis d’abord la documentation au lieu de deviner l’API : https://blockwallets.io/llms-full.txt (documentation complète) et https://blockwallets.io/agents.md (règles d’intégration, erreurs courantes, liste de vérification de recette). Dis-moi si tu ne peux pas les ouvrir. 2. Regarde mon projet, dis-moi avec quoi il est construit et comment tu comptes l’intégrer, puis attends mon accord. 3. Par défaut : « créer une facture et rediriger vers la page de paiement + webhook ». Vérifie toujours les signatures des webhooks et dédoublonne-les, car le même peut arriver deux fois. 4. Conserve l’ID du merchant et l’API key dans des variables d’environnement, et fais d’abord fonctionner le tout avec les identifiants Test sur les testnets. 5. À la fin, passe en revue la liste de vérification de recette d’agents.md point par point et donne-moi chaque résultat. Je ne suis pas programmeur : à chaque étape, dis-moi ce que tu as modifié et ce que je dois faire.
L’ouverture copie le prompt complet dans votre presse-papiers ; le lien ne contient qu’une courte amorce. Collez-le une fois la page ouverte.
Vous voulez un prompt adapté à votre site ? Trois étapes ci-dessous. ↓
Étape 1
Pas sûr ? Choisissez « Autre / je ne sais pas » et l’IA regardera d’abord votre projet.
Les liens de paiement ne demandent aucun code : tableau de bord → « Encaissements › Liens de paiement » → saisissez un montant → créez, puis partagez le lien. L’IA ajoute seulement un bouton sur votre site.
Ouvrir le tableau de bordÉtape 2
Chaque outil lit la documentation différemment ; suivez les étapes correspondantes.
Ouvrez un terminal dans le dossier du projet de votre site et enregistrez les règles d’intégration sous le nom AGENTS.md :
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdCodex lit AGENTS.md tout seul. Pour Claude Code, exécutez aussi :
echo '@AGENTS.md' >> CLAUDE.mdCollez ensuite le prompt de l’étape 3.
Vous pouvez aussi installer le serveur MCP de blockwallets pour que l’IA puisse chercher dans la documentation et créer directement des factures de test.Configurer MCP →
Placez aussi AGENTS.md à la racine du projet (Cursor le détecte automatiquement) :
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdPassez en mode Agent et collez le prompt.
Vous pouvez aussi installer le serveur MCP de blockwallets pour que l’IA puisse chercher dans la documentation et créer directement des factures de test.Configurer MCP →
Collez le prompt dans une nouvelle conversation, ou utilisez « Ouvrir dans ChatGPT / Claude » ci-dessous.
S’il dit ne pas pouvoir ouvrir de liens, ouvrez https://blockwallets.io/llms-full.txt, sélectionnez tout, copiez et collez-le aussi.
Il vous donnera le code complet et où le placer ; suivez-le étape par étape. Un outil qui modifie le code à votre place (Claude Code, Codex, Cursor) évite beaucoup de copier-coller.
Collez le prompt. S’il ne peut pas ouvrir de pages web, collez aussi le contenu de llms-full.txt.
Étape 3
Il se met à jour selon vos choix ci-dessus et contient les liens vers la documentation, les pièges habituels et une liste de vérification de recette.
Tu es mon développeur. Aide-moi à accepter des paiements en crypto sur mon site web avec blockwallets (les clients paient en USDT, USDC, BTC et 14 autres cryptos ; je suis crédité en dollars américains).
## À propos de moi
- Mon site est construit avec : Je ne suis pas sûr. Regarde d’abord mon projet, dis-moi avec quoi il est construit, puis commence.
- Comment je veux encaisser : Crée une facture à la commande et redirige le client vers la page de paiement de blockwallets ; quand l’argent arrive, blockwallets appelle mon serveur, je marque la commande comme payée et je l’expédie.
- Je ne suis pas programmeur. À chaque étape, dis-moi quels fichiers tu as modifiés et ce que je dois faire (par exemple où mettre les variables d’environnement). Ne change pas trop de choses à la fois.
- AGENTS.md à la racine du projet contient les règles d’intégration de blockwallets ; lis-le d’abord, et lis https://blockwallets.io/llms-full.txt pour les détails.
## Lis d’abord la documentation ; ne devine pas l’API de mémoire
- Documentation d’intégration complète (Markdown) : https://blockwallets.io/llms-full.txt
- Règles d’intégration et erreurs courantes : https://blockwallets.io/agents.md
- Si le site utilise déjà Cryptomus, NOWPayments ou Coinbase Commerce, passe-le à l’API compatible correspondante au lieu de le réécrire : https://blockwallets.io/docs/migrate.md?lang=en
- Si tu ne peux pas ouvrir un lien, dis-le-moi et je collerai le contenu.
## Points clés (là où les intégrations déraillent d’habitude)
1. Tous les endpoints sont en POST + JSON sur https://blockwallets.io. En-têtes : merchant = l’UUID du merchant, sign = md5(base64(corps de la requête) + API key). Signe exactement la chaîne JSON que tu envoies ; ne la re-sérialise pas après la signature.
2. Crée une facture avec POST /v1/payment. Obligatoires : amount (une chaîne avec au plus deux décimales, p. ex. "42.00"), currency ("USD"), order_id (mon numéro de commande : lettres, chiffres, - et _, jusqu’à 100 caractères). Passe aussi url_callback (l’URL du webhook) et url_success (où le client revient après le paiement). Redirige le client vers result.url.
3. Un nouvel appel avec le même order_id renvoie la même facture : les nouvelles tentatives sont donc sûres et ne créent jamais une seconde facture.
4. Les signatures des webhooks doivent être vérifiées : analyse le JSON du webhook, retire le champ sign, ré-encode le reste comme le fait json_encode de PHP (compact, caractères non ASCII conservés, / échappé en \/), puis md5(base64(encodé) + API key) doit être égal à sign. Oublier d’échapper / est l’erreur la plus fréquente.
5. Marque la commande comme payée uniquement quand status vaut paid ou paid_over, en utilisant payment_amount_usd. Le même webhook peut arriver plusieurs fois : dédoublonne par uuid + status. Réponds avec un statut 2xx une fois traité.
6. Conserve l’ID du merchant et l’API key dans des variables d’environnement (p. ex. BW_MERCHANT, BW_API_KEY) ; ne les écris jamais en dur dans le code et ne les commite pas. Ajoute d’abord le domaine de l’URL du webhook dans « Domaines du site web », sur la page « Développeurs › Intégration et clés » du tableau de bord.
7. Fais d’abord tout fonctionner avec les identifiants Test (testnets, pas d’argent réel) ; ne passe en Live qu’après ma confirmation.
## Quand tu as terminé, vérifie chaque point et donne-moi le résultat
- [ ] Créer une facture de test avec les identifiants Test et obtenir le lien de la page de paiement (result.url)
- [ ] Ouvrir la page de paiement et cliquer sur « Simuler un paiement » → montant complet
- [ ] Mon serveur reçoit un webhook avec status paid et la signature est vérifiée
- [ ] La commande correspondante est marquée comme payée
- [ ] Le même webhook reçu une seconde fois (renvoyez-le depuis « Développeurs › Journal des webhooks » dans le tableau de bord, ou avec POST /v1/payment/resend) n’expédie pas deux fois
Si un point échoue, dis-moi où ça bloque et le message d’erreur exact avant de changer autre chose.
Demandez à l’IA de rendre compte de chaque résultat. Ne passez en Live que si tout est validé.
Bloqué ?
La plupart des problèmes viennent des signatures. Le texte brut aide l’IA bien plus qu’une description.
Collez le corps brut du webhook dans le vérificateur de signature. Il montre chaque étape intermédiaire et marque la première différence ; dites à votre IA exactement ce qui diffère.
Collez à votre IA la requête et la réponse exactes (message compris). Quand la signature est mauvaise, debug.body_base64 dans la réponse 401 est le texte que nous avons signé ; demandez à l’IA de le comparer au sien.
Demandez à l’IA de parcourir la liste de vérification de recette depuis le premier point, un à la fois, en rendant compte de chaque résultat. La page « Développeurs › Journal des webhooks » du tableau de bord montre chaque requête de webhook et la réponse de votre serveur.
Sécurité
L’ID du merchant et l’API key de Test fonctionnent sur des testnets ; même s’ils fuitent, aucun argent ne peut bouger.
Placez vous-même l’API key Live dans les variables d’environnement de votre serveur. Ne la collez jamais dans une conversation et ne la commitez pas dans un dépôt.
Commitez (git commit) ou copiez les fichiers de votre site avant que l’IA ne commence, pour pouvoir revenir en arrière.
Après être passé en Live, payez un petit montant réel via « Tester un paiement » sur la page d’accueil du tableau de bord et vérifiez que la commande est payée et que le solde arrive.
Fichier de règles
AGENTS.md rassemble l’essentiel de l’intégration, les erreurs courantes et la liste de vérification de recette. Placez-le à la racine de votre projet : Codex et Cursor le lisent automatiquement, Claude Code l’importe avec @AGENTS.md.
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdecho '@AGENTS.md' >> CLAUDE.mdFichiers pour l’IA
FAQ
Pour la plupart des sites, oui. L’IA écrit le code de création de facture et de signature à partir de la documentation ; vous placez les identifiants dans des variables d’environnement et parcourez la liste de vérification de recette en mode test. Si vous ne voulez aucun code, utilisez les liens de paiement.
Un outil qui modifie votre projet et exécute des commandes est le plus simple : Claude Code, Codex ou Cursor. ChatGPT ou Claude sur le web conviennent aussi, mais vous collez vous-même le code dans votre site.
Seulement les identifiants Test, et dans un fichier d’environnement plutôt que dans la conversation. Placez vous-même l’API key Live sur votre serveur.
Retirez sign, ré-encodez le reste comme le fait json_encode de PHP et échappez / en \/. Collez le corps brut du webhook dans /docs/sign pour comparer chaque étape, puis dites à l’IA ce qui diffère.
Parcourez la liste de vérification de recette : créez une facture de test, simulez le paiement, constatez que le webhook est vérifié, que la commande est marquée payée, et renvoyez le même webhook pour confirmer que rien n’est expédié deux fois. Payez un petit montant en Live avant le passage en production.