Guida · Telegram Stars

Fatture Telegram Stars (XTR) nei bot: il flusso di pagamento per gli sviluppatori, passo dopo passo

Vendere beni digitali in cambio di Stars in un bot: sendInvoice con XTR, risposta a pre_checkout_query entro 10 secondi, successful_payment, salvataggio del charge ID e checklist di lancio.

Pubblicato:

Fatture Telegram Stars (XTR) nei bot: il flusso di pagamento per gli sviluppatori, passo dopo passo

Il tuo bot vende qualcosa di digitale, come un abbonamento, contenuti, richieste di AI o oggetti di gioco? Allora il pagamento è solo in Telegram Stars. Questo articolo illustra il flusso della fattura Telegram Stars (XTR) dal punto di vista di uno sviluppatore, seguendo la documentazione ufficiale della Bot API. Per capire perché deve essere Stars, vedi beni digitali nei bot solo tramite Stars.

Il flusso in sintesi

PassoCosa fa il botCosa invia Telegram
1sendInvoice con currency = XTR—
2Attendepre_checkout_query
3answerPreCheckoutQuery (entro 10 secondi)—
4Attendesuccessful_payment
5Salva il charge ID e consegna i beni—

Passo 1: crea la fattura

Ci sono due modi:

  • Fattura del bot: il metodo sendInvoice. Poiché i beni sono digitali, provider_token è una stringa vuota e il campo currency è XTR. La fattura può andare in una chat privata, in un gruppo o in un canale.
  • Fattura inline: se il bot supporta la modalità inline, inputInvoiceMessageContent permette agli utenti di condividere la fattura con amici, gruppi e canali. Il pulsante Pay può essere usato molte volte.

Passo 2: scegli il comportamento di inoltro

Il parametro start_parameter lo controlla:

  1. Fattura multi-chat: le copie inoltrate mantengono un pulsante Pay, così molti utenti possono pagare. Le fatture inline sono sempre multi-chat.
  2. Fattura single-chat: pagabile solo nella chat in cui è stata inviata; le copie inoltrate mostrano invece un pulsante di collegamento diretto al bot.

Nota: una fattura single-chat inviata nella chat privata con il tuo bot può essere pagata una sola volta. In ogni caso, è sempre il bot a decidere se accettare un nuovo pagamento.

Passo 3: verifica preliminare

L'utente (acquistando prima Stars se necessario) tocca Pay. Il bot riceve una pre_checkout_query con i dettagli dell'ordine e deve rispondere con answerPreCheckoutQuery entro 10 secondi, altrimenti la transazione viene annullata. Se rifiuti, indica un motivo comprensibile; Telegram lo mostra all'utente.

Passi 4–5: pagamento e consegna

Quando il pagamento riesce, arriva un messaggio successful_payment. Solo allora devi consegnare, perché rispondere a pre_checkout_query non garantisce che il pagamento sia andato a buon fine. Salva il telegram_payment_charge_id: ti servirà per i rimborsi.

Prima di andare in produzione

  • Attiva la verifica in due passaggi per l'account che controlla il bot.
  • Fornisci i termini tramite /terms e il supporto tramite /support e /paysupport.
  • Preparati a contestazioni e rimborsi con refundStarPayment. Approfondisci in rimborsi Stars e /paysupport.
  • Mantieni il server stabile e fai il backup dei dati di pagamento.

Come testare

L'ambiente di test dedicato di Telegram ti permette di testare i pagamenti in Stars gratuitamente. Quando tutto funziona, passa alla produzione.

Il lato dell'acquisto di Stars

I tuoi utenti comprano Stars nell'app o tramite @PremiumBot, e PayStars le vende in cambio di USDT. Se il tuo servizio deve acquistare Stars in automatico, lo coprono l'API PayStars e la panoramica dell'API.

Domande frequenti

Posso accettare criptovalute o un'altra valuta al posto di Stars?

No. I beni e i servizi digitali nelle app Telegram si pagano solo in Stars.

Come testo i pagamenti?

Collega il bot all'ambiente di test dedicato di Telegram, dove i pagamenti in Stars si possono testare gratuitamente.

Come emetto un rimborso?

Con il metodo refundStarPayment della Bot API.

Fonti

Acquista Stars e Premium con USD (USDT)

Con chiave API: prezzo Fragment, 0% (sito: 5%).

Inizia