Guide · Telegram Stars

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é:

Factures Telegram Stars (XTR) dans les bots : le flux de paiement pour les développeurs, étape par étape

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

ÉtapeCe que fait le botCe que Telegram envoie
1sendInvoice avec currency = XTR—
2Attendpre_checkout_query
3answerPreCheckoutQuery (dans les 10 secondes)—
4Attendsuccessful_payment
5Enregistre 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 :

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

Acheter des Stars et Premium en USD (USDT)

Via une clé API : prix Fragment, 0 % (site : 5 %).

Commencer