How to Accept Stars Payments in Your Mini App — Developer Guide

Why Accept Stars in Your Mini App?

Telegram Stars have become the native payment currency of the Telegram ecosystem. With millions of users holding Stars and growing demand for Mini App features, accepting Stars opens your application to a massive, ready-to-pay audience. Unlike traditional payment gateways, Stars payments are instant, require no bank account setup, and work across all regions where Telegram operates.

Prerequisites

Before integrating Stars payments, ensure you have:

• A Telegram bot — created via @BotFather with an active API token
• A Mini App — your web application configured to run inside Telegram
• Bot owner account with Stars balance — your bot must be able to receive Stars from users
• Telegram Premium or sufficient Stars — for testing your payment flow

Step 1: Enable Payments on Your Bot

Open a conversation with @BotFather and send the /setpayments command. BotFather will guide you through enabling the Stars payment system for your bot. You'll need to:

• Confirm that your bot will accept Stars payments
• Set your bot's Stars wallet address — this is where received Stars will be deposited
• Review and accept Telegram's payment terms and conditions

Once enabled, your bot can receive Stars from users who interact with your Mini App.

Step 2: Integrate the Telegram Payment API

Telegram provides a JavaScript SDK for Mini Apps that includes payment functionality. Include the SDK in your Mini App:

<script src="https://telegram.org/js/telegram-web-app.js"></script>

The SDK exposes the Telegram.WebApp object with payment-related methods. The key method for initiating a Stars payment is:

Telegram.WebApp.requestPriceConfirmation(price, description, callback)

Payment Flow

1. User initiates purchase — they click a "Buy" button in your Mini App
2. Your app calls requestPriceConfirmation() — passing the Stars amount and description
3. Telegram shows a confirmation dialog — the user reviews the purchase and confirms
4. Stars are transferred to your bot — Telegram handles the transaction on the TON blockchain
5. Your callback receives the result — success or failure with transaction details

Step 3: Define Your Pricing Strategy

Setting the right price in Stars is crucial for conversion. Consider these factors:

Understanding Star Value

• Official purchase rate: users pay approximately $0.028-0.050 per Star
• Perceived value: users think of Stars as "points" rather than dollars, so round numbers (10, 25, 50, 100) convert better
• Psychological pricing: 49 Stars feels significantly cheaper than 50 Stars, even though the difference is negligible

Common Pricing Tiers

Successful Mini Apps typically offer multiple tiers:

• Micro-purchases (5-25 Stars): single features, one-time unlocks, cosmetic items
• Standard purchases (25-100 Stars): premium features, content packs, ad removal
• Subscriptions (100-500 Stars/month): recurring access to premium features
• Premium tiers (500+ Stars): full feature access, VIP status, exclusive content

Tip: Start with lower prices to build your user base and revenue history, then gradually increase as demand proves your value.

Step 4: Handle Payment Confirmation Server-Side

Never trust client-side payment confirmation alone. Implement server-side verification:

1. When a user completes a purchase, your Mini App sends the transaction data to your backend
2. Your backend verifies the transaction using the Telegram Bot API
3. Upon successful verification, grant the user their purchased features
4. Log the transaction for revenue tracking and analytics

This prevents users from manipulating the client-side callback to get features without paying.

Step 5: Convert Stars Revenue to USDT

As a developer, you'll accumulate Stars in your bot's wallet. To convert this revenue to usable funds:

Option A: Fragment.com (Official)

Fragment is Telegram's official platform for creator monetization:

• Commission: approximately 30%
• Minimum withdrawal: 1,000 Stars
• Payout: USDT on the TON blockchain
• Process: connect your bot to Fragment, request withdrawal, receive USDT

Option B: Third-Party Exchange Services

Services like Flash Swap (@flash_swap_bot) offer Stars-to-USDT exchange with:

• Commission: approximately 30%
• Minimum threshold: as low as 5 Stars
• Automation: fully automated exchange process
• Speed: USDT delivered to your TON wallet within minutes

Recommendation: For small and medium Mini Apps, third-party services offer lower minimums and faster processing. For large-scale operations, Fragment provides the official channel with potentially better rates at volume.

Step 6: Implement Recurring Payments (Subscriptions)

Telegram supports recurring Stars payments for subscription-based Mini Apps. The implementation differs slightly from one-time purchases:

• Set up a subscription plan with a defined billing period (weekly, monthly, yearly)
• Users authorize recurring payments — Telegram handles the automatic deduction
• You receive Stars automatically at each billing cycle
• Users can cancel anytime through Telegram settings

Subscriptions provide predictable, recurring revenue — the most valuable revenue model for Mini App sustainability.

Best Practices for Stars Monetization

1. Free Tier First

Offer a compelling free tier that demonstrates your Mini App's value. Users who experience the free features are significantly more likely to upgrade to paid features. The freemium model is the most proven approach in the Telegram ecosystem.

2. Clear Value Communication

When presenting a Stars purchase, clearly explain what the user gets. Use screenshots, feature lists, or demo content. Users are more likely to spend Stars when they understand the value.

3. Progressive Disclosure

Reveal premium features gradually. Let users discover paid features through the free experience rather than presenting a paywall immediately. This builds desire and increases conversion rates.

4. Social Proof

Show how many users have purchased, ratings, or testimonials. Social proof significantly increases trust and willingness to pay.

5. Referral Incentives

Offer Stars or premium features to users who refer new customers. This leverages Telegram's native sharing capabilities and creates organic growth.

6. Regular Updates and New Content

Keep your Mini App fresh with regular updates, new features, and seasonal content. Active development signals to users that their Stars investment is safe and will continue to be supported.

Technical Considerations

Error Handling

Implement robust error handling for payment failures:

• Insufficient Stars balance — prompt the user to acquire more Stars
• Network errors — retry the transaction with a clear error message
• Bot configuration issues — ensure your bot is properly configured for payments

Cross-Platform Compatibility

Test your payment flow on both iOS and Android Telegram clients. The payment UI may render slightly differently on each platform.

Localization

Display prices and descriptions in the user's language. Telegram provides the user's language code via the SDK — use it to localize your payment screens.

Revenue Tracking and Analytics

Track these key metrics to optimize your Stars revenue:

• Conversion rate: percentage of users who make at least one purchase
• Average revenue per paying user (ARPPU): total Stars revenue divided by number of paying users
• Churn rate: for subscriptions, the percentage of users who cancel each period
• Revenue per Star: after conversion to USDT, track your effective revenue per Star received

Use these metrics to adjust pricing, feature bundles, and marketing strategies.

Common Mistakes to Avoid

• ❌ Overpricing: Stars feel expensive to users accustomed to free Mini Apps. Start conservative and increase based on data.
• ❌ Paywalling everything: if users can't experience any value for free, they won't pay. Always offer a meaningful free tier.
• ❌ Ignoring server-side verification: client-side confirmation alone is not secure. Always verify transactions on your backend.
• ❌ Not providing receipts: users should receive confirmation of their purchase. Include transaction details and what they received.
• ❌ Forgetting about the 30% commission: factor Telegram's commission into your pricing strategy. If you want $10 in USDT, you need to earn approximately $14.30 worth of Stars.

Conclusion

Accepting Stars payments in your Mini App is one of the most effective monetization strategies in the Telegram ecosystem. The combination of instant transactions, no bank account requirements, and access to millions of Star-holding users makes Stars an ideal payment method. Start with a clear pricing strategy, implement proper server-side verification, and focus on delivering value that users are willing to pay for. As your Mini App grows, you can expand your monetization strategy with subscriptions, tiered features, and referral programs.