Démarrer en tant que développeur

Créez une application dans la Mini App, copiez son token d’API dès qu’il s’affiche, puis commencez à appeler l’API. Toute la configuration se trouve sous Plus → API marchand.

Les étapes

1. Ouvrez Plus → API marchand et choisissez Créer l’application.
2. Saisissez un Nom de l’application (par exemple : “Ma boutique”) et, facultativement, une URL du webhook (facultatif).
3. Acceptez les conditions du formulaire et touchez Créer l’application. Confirmez avec votre PIN ou la biométrie si cela vous est demandé. Créer une application vaut acceptation des conditions d’utilisation de l’API marchand — ce pour quoi vous pouvez, ou non, utiliser l’API.
4. Copiez le token d’API immédiatement. Il n’est affiché qu’une seule fois — l’app n’en conserve qu’une empreinte.
5. Envoyez votre première requête avec le token dans l’en-tête TgPayCrypto-API-Token.

Votre premier appel

Pointez votre client vers la base d’API https://app.tgpaycrypto.com/pay/api et appelez getMe pour vérifier que le token fonctionne. getBalance renvoie les soldes de votre application, getCurrencies les actifs que vous pouvez utiliser.

Les méthodes de lecture sont en GET. Les méthodes d’écriture, comme createInvoice, transfer, createCheck, deleteInvoice et deleteCheck, sont uniquement en POST. Les paramètres peuvent être envoyés dans le corps de la requête en JSON ou en form-urlencoded, ou dans l’URL. Préférez le corps de la requête pour éviter que les montants et les clés d’idempotence ne figurent dans les journaux d’accès aux URL.

Testnet

Développez d’abord sur le réseau de test — même API, même Mini App, cryptos de test sans valeur réelle :

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
Base de l’API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
Serveur MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Les applications et les tokens sont distincts : un token du testnet ne fonctionne pas sur le mainnet, et inversement. Pour obtenir des cryptos de test, ouvrez la Mini App du testnet et touchez Obtenir des cryptos de test sur l’écran d’accueil. Le distributeur crédite un lot de cryptos de test sous forme de dépôts ordinaires ; les actifs des réseaux désactivés sont ignorés. L’app indique les montants crédités et le moment où une nouvelle demande sera possible. Vous pouvez utiliser un second compte Telegram comme client pour payer vos factures de test.

Les dépôts et les retraits sont simulés, sans transaction réelle sur la blockchain. N’envoyez jamais de fonds réels à une adresse de dépôt du testnet. Le contrat de l’API est commun, mais les fonctionnalités disponibles, les taux et les limites peuvent différer du mainnet. Quand vous avez terminé, créez une application de production dans @tgpaycryptobot et changez l’URL de base.

Gérer une application

Ouvrez une application dans API marchand pour voir son identifiant et son solde. Vous pouvez ensuite :

• Définir ou changer l’URL du webhook dans Webhook, puis l’enregistrer.
• Choisir des événements de webhook supplémentaires — les interrupteurs Événements de webhook supplémentaires de la section Webhook permettent d’activer des types d’événements au-delà d’invoice_paid (voir la référence des webhooks).
• Restreindre qui l’API peut payer — dans Paramètres des paiements, Paiements via l’API est sur Tous les utilisateurs pour une nouvelle application ; passez-le sur Utilisateurs de la liste uniquement (et listez les destinataires) ou sur Désactivés si votre intégration ne paie jamais personne — un garde-fou au cas où le token fuirait (voir le mode de paiement sortant).
• Créer des tokens restreints — ouvrez Accès et tokens pour ajouter des tokens d’API sous Tokens restreints, chacun limité aux permissions que vous choisissez (voir la référence de l’API).
• Renouveler le token — dans Accès et tokens, cette action crée un nouveau token et invalide instantanément l’ancien. Utilisez cela en cas de fuite ; le nouveau est affiché une seule fois, comme à la création.
• Supprimer — transférez d’abord le solde disponible ; sinon, la suppression est refusée avec app_has_balance. Réglez aussi les chèques en cours et les paiements sortants en attente avant de supprimer l’application. Elle disparaît de la liste et ses tokens cessent de fonctionner ; son historique de paiements est conservé.

Les webhooks

Si vous définissez une URL de webhook, l’app y envoie en POST un corps JSON signé :

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

La signature se trouve dans l’en-tête TgPayCrypto-API-Signature (avec TgCryptoPay-API-Signature et Crypto-Pay-API-Signature comme alias de compatibilité) : un HMAC-SHA256 sur le corps brut, avec pour clé le SHA-256 de votre token d’API principal. Vérifiez-la avant de faire confiance à quoi que ce soit dans la charge utile.

Les livraisons sont réessayées avec un délai exponentiel sur une longue période, et update_id reste le même d’un essai à l’autre — fondez votre déduplication dessus et rendez votre gestionnaire idempotent.

invoice_paid ne nécessite pas d’activation distincte lorsqu’une URL de webhook est configurée. Les autres types d’événements — factures expirées, chèques récupérés, remboursements, événements d’abonnement — s’activent via les commutateurs Événements de webhook supplémentaires. La liste complète, la forme des charges utiles et les règles de nouvelles tentatives sont dans la référence des webhooks.

⚠️ Gardez le token comme une clé privée

Il autorise des paiements depuis le solde de votre application. Gardez-le sur votre serveur, jamais dans une application mobile, un bundle front-end ou une configuration enregistrée dans votre dépôt de code. Si vous soupçonnez une fuite, renouvelez-le — le renouvellement est instantané et ne coûte rien. Et ne donnez à chaque serveur que ce dont il a besoin : un token limité à la permission invoices peut créer et supprimer des factures, mais ne peut ni transférer des fonds, ni créer des chèques, ni effectuer des remboursements.