Take Stars payments in your bot: invoices, subscriptions and refunds
What it is
Digital goods and services in bots and Mini Apps sell only for Telegram Stars, currency `XTR`. Your bot issues an invoice, confirms the order at checkout, delivers after payment and keeps the payment ID for refunds. One parameter turns an invoice link into a 30-day subscription.
How to do it
- Use `sendInvoice`, or `createInvoiceLink` for a link: `currency` `XTR`, empty… Use `sendInvoice`, or `createInvoiceLink` for a link: `currency` `XTR`, empty `provider_token`, exactly one item in `prices`, your order ID in `payload`.
- Subscription: add `subscription_period` 2592000 (30 days) to `createInvoiceLink`.
- In a Mini App, open the link with `openInvoice`; `invoiceClosed` reports `paid`, `cancelled`, `failed` or `pending`.
- On `pre_checkout_query`, call `answerPreCheckoutQuery`: `ok` true, or false with an `error_message` for the buyer.
- Deliver only after `successful_payment`, and save its… Deliver only after `successful_payment`, and save its `telegram_payment_charge_id`. Subscription payments also carry `is_recurring`, `is_first_recurring` and `subscription_expiration_date`.
- Since July 2026, the `subscription` update reports `canceled`, `active` or `failed`.
- Refund with `refundStarPayment`; refunds arrive as `refunded_payment` service… Refund with `refundStarPayment`; refunds arrive as `refunded_payment` service messages. `editUserStarSubscription` cancels a renewal or lets the user re-enable one your bot canceled.
- Reconcile with `getStarTransactions` and `getMyStarBalance`.
Watch out
- Answer the pre-checkout query within 10 seconds, or the payment is cancelled.
- `payload` is 1–128 bytes, `title` 1–32 characters, `description` 1–255; tips don't work in Stars.
- A subscription costs at most 10,000 Stars; one user can hold several.
- `getStarTransactions` returns 1–100 records per call.
- A chargeback can take Stars back after `successful_payment`.
- Test first in Telegram's test environment.
With Gem
Gem doesn't run invoices for your own bot: a creator's own bot isn't available yet. In a Gem project, /myprojects › Sell takes Stars for your offers through @gembot, which Gem holds.
Sources
- https://core.telegram.org/bots/payments-stars
- https://core.telegram.org/bots/api#payments
- https://core.telegram.org/bots/webapps#initializing-mini-apps
- https://core.telegram.org/bots/api-changelog#july-14-2026