Factures Telegram Stars (XTR) dans les bots : le flux de paiement pour les développeurs, étape par étape
Vendre des biens numériques contre des Stars dans un bot : sendInvoice avec XTR, la réponse à pre_checkout_query en 10 secondes, successful_payment, l’enregistrement de l’identifiant de débit et une liste de contrôle avant le lancement.
Publié:

Votre bot vend-il quelque chose de numérique, comme un abonnement, du contenu, des requêtes d’IA ou des objets en jeu ? Alors le paiement se fait uniquement en Telegram Stars. Cet article décrit le flux de facture Telegram Stars (XTR) du point de vue d’un développeur, en suivant la documentation officielle de l’API Bot. Pour comprendre pourquoi il faut passer par les Stars, consultez les biens numériques dans les bots uniquement via les Stars.
Le flux en un coup d’œil
| Étape | Ce que fait le bot | Ce que Telegram envoie |
|---|---|---|
| 1 | sendInvoice avec currency = XTR | — |
| 2 | Attend | pre_checkout_query |
| 3 | answerPreCheckoutQuery (dans les 10 secondes) | — |
| 4 | Attend | successful_payment |
| 5 | Enregistre l’identifiant de débit, livre les biens | — |
Étape 1 : créer la facture
Il existe deux méthodes :
- Facture du bot : la méthode sendInvoice. Comme les biens sont numériques, provider_token est une chaîne vide et le champ currency est XTR. La facture peut être envoyée dans une discussion privée, un groupe ou un canal.
- Facture intégrée : si votre bot prend en charge le mode intégré, inputInvoiceMessageContent permet aux utilisateurs de partager la facture avec des amis, des groupes et des canaux. Son bouton Payer peut être utilisé plusieurs fois.
Étape 2 : choisir le comportement de transfert
Le paramètre start_parameter le contrôle :
- Facture multi-discussions : les copies transférées conservent un bouton Payer, afin que de nombreux utilisateurs puissent payer. Les factures intégrées sont toujours multi-discussions.
- Facture à discussion unique : payable uniquement dans la discussion où elle a été envoyée ; les copies transférées affichent à la place un bouton de lien profond vers le bot.
Notez qu’une facture à discussion unique envoyée dans la discussion privée avec votre bot ne peut être payée qu’une seule fois. Dans tous les cas, votre bot décide toujours d’accepter ou non un nouveau paiement.
Étape 3 : contrôle avant paiement
L’utilisateur (qui achète d’abord des Stars si nécessaire) appuie sur Payer. Votre bot reçoit une pre_checkout_query avec les détails de la commande et doit répondre avec answerPreCheckoutQuery dans les 10 secondes, sinon la transaction est annulée. En cas de refus, indiquez une raison compréhensible ; Telegram l’affiche à l’utilisateur.
Étapes 4–5 : paiement et livraison
Lorsque le paiement réussit, un message successful_payment arrive. Ne livrez qu’à ce moment-là, car répondre à pre_checkout_query ne garantit pas que le paiement a abouti. Enregistrez le telegram_payment_charge_id ; vous en aurez besoin pour les remboursements.
Avant la mise en production
- Activez la validation en deux étapes pour le compte qui contrôle le bot.
- Fournissez les conditions via /terms, et l’assistance via /support et /paysupport.
- Préparez-vous aux litiges et aux remboursements avec refundStarPayment. Plus de détails dans remboursements Stars et /paysupport.
- Maintenez le serveur stable et sauvegardez les données de paiement.
Comment tester
L’environnement de test dédié de Telegram permet de tester gratuitement les paiements en Stars. Une fois que tout fonctionne, passez en production.
Le côté achat de Stars
Vos utilisateurs achètent des Stars dans l’application ou via @PremiumBot, et PayStars les vend contre des USDT. Si votre propre service doit acheter des Stars automatiquement, l’API PayStars et l’aperçu de l’API en parlent.
FAQ
Puis-je accepter des cryptomonnaies ou une autre devise à la place des Stars ?
Non. Les biens et services numériques dans les applications Telegram se paient uniquement en Stars.
Comment tester les paiements ?
Connectez votre bot à l’environnement de test dédié de Telegram, où les paiements en Stars peuvent être testés gratuitement.
Comment effectuer un remboursement ?
Avec la méthode refundStarPayment de l’API Bot.
Sources
Related pages
Acheter des Stars et Premium en USD (USDT)
Via une clé API : prix Fragment, 0 % (site : 5 %).
More news
Rédiger une politique de remboursement pour votre bot Telegram Stars : modèle et exemplesCe qu'une politique de remboursement pour un bot Telegram Stars doit couvrir : éligibilité, délai, /paysupport et refundStarPayment, plus des formulations types à adapter.Lire →
Que deviennent vos Telegram Stars si vous perdez l'accès à votre compteLes Stars appartiennent à votre compte Telegram, pas à votre téléphone. Découvrez ce qui leur arrive lorsque vous perdez l'accès, comment vous reconnecter et comment protéger votre solde.Lire →
Tenir les registres des revenus Telegram Stars en tant que créateur ou entrepriseComment tenir des registres clairs des revenus Telegram Stars : quoi consigner, suivre les retraits Fragment, séparer le personnel et l'activité, et quoi demander à un comptable.Lire →