Migrating Telegram Bot Payments to Stars: Stripe & Yookassa Guide

Migrating Telegram Bot Payments to Stars: Stripe & Yookassa Guide

TL;DR. If your bot sells a digital good or service — a subscription, a data pack, extra bot uses — Telegram requires you to charge in Stars (XTR), not Stripe or Yookassa; that rule has stood since Stars launched and is not new. Physical goods still work fine on your existing fiat provider. The real migration is running both rails in parallel — one invoice per currency, never mixed — until every digital line item is on Stars and every physical one is not. Below are the three paths that work, the API constraints that trip people up, and what to leave alone.

Ready to stop context-switching between payment consoles and channel posting? Autogram automates the posting side so payments are the only thing left to migrate.

Prerequisites

Before you touch a single invoice call, settle two questions:

• Which of your bot's line items are digital? Telegram's own line is subscriptions, in-bot currencies, extra levels or uses, and "similar intangible products" — sold inside a Telegram app. That line has to use Stars.
• Which are physical, or delivered outside Telegram entirely? A shipped product, an in-person service, an invoice for work billed off-platform — none of that is covered by the Stars requirement, and Stripe or Yookassa keep working exactly as before.

Most bots that ask "how do I migrate to Stars" turn out to have a mix of both, and the honest answer is: you migrate the digital half and leave the rest alone. Confusing the two is the single biggest mistake in this whole process — more on that below.

Step 1 — Read the actual constraint, not the internet's summary of it

The rule, verbatim from Telegram's own Bot Payments API docs (checked September 2026): digital goods and services sold via bots and mini apps must be paid for exclusively in Telegram Stars. Telegram frames this as staying compliant with Apple's and Google's in-app-purchase policies — Stars is Telegram's answer to the same rule every other app-store-distributed app follows for digital content.

What it does not say: it does not touch physical goods. Telegram's own launch post (June 2024) is explicit that "purchases of physical products stay exactly the same – using any of Telegram's supported payment providers." So if your bot sells a printed poster, a coaching call billed by the hour, or anything else delivered outside the app, Stripe and Yookassa remain valid — this migration has nothing to do with them.

Photo by DS stories on Pexels

Step 2 — Run both rails side by side (the "dual-currency" step)

Here's the part the API doesn't let you fudge: a single Telegram invoice is one currency. Per the Bot API changelog for May 2024, createInvoiceLink and sendInvoice require the price breakdown to contain exactly one item when the currency is XTR, and provider_token must be omitted entirely for a Stars invoice — you cannot attach a Stripe provider token to an invoice priced in Stars, and you cannot price one invoice in both USD and Stars at once.

So "dual-currency" in practice means two invoice links, not one invoice:

1. Keep your existing Stripe/Yookassa createInvoiceLink call for the fiat price, untouched.
2. Add a second createInvoiceLink call with currency: "XTR", an empty provider_token, and a Stars-denominated price.
3. Show the user both buttons — "Pay $4.99" and "Pay with ⭐ 350" — and let them pick.

This is also where most teams discover their price ladder doesn't map cleanly: Telegram doesn't publish a fixed peg, and third-party trackers put the going rate somewhere around $0.013–$0.02 per Star depending on platform and purchase size, so round your Stars prices to a sane number rather than a literal currency conversion.

Step 3 — Cut the recurring digital line over to Stars, keep the rest on fiat

For subscriptions and other recurring digital charges, createInvoiceLink and sendInvoice support subscription_period, but only when currency is XTR — recurring Stars billing is not optional-currency, it's Stars-only by construction. If you're moving a recurring digital product, this is the moment you retire the old provider token for that specific product rather than trying to keep a recurring Stripe subscription "as a fallback": once the parallel-run window closes, the digital SKU has exactly one payment path.

Two things to build before you flip the switch:

