How to accept Stars payments in your own bot
How to accept Stars payments in a Telegram bot: an invoice in XTR without a payment provider, answering pre-checkout within 10 seconds, Stars refunds, the /paysupport command and withdrawing Stars through Fragment.
Digital goods and services in Telegram bots are sold for Stars. You don't need a payment provider for that: the bot issues a Stars invoice itself through the Bot API, and the Stars land on the bot's balance.
Why Stars
Under Telegram's rules, digital goods and services in bots and mini apps are paid for only with Stars — app store rules require it too. Physical goods can be sold for money through payment providers.
How to issue a Stars invoice
- Call
sendInvoice(an invoice in a chat) orcreateInvoiceLink(a payment link). - Set the currency to
XTR— that's how the Bot API names Stars. - Leave
provider_tokenas an empty string: Stars need no provider. - In
prices, pass one item — the amount in Stars.
The user sees the invoice, confirms the payment, and the Stars are taken from their balance.
See also: How to create a Telegram bot.
Required steps after payment
- pre_checkout_query. Before charging, Telegram sends the bot a query. You must answer
answerPreCheckoutQuerywithin 10 seconds, or the payment is cancelled and the user sees the "bot precheckout timeout" error. Answer right away and do the heavy work after answering. - successful_payment. After payment, a message with
telegram_payment_charge_idarrives. Store it: you need it for a refund. - Delivery. Deliver the goods only after
successful_payment.
Refunds, history and support
- Refund — the
refundStarPaymentmethod withtelegram_payment_charge_id: the Stars go back to the buyer. - History — the
getStarTransactionsmethod shows the bot's incoming payments and refunds. - /paysupport — the bot must answer this command: it's how buyers ask about payments.
Subscriptions and paid content
- Subscription. In
createInvoiceLinkyou can set a subscription period — Stars are then charged every 30 days until the user cancels. - Paid photos and videos. The
sendPaidMediamethod sends content that unlocks for Stars; how it looks to people is in photos and videos for Stars.
How to withdraw a bot's Stars
Stars collect on the bot's balance, shown in the bot's profile: "Edit" → "Balance". They can be withdrawn through Fragment — from 1,000 Stars, and each one becomes available 21 days after it arrives. A bot's Stars can also pay for Telegram Ads at a discount — Telegram Ads for Stars. Withdrawal step by step is in how to withdraw Stars from a bot.
Need to send Stars or Premium to your users rather than accept Stars? The Shiba Bank bot's API does that — the Telegram Stars API.
FAQ
How do I add Stars payments to a Telegram bot?
Issue an invoice with sendInvoice or createInvoiceLink in XTR with an empty provider_token, answer pre-checkout within 10 seconds and deliver after successful_payment.
Do I need a payment provider for Stars?
No. For Stars, provider_token is an empty string.
How do I refund Stars to a buyer?
With the refundStarPayment method and the telegram_payment_charge_id from the payment message.
When can I withdraw a bot's Stars?
Through Fragment — from 1,000 Stars, each available 21 days after it arrives.
