API marchand

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 dans le bot, obtenez un token, émettez des factures depuis votre code et recevez un webhook signé à chaque paiement. Vous pouvez aussi confier l’intégration à votre agent IA via le serveur MCP. Les paiements sont réglés dans le service, sans frais de réseau ni attente de confirmations.

Obtenir un token Documentation API Avec un agent IA
Base API : app.tgpaycrypto.com/pay/api · Réseau de test : testnet.tgpaycrypto.com
L’écran de l’API marchand : application, token et événements webhook
Webhook reçu
Réseau de test
Fonctionnement

Du token au premier paiement en quatre étapes

Créez une facture, présentez le lien et attendez l’événement de paiement.

Étape 1

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.

Étape 2

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.

Étape 3

Présentez le lien à l’utilisateur

Ajoutez un bouton ou un lien dans votre bot. L’utilisateur paie depuis le solde de son portefeuille.

Étape 4

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.

Agent IA

Votre agent IA peut préparer l’intégration

L’API marchand dispose d’un serveur MCP. Donnez son URL à votre agent : il consulte la documentation, crée l’application avec votre accord, configure le webhook et écrit le code. Aucun token à recopier manuellement.

  1. Étape 1

    Envoyez la demande à votre agent

    Utilisez Claude Code, claude.ai, Claude Desktop, ChatGPT ou un autre client MCP. La même demande est disponible dans l’application, sous Plus → API marchand → Connecter un agent IA.

  2. É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.

  3. Étape 3

    L’agent termine la configuration

    Il reçoit un token limité et configure les factures, les formules d’abonnement et le webhook. La clé de signature du webhook reste à votre disposition dans l’application.

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 documentation
Demande à transmettre à votre agent
Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
Claude Code
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
claude.ai, Claude Desktop, ChatGPT

Ajoutez app.tgpaycrypto.com/mcp comme serveur MCP dans les paramètres de votre client

Réseau de test
https://testnet.tgpaycrypto.com/mcp
Conditions

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.

Frais par factureÀ la charge du commerçant : le solde de l’application est crédité après déduction des frais. Le taux est fixé au paiement et ne change pas pour les factures déjà payées.
3 %
Réduction selon le volumeLe taux baisse automatiquement selon le volume des 30 derniers jours : dès 10 000 $ — 2,9 %, 25 000 $ — 2,8 %, 50 000 $ — 2,7 %, 75 000 $ — 2,6 %, 100 000 $ — 2,5 %.
jusqu’à 2,5 %
Frais de réseauFactures, transferts et chèques sont réglés dans le service. Aucune confirmation de blockchain à attendre : les fonds sont immédiatement utilisables.
0
Versements aux utilisateursLa méthode transfer envoie des cryptos depuis le solde de l’application à un utilisateur Telegram par son ID. transferBatch permet jusqu’à 100 destinataires par appel. Une nouvelle tentative avec le même spend_id ne débite pas une seconde fois.
jusqu’à 25 000 $
Limites de requêtescreateInvoice et createCheck : 60 par minute ; transfer et refundInvoice : 30 ; transferBatch : 10. Les méthodes de lecture ne sont pas limitées.
60 par minute
Livraison des webhooksUne réponse 2xx en moins de 10 secondes confirme la réception. Sinon, les tentatives sont espacées progressivement sur environ trois jours. Le même update_id est conservé.
jusqu’à 17 tentatives
Fonctionnalités

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é. Les événements d’expiration des factures, de récupération des chèques, de remboursement et d’abonnement s’activent pour chaque application.

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

Transmettez app.tgpaycrypto.com/mcp à votre agent. Il crée l’application, configure le webhook et prépare l’intégration. Vous approuvez la création dans le bot.

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 fréquentes

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.

Toutes les méthodes dans la documentationQuestions : @tgpayhelpbot
Documentation

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