Bot type
A storefront that opens in the chat and settles on TON
A TON Mini App storefront is a web application running inside Telegram with a catalogue, a basket and checkout settled in TON or Telegram Stars. It is the fastest path from a Telegram audience to a paid transaction. It is not a substitute for a web store, and it inherits every constraint of the Telegram webview.
TON Mini App storefronts: price, timeline and limits
- Fixed price
- $9,200 USD
- Delivery
- 35 calendar days from kickoff
- Mini App auth
- initData HMAC-SHA256 against a key derived from the bot token
- Telegram Stars
- Digital goods and services only
- TON finality
- Irreversible once confirmed — no chargeback, no arbiter
- Viewport
- Reports its own height; expands on user gesture, not by default
As of 2025-10-01, Telegram Bot API 13.4
The problem this solves
For a project whose community already lives in Telegram, sending people to an external web store is a measurable loss. The tap out of the app, the wallet connection on an unfamiliar page, the return journey — each step sheds users, and the aggregate drop-off is large enough that it changes what is worth selling. A Mini App removes the departure entirely: the storefront opens over the chat, and the wallet the buyer already uses is a tap away.
The mistake teams make is treating a Mini App as a normal web build with a Telegram wrapper. It is not. The webview has its own viewport behaviour that fights conventional layout, its own theme parameters you are expected to honour, its own back-button semantics, and a hard requirement that the identity of the user be verified server-side rather than trusted from the client. Ignore that last point and you have not built a storefront, you have built an unauthenticated write endpoint with a catalogue in front of it.
The payment decision matters more than the catalogue. Stars and TON are different products with different rules: Stars are Telegram's own currency, permitted for digital goods and services and settled by Telegram; TON is a public chain settled by the buyer's wallet with no intermediary. Choosing wrongly means either a policy breach or a checkout your audience will not complete, and the choice is driven by what you are selling rather than by preference.
How the build runs
The Mini App opens over the chat, not beside it
Launched from a bot button or a direct link. The user never leaves Telegram, which removes the single largest source of drop-off in Telegram-native commerce.
mini-appIdentity is proven before any state is trusted
The webview receives an initData string signed with your bot token. Every request that reads or writes user state validates that HMAC on the server. Skipping it makes the basket endpoint writable by anyone with the URL.
web-app-initdataThe catalogue renders against the Telegram theme
Telegram exposes theme parameters that change with the user's app settings. A storefront that ignores them is legible in one theme and unreadable in the other, and roughly half your audience is in each.
mini-appCheckout routes to TON Connect or to Stars
Physical goods and most services go through a conventional provider or TON. Digital goods can use Stars, which Telegram settles directly. The distinction is a policy boundary, not a preference.
starsPayment is confirmed on-chain or by Telegram, then fulfilled
A TON payment is verified by watching for the transaction rather than trusting the client's claim to have sent it. Fulfilment is triggered by confirmation, which is the only signal that cannot be forged.
payments-apiThe order lands back in the chat
Confirmation, state changes and any delivery are pushed into the conversation. The Mini App closes; the chat persists, and that is where the customer will look tomorrow.
webhook
What Telegram will and will not let you do
The `initData` string must be validated by HMAC-SHA256 against a key derived from the bot token, and it carries an `auth_date` that must be checked for freshness.
Validating the signature but not the age leaves a replay window. Both checks are a dozen lines and their absence is the single most common Mini App vulnerability.
Telegram Stars may be used only for digital goods and services, not physical goods.
Selling merchandise through Stars is a policy breach that puts the bot at risk. Physical fulfilment routes to TON or to a conventional payment provider.
The Mini App viewport reports its own height and expands on user gesture rather than filling the screen by default.
Layouts built against `100vh` are cut off on open. The Telegram viewport API has to be honoured explicitly, and this is where most third-party Mini Apps visibly break.
A TON transaction is final and irreversible once confirmed.
There is no chargeback and no provider to arbitrate. Refunds are a business process you execute manually, and the storefront copy must not imply otherwise.
Telegram Stars payments can be refunded through the Bot API within a limited window.
Stars give you a refund path that TON does not. For a project weighing the two, that difference is often more decisive than the settlement mechanics.
The Mini App runs in a webview whose available storage and cookie behaviour differ across iOS and Android.
Session state lives server-side keyed by validated initData rather than in local storage. Relying on client persistence produces a basket that empties on iOS and not on Android.
When not to build this
- Your audience is not already on Telegram. A Mini App reaches people who are in the app; it is not a discovery channel and will not bring anyone.
- You need full SEO-indexed product pages. A Mini App is not crawlable, and a storefront that must rank in search needs a web presence alongside it.
- Your catalogue runs to thousands of SKUs with complex faceted search. The webview will do it badly and your customers will use the website instead.
- You are selling physical goods and expected Stars to handle it. That combination is not permitted and the build has to be scoped around a real payment provider.
What it runs on
| Component | Version | Why |
|---|---|---|
| grammY | 1.45 | Bot framework and the Mini App launch surface. |
| Telegram Mini Apps | Bot API 9.x | The storefront runtime, with viewport and theme APIs honoured. |
| TON Connect | 2.x | Wallet connection and transaction requests. |
| Cloudflare Workers | current | API surface, initData validation and on-chain confirmation watching. |
| Cloudflare D1 | current | Catalogue, baskets, orders and payment state. |
Questions people ask before committing
Should we settle in TON or in Stars?
What you sell decides it. Stars are permitted only for digital goods and services and give you a refund path through the Bot API. TON handles anything but is final on confirmation with no chargeback. Physical goods rule Stars out entirely.
What exactly is initData and why does it keep being mentioned?
It is a signed string Telegram hands the webview identifying the user. Validating its HMAC against your bot token, and checking its age, is what makes a request trustworthy. Without both, your order endpoint accepts anything, and this is the most common Mini App vulnerability by a distance.
Can customers pay with USDT?
Yes, as a jetton on TON, and for many audiences it converts better than native TON because the amount does not move between quote and payment. It is a configuration decision rather than a different build.
Will the storefront rank in Google?
No. A Mini App is not crawlable and is not intended to be. If search visibility matters, the Mini App is the conversion surface and a conventional web presence does the ranking, with the two sharing a catalogue.
How are refunds handled?
For Stars, through the Bot API within Telegram's refund window. For TON, manually — the transaction is irreversible, so a refund is a new payment you send. The storefront copy has to be honest about that difference rather than implying a uniform policy.
Does it work the same on iOS and Android?
Mostly, with real differences in webview storage and viewport behaviour. State is kept server-side keyed by validated initData rather than in the client precisely because client persistence behaves differently across the two.
Can we reuse our existing web store front end?
Rarely worth it. The viewport, theme, back-button and identity model differ enough that adapting an existing front end usually costs more than building the Mini App properly, and produces something that feels foreign inside Telegram.