Telegram Stars invoices (XTR) in bots: the payment flow for developers, step by step
Selling digital goods for Stars in a bot: sendInvoice with XTR, the 10-second pre_checkout_query reply, successful_payment, storing the charge ID and a launch checklist.
Published:

Does your bot sell something digital, such as a subscription, content, AI requests or in-game items? Then payment is in Telegram Stars only. This article walks through the Telegram Stars invoice (XTR) flow from a developer's point of view, following the official Bot API documentation. For why it has to be Stars, see digital goods in bots only via Stars.
The flow at a glance
| Step | What the bot does | What Telegram sends |
|---|---|---|
| 1 | sendInvoice with currency = XTR | — |
| 2 | Waits | pre_checkout_query |
| 3 | answerPreCheckoutQuery (within 10 seconds) | — |
| 4 | Waits | successful_payment |
| 5 | Stores the charge ID, delivers the goods | — |
Step 1: create the invoice
There are two ways:
- Bot invoice: the sendInvoice method. Because the goods are digital, provider_token is an empty string and the currency field is XTR. The invoice can go to a private chat, a group or a channel.
- Inline invoice: if your bot supports inline mode, inputInvoiceMessageContent lets users share the invoice with friends, groups and channels. Its Pay button can be used many times.
Step 2: choose forwarding behaviour
The start_parameter parameter controls this:
- Multi-chat invoice: forwarded copies keep a Pay button, so many users can pay. Inline invoices are always multi-chat.
- Single-chat invoice: payable only in the chat it was sent to; forwarded copies show a deep-link button to the bot instead.
Note that a single-chat invoice sent in the private chat with your bot can be paid only once. Either way, your bot always decides whether to accept a new payment.
Step 3: pre-checkout
The user (buying Stars first if needed) taps Pay. Your bot receives a pre_checkout_query with the order details and must reply with answerPreCheckoutQuery within 10 seconds, or the transaction is cancelled. If you decline, give a human-readable reason; Telegram shows it to the user.
Steps 4–5: checkout and delivery
When payment succeeds, a successful_payment message arrives. Only then should you deliver, because answering pre_checkout_query doesn't guarantee the payment went through. Store the telegram_payment_charge_id; you'll need it for refunds.
Before you go live
- Turn on two-step verification for the account that controls the bot.
- Provide terms via /terms, and support via /support and /paysupport.
- Be ready for disputes and refunds with refundStarPayment. More in Stars refunds and /paysupport.
- Keep the server stable and back up payment data.
How to test
Telegram's dedicated test environment lets you test Stars payments for free. Once everything works, switch to production.
The Stars-buying side
Your users buy Stars in the app or through @PremiumBot, and PayStars sells them for USDT. If your own service needs to buy Stars automatically, the PayStars API and the API overview cover it.
FAQ
Can I accept crypto or another currency instead of Stars?
No. Digital goods and services inside Telegram apps are paid for in Stars only.
How do I test payments?
Connect your bot to Telegram's dedicated test environment, where Stars payments can be tested for free.
How do I issue a refund?
With the refundStarPayment method in the Bot API.
Sources
Buy Stars and Premium with USD (USDT)
Via API key: 0% (plain Fragment price). Via the website: 5%.
More news
Writing a refund policy for your Telegram Stars bot: template and examplesWhat a refund policy for a Telegram Stars bot should cover: eligibility, time window, /paysupport and refundStarPayment, plus sample wording you can adapt.Read →
What happens to your Telegram Stars if you lose access to your accountStars belong to your Telegram account, not your phone. Learn what happens to them when you lose access, how to get back in, and how to protect your balance.Read →
Keeping records of Telegram Stars revenue as a creator or businessHow to keep clean records of Telegram Stars revenue: what to log, tracking Fragment withdrawals, separating personal and business, and what to ask an accountant.Read →