Bot type
Take payment without a merchant account, for the things Stars allow
A Telegram Stars payment bot charges for digital goods, subscriptions and access using Telegram's own currency, settled by Telegram with no merchant account and no card processing. Stars may not be used for physical goods. Telegram takes a share, and the payout path has its own rules.
Telegram Stars payment bots: price, timeline and limits
- Fixed price
- $6,700 USD
- Delivery
- 28 calendar days from kickoff
- pre_checkout_query
- Must be answered within ~10 seconds or the payment fails
- Permitted goods
- Digital goods and services only
- Payment updates
- At-least-once — can arrive more than once
- Refunds
- Available via the Bot API for a limited window after the charge
As of 2025-10-01, Telegram Bot API 13.4
The problem this solves
Getting a merchant account is the step that kills most small digital products. A card processor wants an entity, a licence, a history and often a reserve, and for a creator selling access to a private channel or a project selling a report, that overhead is larger than the product. Stars remove it: Telegram handles the payment, the user pays with a balance they already have or top up in-app, and no card ever touches your infrastructure.
The obvious catch is what Stars are allowed to buy. Telegram's policy limits them to digital goods and services — access, subscriptions, content, in-app items. Selling anything physical through Stars is a breach that risks the bot itself, and it is a mistake that gets made constantly because the API does not stop you. The second catch is economics: Telegram takes a cut, and the effective rate compares differently against a card processor depending on your price point and your jurisdiction.
Where Stars are genuinely strong is the friction. A user tapping to buy has no form to fill, no card to find, no 3-D Secure interruption. Conversion on a Stars checkout is materially better than on a card checkout for small amounts, and for a two-dollar purchase that difference decides whether the product exists at all. The build is worth doing when what you sell is digital, the price point is low, and the audience is already in Telegram.
How the build runs
The product is defined as an entitlement, not a payment
What the buyer gets, for how long, and what happens when it lapses. Modelling the purchase rather than the entitlement is why so many paid-access bots end up with users who paid and lost access, or who never paid and kept it.
commandsAn invoice is sent in the chat
Telegram renders the Stars price and handles the payment interface. There is no form and no redirect, which is the whole conversion advantage.
payments-apiThe pre-checkout query is answered before money moves
Telegram asks the bot to confirm the order is still valid, and it must answer within seconds. This is where stock, eligibility and duplicate purchases are checked — after payment is too late.
payments-apiA successful payment grants the entitlement idempotently
Keyed on the Telegram payment charge id, so a duplicate delivery of the same update cannot grant twice. Payment webhooks are at-least-once and this is not theoretical.
webhookAccess is enforced against entitlement on every check
Channel membership, feature access or content delivery is checked against current entitlement rather than against a flag set at purchase. That is what makes expiry and refund work correctly.
chat-member-updatesRefunds revoke access as well as returning Stars
The Bot API supports refunding a Stars payment within a window. A refund that returns the money and leaves access intact is a leak, and it is the default outcome if entitlement is not modelled properly.
payments-api
What Telegram will and will not let you do
Telegram Stars may be used only for digital goods and services, not for physical goods.
This is a policy limit, not a technical one — the API will happily invoice for a T-shirt. Doing so risks the bot, so physical fulfilment routes to a conventional provider.
The bot must answer a `pre_checkout_query` within about 10 seconds or the payment fails.
Every validation on that path has a hard latency budget. A synchronous call to a slow third-party API during pre-checkout will lose sales intermittently and confusingly.
Payment updates are delivered at least once and can arrive more than once.
Entitlement grants are idempotent on the charge id. Without that, a redelivered update extends a subscription twice and the discrepancy surfaces at reconciliation, not at the time.
Stars refunds are available through the Bot API for a limited period after the charge.
Your refund policy cannot promise more than the window allows. Beyond it, a refund is a manual goodwill payment and the terms should say so plainly.
Telegram retains a share of Stars revenue, and payout is subject to its own thresholds and schedule.
Effective take rate and cash-flow timing differ from a card processor. For low-value digital goods Stars usually still wins on conversion, but the comparison is worth modelling rather than assuming.
When not to build this
- You are selling anything physical. Stars are not permitted for it, and building on the assumption they are puts the bot at risk.
- Your price point is high. At larger amounts the conversion advantage shrinks and the take rate becomes the dominant term; a card processor is usually cheaper.
- You need funds settled quickly into an operating account. Stars payout has its own schedule and thresholds, which does not suit a business paying suppliers weekly.
- Your buyers are outside Telegram. Stars require a Telegram account and a balance, which is a wall rather than a step for anyone not already there.
What it runs on
| Component | Version | Why |
|---|---|---|
| grammY | 1.45 | Bot framework, with payment and pre-checkout handlers. |
| Cloudflare Workers | current | Runtime, sized for the pre-checkout latency budget. |
| Cloudflare D1 | current | Entitlements, charge ids, refunds and reconciliation records. |
| Zod | 4.4 | Validation of payment payloads, which arrive from outside your control. |
| TypeScript | 5.9 | Strict mode. Entitlement state is money-adjacent and typed accordingly. |
Questions people ask before committing
Can we sell physical products with Stars?
No. Telegram limits Stars to digital goods and services, and the API will not stop you breaching that — it is a policy boundary enforced by consequences rather than by errors. Physical goods route through a conventional payment provider.
How does the take rate compare to a card processor?
Telegram retains a share, and whether that is better depends on your price point. For low-value digital purchases the conversion advantage of a one-tap checkout usually dominates the rate. At higher amounts it generally does not, and the comparison is worth modelling on your own numbers.
Do we need a merchant account or a licence?
No, which is most of the appeal. Telegram is the merchant of record for Stars, so there is no card processing on your side, no PCI scope and no acquirer relationship to establish.
What happens if we refund but the user keeps access?
That is the failure this build is designed around. Access is checked against current entitlement rather than a flag set at purchase, so revoking the entitlement removes access immediately. Modelling the purchase instead of the entitlement is how the leak appears.
Can we run recurring subscriptions?
Yes. Telegram supports recurring Stars charges, and the entitlement model handles renewal, lapse and re-subscription as state transitions rather than as separate purchases, which is what keeps access correct across all three.
What if the same payment webhook arrives twice?
Nothing, by design. Grants are idempotent on the charge id, so a redelivery is a no-op. Payment updates are at-least-once and duplicates do occur, so this is a correctness requirement rather than a precaution.