diamond Telegram Stars

Digital Goods Invoicing, Bot API Webhooks, and Developer Monetization Payouts

verified_user TGWAY Web3 Research Staff • calendar_today Published Sep 11, 2026 • visibility 2,110 Views

Monetizing digital goods and subscriptions inside Telegram bots and Mini Apps previously required fragmented credit card merchant gateways or risky off-platform checkout redirects that violated mobile app store guidelines. Telegram Stars (⭐) introduces a compliant, frictionless digital payment currency built directly into Telegram's Bot API (currency: "XTR"). Consumers purchase Stars seamlessly via Apple In-App Purchases, Google Play In-App Billing, or discounted direct web checkouts via Fragment. For developers, accumulated Stars can be converted into Toncoin (TON) on the Fragment marketplace or reinvested into Telegram Ad campaigns with zero platform commission. Understanding Stars invoicing, webhook verification lifecycles, and developer monetization cash-outs is mandatory for any modern Telegram Web3 application builder.

1 star

App Store Compliance

100% compliant with Apple App Store and Google Play guidelines for digital goods, avoiding account or bot bans.

2 receipt_long

Native Bot API Invoicing

Create seamless one-tap checkout modals in chat using standard sendInvoice endpoints with currency: "XTR".

3 currency_exchange

Fragment TON Payouts

Convert earned Stars directly into Toncoin cryptocurrency on Fragment, withdrawable to any non-custodial wallet.

4 campaign

0% Ad Credit Subsidies

Reinvest Stars directly into Telegram Ads with zero commission, effectively offsetting app store platform cuts.

1. Implementation Workflow: Integrating Telegram Stars Payments

Configure BotFather for Telegram Stars Invoicing

Message @BotFather → Select your bot → Bot Settings → Payments. Enable Telegram Stars as the designated payment provider. Note that no external Stripe or merchant API keys are needed!

Dispatch Invoice Payload via sendInvoice

Call the Telegram Bot API method sendInvoice with parameters: currency: "XTR", and define the price array: prices: [{"label": "VIP Pass", "amount": 100}]. 100 amount units corresponds exactly to 100 Stars.

Handle pre_checkout_query & successful_payment Webhooks

Your backend must respond to incoming pre_checkout_query within 10 seconds via answerPreCheckoutQuery(ok=True). Upon payment completion, Telegram dispatches successful_payment containing the Telegram charge ID for order fulfillment.

Execute Fragment Toncoin Withdrawal

Navigate to Fragment.com → Connect your bot owner account → View accumulated Stars balance. After the standard 21-day fraud protection holding period, initiate withdrawal to convert Stars into Toncoin directly to your wallet.

2. Interactive Simulator: Telegram Stars Invoice & Revenue Yield Calculator

paid

Telegram Stars Invoice & Fee Breakdown

Bot API "XTR" Invoicing & Net TON Conversion Engine

XTR BOT API READY

STARS INVOICE AMOUNT

USER PURCHASE CHANNEL

PAYOUT WITHDRAWAL DESTINATION

User Price (USD)

$5.00

Platform Cut

$1.50 (30%)

Developer Net (USD)

$3.25

Estimated Payout

0.625 TON

BOT API sendInvoice JSON REQUEST BODY: CURRENCY: XTR

3. Telegram Stars vs. External Payment Gateways

Evaluating Stars compliance and conversion mechanics against third-party processors:

Payment Dimension	Telegram Stars (XTR)	Legacy Credit Card Webhook
iOS/Android App Compliance	100% Guaranteed; official platform currency	High Risk: Banned by Apple/Google for digital goods
User Checkout Friction	1-Tap native confirmation with Face ID / Touch ID	Requires external browser redirection and manual card typing
Cryptocurrency Cash-Out	Direct Toncoin (TON) withdrawal to private wallets via Fragment	Requires traditional corporate banking accounts and KYC paperwork
Ad Credit Subsidies	0% platform fee when reinvesting into Telegram Ads	Standard 2.9% + $0.30 merchant processing fee with zero ad credit

4. Architectural Overview: Telegram Stars Webhook & Settlement Flow

Telegram Stars In-App Economy Architecture Infographic

Figure 1: Lifecycle of a Telegram Stars transaction from Bot API sendInvoice to Fragment Toncoin settlement.

5. Frequently Asked Questions (FAQ)

Can Telegram Stars be used to sell physical products like t-shirts or coffee?

No. Telegram Stars are strictly designated for digital goods, software licenses, virtual game items, and digital subscriptions. Physical goods can continue using standard third-party payment providers (such as Stripe, PayMe, or YooMoney) supported by BotFather.

How long does a developer have to wait before withdrawing Stars into Toncoin?

Telegram applies a 21-day holding period from the moment Stars are received by your bot. This buffer protects developers and the platform against consumer credit card chargebacks and fraudulent app store disputes before on-chain Toncoin conversion executes.

Can bot developers issue partial or full refunds in Stars?

Yes. The Bot API provides the refundStarPayment method. Developers pass the original user ID and telegram_payment_charge_id to immediately return Stars to the consumer's Telegram balance without incurring financial penalty fees.