Stars Payment Flow at a Glance
Cheat sheets · 2026-11-06 · 18+ readers
A Stars sale is a short conversation between your bot and Telegram. Here it is as a timeline.
The timeline
| Step | Who acts | What happens |
|---|---|---|
| 1 | Bot | Sends an invoice with currency XTR |
| 2 | Buyer | Presses Pay |
| 3 | Sends pre_checkout_query | |
| 4 | Bot | Answers ok within about ten seconds |
| 5 | Sends a message with successful_payment | |
| 6 | Bot | Records the charge id and delivers |
| 7 | Bot (later) | Calls refundStarPayment if needed |
Fields worth remembering
- Invoice:
title,description,payload,currency,priceswith one item. - Payment record:
total_amount,invoice_payload,telegram_payment_charge_id. - Refund:
user_idand the charge id.
Safety rules
- Deliver only after
successful_payment. - Deliver once, even if the update repeats.
- Check amount and currency against your order.
- Offer a support contact and a clear refund policy.
Frequently asked questions
Do I need a provider token?
Not for Stars.
Can an invoice list several items?
Stars invoices carry one price item. Bundle products instead.
Where do I see totals?
getStarTransactions lists transactions.