Guide · PayStars

API PayStars pour les développeurs : le flux complet pour vendre Stars et Premium dans votre bot

Comment l'API REST PayStars fonctionne de bout en bout : X-API-Key, vérifications de nom d'utilisateur, devis en USD avec max_usd, commandes idempotentes, l'erreur 409 price_changed et la vérification du TxId, sous forme de plan d'intégration.

Publié: · Mis à jour:

API PayStars pour les développeurs : le flux complet pour vendre Stars et Premium dans votre bot

Vous voulez vendre Telegram Stars et Premium dans votre propre bot, boutique ou application ? L'API PayStars vous offre une interface HTTPS unique et un solde en USD partagé avec le site. Plutôt que de répéter la référence de l'API, cet article montre comment construire l'intégration du début à la fin.

L'architecture en un coup d'œil

Votre système fait trois choses : alimenter le solde avec USDT, demander un prix et créer une commande. Tout le reste, y compris la livraison via le flux d'achat officiel de Telegram, se fait côté PayStars.

PartieCe qu'elle fait
AccèsEn-tête X-API-Key ; les clés sont créées dans le tableau de bord
SoldeUSD, rechargé avec USDT (TON, BEP20 ou TRC20)
PrixPrix Fragment × 1.05, arrondi au centime supérieur
Limite10 requêtes par seconde et par clé
TransparenceUn TxId public pour chaque commande terminée

Étape 1 : alimenter le solde

POST /usd/invoice avec un montant et une chaîne ("ton", "bsc" ou "trc20") renvoie un montant exact valable 30 minutes. Le minimum est de 0.1 USDT.

Étape 2 : vérifier le destinataire

POST /api/v1/check-username vérifie le destinataire et renvoie un jeton de vérification de courte durée. Cela empêche les paiements vers des noms d'utilisateur inexistants : si un client fait une faute de frappe, vous le savez avant tout débit.

Étape 3 : obtenir et plafonner le prix

POST /api/v1/usd/quote renvoie le prix actuel (usd) et la majoration (markup_percent : 5). Le prix suit le marché, donc :

  • demandez un devis frais avant chaque commande ;
  • passez max_usd égal au montant indiqué ;
  • envoyez toujours currency : "USD", sinon la préférence enregistrée du compte est utilisée.

Étape 4 : créer la commande

POST /api/v1/stars/buy ou /api/v1/premium/buy. Chaque requête doit porter un Idempotency-Key, afin qu'en cas de coupure de connexion et de nouvelle tentative, vous ne soyez pas débité deux fois. Stockez la clé avec l'identifiant de commande dans votre base de données.

Étape 5 : suivre le statut

GET /api/v1/order/{id} et /api/v1/orders vous donnent les statuts et l'historique. La plupart des commandes sont livrées en quelques minutes. Une commande terminée reçoit un TxId que vous et votre client pouvez vérifier sur le registre public PayStars.

Gérer correctement les erreurs

  • 409 price_changed signifie que le prix a dépassé max_usd et que rien n'a été débité. Obtenez un nouveau devis et montrez au client le prix mis à jour.
  • Limite de débit : ne dépassez pas 10 requêtes par seconde ; ajoutez une file d'attente ou un délai de reprise.
  • Nouvelles tentatives : réutilisez toujours le même Idempotency-Key.

Avant la mise en production

  1. Conservez la clé API dans une variable d'environnement du serveur, pas dans le code.
  2. Exécutez tout le flux avec une petite commande réelle de 50 Stars.
  3. Montrez aux clients leur TxId, ce qui renforce la confiance.

Documentation complète et guides de démarrage : API Stars PayStars et tarification USD de l'API. Pour les paiements dans le bot, voir les biens numériques dans les bots se paient uniquement en Stars.

FAQ

Existe-t-il un bac à sable ?

Il n'y a pas de bac à sable distinct ; testez avec de petites commandes réelles (50 Stars) pendant l'intégration.

Quels langages de programmation fonctionnent ?

Tout langage capable d'envoyer des requêtes HTTPS. Des guides de démarrage existent pour Python, Node.js et PHP.

Comment alimenter le solde ?

Avec USDT sur TON, BEP20 ou TRC20, minimum 0.1 USDT ; chaque facture a un montant exact valable 30 minutes.

Sources

Acheter des Stars et Premium en USD (USDT)

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

Commencer