• Refunds. refundStarPayment (added in Bot API 8.0) is a bot-side call, not a Telegram-support ticket — build it into your support flow now, because "all sales of Stars are final" from the user's side means your bot is the only refund path a buyer has.
• Withdrawal expectations. Stars you earn settle through Fragment into TON, gated by a 1,000-Star minimum and a 21-day hold on each batch from the day it's earned. Budget for that lag; it is not a same-day settlement the way a card payout can be.

Photo by Tranmautritam on Pexels

Common mistakes

• Treating "Stars vs. Stripe" as a global choice. It's per-SKU, not per-bot. Digital and physical line items can — and usually should — coexist on different rails in the same bot.
• Trying to send one invoice with both a fiat price and a Stars price. The API rejects a price breakdown that isn't exactly one currency; build two invoice links instead.
• Assuming Stripe was ever an option for a Russia-market bot. Stripe's own sanctions policy confirms it does not support users located in Russia, Ukraine, or Belarus at all — for that audience the realistic starting point was always Yookassa (still actively documented for Telegram bots as of April 2026), not Stripe, so "migrating away from Stripe" doesn't apply there in the first place.
• Forecasting Stars revenue at face value. What you receive per Star is lower than what the buyer paid for it, and Fragment's conversion to TON adds its own spread on top — budget on the earn side, not the list price.

Related reading

• Telegram Star Subscriptions Setup: A Recurring-Revenue How-To — the subscription_period mechanics this migration's Step 3 leans on.
• Refunding Telegram Stars: How refundStarPayment Actually Works — build this before you retire your old refund flow.
• TON to Fiat for Channel Operators: Fragment Withdrawal Walkthrough — what happens after Stars land in your balance.
• Telegram Stars Monetization: A 2026 Toolkit for Channel Owners — the wider monetization picture beyond bot payments specifically.

FAQ

Do I have to use Telegram Stars for everything my bot sells?

No — only for digital goods and services sold inside a Telegram app: subscriptions, in-bot currencies, extra features, and similar intangible products. Physical goods and off-platform services can stay on Stripe, Yookassa, or any other supported provider.

Can one invoice offer both a fiat price and a Stars price?

No. createInvoiceLink and sendInvoice require the price breakdown to contain exactly one item when currency is XTR, and reject a mixed fiat-plus-Stars line. Offer two separate invoice links and let the buyer pick.

Is Stripe still usable for a Telegram bot at all?

Yes, for anything outside the digital-goods rule — physical products and off-platform services. It was also never available for buyers in Russia, Ukraine, or Belarus, regardless of what the bot sells, since Stripe does not support those countries.

Is Yookassa still supported for Telegram bots?

Yes — Yookassa's own Telegram-bot integration docs remain live and were last updated in April 2026. It's a valid rail for anything outside the Stars-mandatory digital-goods rule, and it's the realistic default for a Russia-market bot, since Stripe was never an option there.

How do refunds work once I'm on Stars?

Through the refundStarPayment Bot API method, added in Bot API 8.0 — your bot has to call it. Telegram's own terms say Stars purchases are final from the buyer's side, so your bot is the buyer's only refund path if it fails to deliver what it promised.

How long until I can withdraw Stars I've earned?

Withdrawal through Fragment needs a 1,000-Star minimum balance, and each batch of Stars unlocks 21 days after you earned it — plan cash flow around that lag, not a same-day payout.

What's a Star actually worth in real money?

Telegram doesn't publish a fixed peg, and the rate varies by platform and purchase size — third-party trackers put it in the neighborhood of $0.013–$0.02 per Star as of 2026. Round your Stars prices to sensible numbers rather than chasing an exact conversion that will drift anyway.

Bottom line

Explore Autogram's plans. Connect your first channel to start 7 days of Solo access, with a $1 AI budget and no card required.

Image credits

• Hero: Photo by Mikhail Nilov on Pexels
• Inline 1: Photo by DS stories on Pexels
• Inline 2: Photo by Tranmautritam on Pexels