Guide · Telegram Stars

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:

Telegram Stars invoices (XTR) in bots: the payment flow for developers, step by step

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

StepWhat the bot doesWhat Telegram sends
1sendInvoice with currency = XTR—
2Waitspre_checkout_query
3answerPreCheckoutQuery (within 10 seconds)—
4Waitssuccessful_payment
5Stores 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:

  1. Multi-chat invoice: forwarded copies keep a Pay button, so many users can pay. Inline invoices are always multi-chat.
  2. 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%.

Get started