Démarrer en tant que développeur

Créez une application dans la Mini App, copiez son token d’API une bonne fois, et commencez à appeler l’API. Toute la configuration se trouve sous Plus → API marchand.

Les étapes

1. Ouvrez Plus → API marchand.
2. Saisissez un Nom de l’application (par exemple : “Ma boutique”) et, facultativement, une URL du webhook.
3. Touchez Créer l’application.
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 TgCryptoPay-API-Token.

Votre premier appel

Pointez votre client vers la base d’API https://crypto.tgpaybot.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. Celles qui déplacent de l’argent — createInvoice, transfer, createCheck et leurs pendants de suppression — sont uniquement en POST, exprès : les montants et les clés d’idempotence n’ont pas leur place dans les journaux d’accès. Les paramètres peuvent être envoyés en corps JSON, en form-urlencoded ou en paramètres d’URL.

Gérer une application

Chaque carte d’application dans API marchand affiche son identifiant d’application et son solde, et vous permet de :

• Définir ou changer l’URL du webhook et l’enregistrer.
• Choisir des événements de webhook supplémentaires — une fois une URL de webhook définie, les commutateurs Événements de webhook supplémentaires vous laissent activer des types d’événements au-delà d’invoice_paid (voir la référence des webhooks).
• Créer des tokens restreints — des tokens d’API supplémentaires sous Tokens restreints, chacun limité aux permissions que vous choisissez (voir la référence de l’API).
• Renouveler le token — émet 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 — l’application cesse de s’authentifier, mais son solde et son historique de paiements sont conservés. Supprimer une application ne fait jamais disparaître son argent.

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 TgCryptoPay-API-Signature (avec 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. 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 est toujours livré. 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 le calendrier des réessais 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 commitée. Si vous doutez d’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 restreint sans la permission payouts peut créer des factures mais ne pourra jamais sortir votre solde.