Integration

Stars, and the policy line the API will happily let you cross

Telegram Stars are Telegram's in-app currency, usable for digital goods and services with no merchant account and no card processing. The API will invoice for anything; the policy permits only digital goods, and breaching it risks the bot. Telegram retains a share and payout runs on its own schedule.

Telegram Stars integration: auth, limits and availability

Auth model: None required
Permitted goods: Digital goods and services only
GCC availability: Available wherever Telegram is, with no merchant onboarding
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

Stars remove the single biggest obstacle to selling small digital products: the merchant account. A creator selling access to a channel, a project selling a research note, a game selling an item — all of these are commercially viable at two or three dollars only if the friction of taking the payment is near zero on both sides. A card processor requires an entity, underwriting and a reserve; Stars require a bot.

The friction removal on the buyer side is just as significant. There is no form, no card entry and no 3-D Secure interruption. The user taps, confirms with a balance they already hold, and the purchase is done. At low price points that difference is not marginal — it determines whether the product exists.

The constraint that gets projects into trouble is that the policy boundary is not enforced by the API. Nothing stops you invoicing Stars for a T-shirt; the consequence arrives later and lands on the bot rather than on the transaction. Because the failure is delayed and total, it is worth treating the digital-goods limit as a hard architectural constraint at scoping rather than as a term to check before launch.

How the data actually moves

Pre-checkout is the last point at which an order can be refused, and the answer has a hard ten-second budget. Everything that must be checked is checked there.

There is no separate integration credential. Stars are part of the Bot API, so the bot token is the only secret involved, and payment events arrive through the same authenticated webhook as every other update. That means the webhook secret-token check is doing double duty: without it, anyone who guesses your webhook URL can post fabricated successful-payment events.

Auth model: No authentication

Their limits, and what they mean for you

Stars may be used only for digital goods and services, not physical goods.

A policy limit rather than a technical one. The API will invoice for a physical product and the consequence lands on the bot, which makes this an architectural constraint rather than a checklist item.

A `pre_checkout_query` must be answered within roughly 10 seconds or the payment fails.

Everything on that path has a hard latency budget. A synchronous call to a slow third-party API during pre-checkout loses sales intermittently, and the pattern is hard to diagnose because it is load-dependent.

Stars payments can be refunded through the Bot API within a limited window.

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 rather than implying an unlimited right.

Telegram retains a share of Stars revenue, and payout is subject to thresholds and its own schedule.

Effective take rate and cash-flow timing differ from a card processor. At low price points the conversion advantage usually dominates; at higher ones it usually does not.

Payment updates are delivered at least once and may arrive more than once.

Entitlement grants are idempotent on the charge id. Without that, a redelivered update extends a subscription twice and the discrepancy shows up at reconciliation rather than at the time.

How it fails, and what happens when it does

Pre-checkout times out because a validation call was too slow.

Validation data needed at pre-checkout is cached ahead of time. The customer experiences a failed payment for no visible reason, which is among the worst failure modes available.

A successful payment update is delivered twice.

The grant is idempotent on the charge id, so the second delivery is a no-op. This is documented behaviour rather than an edge case.

A refund is issued and the customer retains access.

Entitlement is the record the bot reads on every access check, not a one-off flag written when the charge cleared. Revoke the entitlement and the next check fails, which is what makes a refund actually take effect rather than leaving a paid-once member inside forever.

A user buys the same subscription twice by tapping an old invoice.

Pre-checkout rejects a purchase that would duplicate an active entitlement, with an explanation. Refunding afterwards is possible and is a worse experience than not taking the money.

Availability in the UAE and the wider GCC

Global, within Telegram

Available wherever Telegram is, with no per-country merchant onboarding. The buyer needs a Telegram account and a Stars balance.

Physical goods

Not permitted, anywhere. This is the constraint that most often forces a second payment rail alongside Stars.

United Arab Emirates

No local licensing step for Stars specifically, since Telegram is the merchant of record. Your own tax and reporting obligations on the revenue are unchanged.

High-value transactions

Technically fine and commercially questionable. As amounts rise the take rate dominates the conversion advantage, and a conventional processor is usually cheaper.

When not to use this integration

You are selling anything physical. Not permitted, and the API not stopping you is the trap rather than the permission.
Your price point is high. The take rate becomes the dominant term and a card processor is usually cheaper.
You need funds in an operating account quickly. Payout has thresholds and a schedule that does not suit paying suppliers weekly.
Your buyers are not Telegram users. Stars require an account and a balance, which is a wall rather than a step.

What it runs on

Component	Version	Why
grammY	1.45	Invoice sending, pre-checkout and successful-payment handlers.
Cloudflare Workers	current	Runtime, sized against the pre-checkout latency budget.
Cloudflare D1	current	Entitlements, charge ids, refunds and reconciliation.
Zod	4.4	Validation of payment payloads arriving on the webhook.

Questions that come up during scoping

Can we sell a physical product if we describe it as a digital voucher?

No, and framing it that way is worse than doing it openly because it demonstrates awareness. The policy is about what the buyer receives. A physical fulfilment needs a conventional payment rail alongside Stars.

What exactly has to happen within the ten-second pre-checkout window?

Every check that could refuse the order: stock, eligibility, duplicate entitlement, price validity. Anything slow is cached ahead of time, because a timeout presents to the customer as an unexplained failed payment.

Do we need any licence or merchant account?

No. Telegram is the merchant of record for Stars, so there is no card processing on your side and no PCI scope. Your own tax and reporting obligations on the revenue are unaffected.

How do refunds work?

Through the Bot API within Telegram's refund window, and the refund must also revoke the entitlement or you have returned the money and kept nothing. Beyond the window it becomes a manual goodwill payment.

Is the effective rate better or worse than a card processor?

At low price points, usually better once you account for conversion — a one-tap checkout with no card entry completes far more often. As amounts rise the take rate dominates. It is worth modelling on your own numbers rather than assuming either way.

What stops someone forging a successful payment event?

The webhook secret token, which is verified on every request before the update is processed. It is the only thing standing between a guessed webhook URL and fabricated payment events, which makes it more load-bearing here than people assume.