Paiements crypto dans un bot Telegram : factures, webhooks et versements
L’API marchand est l’API de paiement de TgPay Crypto pour les bots et services. Créez une application, obtenez un token, émettez des factures depuis votre code et recevez des webhooks de paiement signés. Un agent MCP compatible peut vous aider à réaliser l’intégration. Les paiements depuis le solde du portefeuille sont réglés dans le service ; les paiements sur la blockchain suivent les règles de confirmation du réseau choisi.
Base API : app.tgpaycrypto.com/pay/api · Réseau de test : testnet.tgpaycrypto.com
Du token au premier paiement en quatre étapes
Créez une facture, présentez le lien et attendez l’événement de paiement.
Créez une application
Dans le bot, ouvrez Plus → API marchand et renseignez un nom et une URL de webhook. Le token n’est affiché qu’une fois : conservez-le sur votre serveur.
Créez une facture
Un appel POST à createInvoice suffit : montant en crypto ou en devise, description et échéance. La réponse contient le lien de paiement.
Présentez le lien à l’utilisateur
Avec un bouton ou un lien dans votre bot, l’utilisateur paie depuis le solde de son portefeuille. Les montants élevés sont confirmés par PIN ou Face ID.
Traitez le webhook
Votre serveur reçoit invoice_paid signé avec HMAC-SHA256. Vérifiez la signature, éliminez les doublons par update_id, puis livrez le produit.
Votre agent IA peut préparer l’intégration
L’API marchand dispose d’un serveur MCP. Connectez-le dans un client d’agent compatible : l’agent peut lire la documentation, demander la création d’une application, configurer les webhooks et vous aider à écrire l’intégration. Vous approuvez l’application dans Telegram, puis vérifiez et testez le résultat.
- Étape 1
Envoyez la demande à votre agent
Utilisez un client d’agent qui prend en charge les serveurs MCP distants pour votre compte ou espace de travail. La demande est aussi disponible sous Plus → API marchand → Connecter un agent IA.
- Étape 2
Approuvez l’application dans Telegram
L’agent fournit un lien t.me. Le bot présente la demande et vous l’approuvez. Le lien est à usage unique ; rien n’est créé avant votre accord.
- Étape 3
Terminez et testez l’intégration
L’agent reçoit un token limité et vous aide à configurer les factures, les formules d’abonnement et les webhooks. Pour obtenir la clé de signature des webhooks, renouvelez le token principal dans l’application et conservez-le en lieu sûr sur votre serveur.
Le token remis par ce parcours permet de recevoir des paiements et de configurer le webhook, mais pas d’effectuer des transferts, de créer des chèques ou de rembourser. Les opérations sortantes nécessitent des permissions distinctes que vous contrôlez.
Le parcours avec un agent dans la documentationConnect the MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Ajoutez app.tgpaycrypto.com/mcp comme serveur MCP dans les paramètres de votre client
https://testnet.tgpaycrypto.com/mcp
Frais et limites
Ces valeurs proviennent du catalogue public des limites au moment de la génération de cette page. Consultez l’application pour les valeurs en vigueur.
Les possibilités de l’API marchand
Chaque application dispose d’un solde distinct de votre portefeuille. Les factures le créditent ; les versements et les chèques le débitent.
Factures et remboursements
Montant fixe en crypto, prix en devise ou montant libre choisi par le payeur. Remboursement total ou partiel, y compris pour les payeurs anonymes.
Abonnements
L’utilisateur accepte une formule une fois. Les prélèvements suivants sont automatiques, avec un événement pour chacun.
Transferts et chèques
Versements aux utilisateurs Telegram depuis le solde de l’application et chèques à partager par lien, récupérables sous réserve des conditions définies.
Webhooks
invoice_paid est toujours envoyé. Vous pouvez activer, pour chaque application, les événements d’expiration des factures et des chèques, de récupération des chèques, de remboursement, de paiement sortant et d’abonnement.
Réseau de test
La même API et la même mini-application dans @tgpaycrypto_testnet_bot. Un bouton sur l’accueil fournit des cryptos de test une fois par heure.
Agent IA et MCP
Connectez app.tgpaycrypto.com/mcp dans un client d’agent compatible avec les serveurs MCP distants. Après votre accord dans Telegram, l’agent peut créer une application et vous aider à réaliser l’intégration. Vérifiez et testez le résultat avant de l’utiliser.
Compatibilité avec l’API Crypto Bot
Les noms de méthodes, l’enveloppe {ok, result} et le mécanisme de signature des webhooks sont compatibles. Modifiez l’URL de base et le token, puis vérifiez les méthodes utilisées par votre intégration.
Gardez le contrôle des tokens
Tokens à permissions limitées, rotation immédiate, paiements sortants réservés aux utilisateurs autorisés ou désactivés, et plafond quotidien en cas de fuite d’un token.
Questions sur l’API
Tokens, signatures des webhooks, tests et migration depuis une autre API.
La création peut nécessiter une vérification d’identité complète selon les règles en vigueur. En cas d’erreur de vérification, terminez les étapes dans l’application puis réessayez.
L’en-tête TgPayCrypto-API-Signature contient le HMAC-SHA256 du corps de la requête, avec le SHA-256 de votre token principal comme clé. Comparez la signature sur les octets bruts du corps. Ne livrez rien et ne marquez pas la facture comme payée avant validation.
L’API marchand reprend les méthodes, l’enveloppe {ok, result}, les montants en chaînes décimales et le mécanisme de signature de l’API Crypto Bot. Modifiez l’URL de base et le token, puis testez votre intégration. L’en-tête Crypto-Pay-API-Token reste accepté comme alias.
Le réseau de test utilise la même API et la même mini-application : bot @tgpaycrypto_testnet_bot, base testnet.tgpaycrypto.com/pay/api. Le bouton de l’accueil fournit 1 000 USDT, 1 000 GRAM et 0,01 BTC de test une fois par heure. Les tokens des réseaux principal et de test ne sont pas interchangeables.
L’agent reçoit un token limité pour créer des factures et des formules d’abonnement, consulter le solde et les statistiques et configurer le webhook. Les transferts, chèques et remboursements nécessitent des permissions supplémentaires et l’activation des fonctionnalités concernées.
Documentation publique de l’API marchand
Référence des méthodes, spécification OpenAPI et guides détaillés sur docs.tgpaycrypto.com.
Intégrez les paiements à votre produit
Créez une application dans @tgpaycryptobot ou transmettez le lien du serveur MCP à votre agent IA, puis approuvez la création dans le bot.
Ouvrir le bot