tg-stars-payments

Checked against the official docs on 2026-10-30: Bot API 10.3 (August 24, 2026), the Stars payments guide and the developer terms § 6.2. Nothing here was run against a live bot, see Not verified live.

Digital goods and services sold inside Telegram apps go through Stars only: currency XTR, empty provider_token. Physical goods use a provider, see Payments. Payout rates, the hold, expiry and the 15% topics fee live in references/stars-economics.md; read it before quoting money or enabling topics in private chats.

Purchase flow

1. Subscribe. The active allowed_updates includes message and pre_checkout_query, plus subscription and purchased_paid_media when you sell those. An omitted list keeps the previous setting, see tg-bot-ops. A bot without pre_checkout_query lets every checkout time out.
2. Create the invoice (table below). Put an order id in payload (1-128 bytes). The title is 1-32 characters, the description 1-255, prices has exactly one item, amounts are whole Stars.
3. Answer pre-checkout within 10 seconds with answerPreCheckoutQuery, or the transaction is canceled. Answer it in the handler itself, outside any update queue: a queue that lags 10 seconds cancels the purchase. Check stock and order state, not delivery. On ok: false pass error_message; Telegram shows it to the user.
4. Credit on successful_payment only. It arrives as a service message. Answering pre-checkout proves nothing; a Mini App paid status is a hint for the UI.
5. Store first, deliver second. See Recording and delivery.
6. Support. The bot answers /paysupport, and refunds through Refunds.

Done when: a repeated successful_payment starts no new delivery, two parallel handlers claim a payment once, and a crash between storing and delivering returns the order to the queue.

Creating the invoice