An artist who teaches watercolour is launching a bot: access to a video lesson costs a small amount. The first thought is to connect card payments, since buyers are used to them. But a video lesson is a digital good, and for digital goods Telegram has one rule: Stars only.

With Telegram bots, the question of how to take money is not settled by comparing fees. First decide what you are selling, and the rules will point to the method. A mistake here can cost the bot itself.

21 days
After this long, Stars a bot earns become available for rewards or advertising.
10 seconds
How long a bot has to confirm an order before payment.
0 %
Telegram's fee for card payments through a provider. The provider charges its own.

Where to start

The main rule: the type of product

  • Digital — access to lessons, a subscription, files, bot features, in-game items. Telegram Stars only. The App Store and Google Play require it, and Telegram has to follow their rules on digital goods. If a bot accepts other payment methods for digital goods, the owner gets a warning, after which the bot may be made unavailable in the app-store versions of Telegram or shut down.
  • Physical — goods with delivery, services in the real world. Payment by card through a third-party payment provider, in ordinary currency.
  • Crypto. If a mini app works with crypto, it must be the TON network only, and wallets connect only through TON Connect. Digital goods are still sold for Stars.

Where the line between digital and physical runs is defined by Apple's and Google's rules, and they change. If your product is on the borderline, check their current requirements.

Three rows: digital goods to Stars; physical goods to card payments; crypto to a wallet connection through TON Connect.
Read left to right, rows top to bottom. Digital goods: Stars only. Physical goods: card through a provider. Crypto: TON Connect on TON.

Table

The methods compared

What you sell

How to accept payment

Rules and fees

How you get the money

Digital goods and services

Telegram Stars (currency XTR)

The buyer purchases Stars through the App Store, Google Play or @PremiumBot, and enters no card details in the bot

Stars on the bot's balance. After 21 days they can be exchanged for a reward through Fragment or spent on ads. Valid for 3 years

Physical goods and offline services

A card through a provider connected in BotFather

Telegram takes no fee; the provider takes its own. Amounts roughly from 1 to 10,000 dollars

To your account with the provider, under its rules

Crypto payment

GRAM or TON tokens through TON Connect in a mini app

TON network only. Digital goods still go through Stars

Straight to your TON address. Refunds are manual

How Stars differ from GRAM and why people confuse them is covered in "Telegram Stars vs GRAM: the difference, and why mixing them up costs money".

Digital goods

Stars: what payment looks like in code

The order is the same for any bot:

  1. Send an invoice with the sendInvoice method and the currency XTR. No provider token is needed for Stars.
  2. Confirm the order in reply to pre_checkout_query with answerPreCheckoutQuery within 10 seconds, or the payment is cancelled.
  3. Deliver the goods only after successful_payment. Confirming the order does not yet mean the money has arrived.
  4. Save the telegram_payment_charge_id — without it you cannot issue a refund.

The fragment below continues the bot from "How to create a Telegram bot: BotFather, your first Python code, and one rule about the token": the call function is already there.

# An invoice for a digital poster costing 50 Stars
def send_poster_invoice(chat_id):
    call(
        "sendInvoice",
        chat_id=chat_id,
        title="Digital poster",
        description="High-resolution PNG file",
        payload="poster-001",
        provider_token="",          # left empty for Stars
        currency="XTR",             # Telegram Stars
        prices=[{"label": "Poster", "amount": 50}],
    )


def handle_payment_update(update):
    query = update.get("pre_checkout_query")
    if query:
        # Check that the item is available and answer within 10 seconds
        call("answerPreCheckoutQuery", pre_checkout_query_id=query["id"], ok=True)
        return

    payment = update.get("message", {}).get("successful_payment")
    if payment:
        charge_id = payment["telegram_payment_charge_id"]
        save_charge(charge_id)      # keep it for a possible refund
        deliver_poster(update["message"]["chat"]["id"])


def refund(user_id, charge_id):
    call("refundStarPayment", user_id=user_id, telegram_payment_charge_id=charge_id)

The save_charge and deliver_poster functions are yours: the first records the payment in your database, the second sends the buyer the file.

Platform rules

A seller's duties

  • Support. The bot must respond to the /paysupport command and handle payment questions. It also needs clear terms, for example under /terms, and a way to contact you.
  • Disputes are yours. Telegram does not mediate between seller and buyer. If you cannot fulfil an order, return the Stars with refundStarPayment: the platform rules explicitly allow this without penalty.
  • Consequences. For unresolved legitimate complaints Telegram may debit Stars from the balance, remove the bot from the app-store versions, add a SCAM label and close the owner's account. Stars may also be withheld if a buyer was refunded for buying them through an app store.

Payment providers

Card: physical goods

Card payments are connected in BotFather: /mybots → your bot → the payments section → choose a provider. The provider issues a token that is passed to sendInvoice. While testing, use Stripe's test mode: payments go through without charges, using test cards.

For physical goods a bot can ask for a name, phone, email and delivery address, offer delivery options and tips. Card details go to the provider, not to the bot or to Telegram. So refunds and card disputes are settled with the provider under its rules.

GRAM and tokens

Crypto: TON only

The platform rules for mini apps are strict: anything to do with crypto is TON network only, wallets connect only through TON Connect, and promoting wallets and assets of other networks is not allowed. The buyer confirms the transfer in their own wallet, and the money arrives straight at your address.

This method suits physical goods and services if your buyers already hold GRAM or USDT on TON. Refunds have to be made by hand with an ordinary transfer, and prices in GRAM need recalculating, because the rate moves. How mini apps work is covered in "What are Telegram Mini Apps and how do they work?".

Questions

When can I withdraw the Stars I have earned?

21 days after receiving them. Stars are exchanged for a reward through Fragment; the minimum and the procedure are covered in "How to withdraw Telegram Stars: from channel Stars to GRAM".

Telegram works closely with TON, so can digital goods be sold for GRAM?

No. The digital goods rule covers every payment method other than Stars, crypto included. TON integration allows crypto but does not override the app stores' requirement.

Does Telegram take a fee?

Not for card payments through a provider. With Stars the scheme is different: the buyer pays the app store for Stars, and you receive Stars and exchange them at a rate Telegram sets. A separate 15% fee applies if you enable topics in private chats for the bot.


The product chooses the payment method in a bot. Digital goods go for Stars, physical ones by card through a provider, and crypto only on TON and for buyers who are ready for it. Getting this wrong puts the bot itself at risk.

After that, everything comes down to care in the code: goods are delivered only after a successful payment, the payment ID is saved, and /paysupport works. That is enough for the money to arrive and for disputes not to turn into sanctions.