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:

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
| Passo | Cosa fa il bot | Cosa invia Telegram |
|---|---|---|
| 1 | sendInvoice con currency = XTR | — |
| 2 | Attende | pre_checkout_query |
| 3 | answerPreCheckoutQuery (entro 10 secondi) | — |
| 4 | Attende | successful_payment |
| 5 | Salva 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:
- Fattura multi-chat: le copie inoltrate mantengono un pulsante Pay, così molti utenti possono pagare. Le fatture inline sono sempre multi-chat.
- 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
Related pages
Acquista Stars e Premium con USD (USDT)
Con chiave API: prezzo Fragment, 0% (sito: 5%).
More news
Scrivere una politica di rimborso per il tuo bot Telegram Stars: modello ed esempiCosa deve coprire una politica di rimborso per un bot Telegram Stars: idoneità, finestra temporale, /paysupport e refundStarPayment, più testi di esempio da adattare.Leggi →
Cosa succede alle tue Telegram Stars se perdi l'accesso al tuo accountLe Stars appartengono al tuo account Telegram, non al telefono. Scopri cosa succede quando perdi l'accesso, come rientrare e come proteggere il saldo.Leggi →
Tenere i registri dei ricavi Telegram Stars come creatore o aziendaCome tenere registri chiari dei ricavi Telegram Stars: cosa annotare, come tracciare i prelievi Fragment, come separare personale e attività, e cosa chiedere a un commercialista.Leggi →