Telegram Bot Payments and Stars for Developers

Telegram bots take payments through Telegram's built-in payments system. For digital goods and services, Telegram's rules generally require payment in Telegram Stars; for physical goods, bots can use supported third-party payment providers. In both cases the flow is the same shape: your bot sends an invoice, confirms the order when Telegram asks, and delivers once Telegram reports a successful payment.

This guide explains the concepts and the order of events in plain language. It does not replace Telegram's official Bot API documentation, which you should read for exact method names, fields and current rules.

Stars or a payment provider?

The first decision is which kind of payment you need. Telegram's rules here have changed over time, so check the current developer terms before building.

Telegram Stars for digital goods

Telegram Stars are Telegram's own currency. Users buy them inside Telegram and spend them in bots and Mini Apps. For digital goods and services sold in a bot or Mini App, such as premium features, content, in-app items or access, Telegram generally requires Stars.

For developers, Stars have practical advantages:

• No separate payment provider account is needed to accept them.
• The buyer pays with a balance they already hold in Telegram.
• Telegram handles the purchase screen.

For a user-level overview, see Telegram Stars Explained.

Payment providers for physical goods

For physical goods and some services, a bot can connect a supported third-party payment provider through @BotFather. The provider processes the card or other payment, and Telegram passes the result to your bot. Which providers are available depends on region and changes over time, so check BotFather's current options.

How the payment flow works

Whether you use Stars or a provider, the sequence is broadly the same. Here it is in order.

1. You create an order on your side

Before sending anything to the buyer, record the order in your own system. Note what is being bought, the price, the currency and who is buying. Give the order an identifier that only you control.

This record matters. Later, you will check every payment against it.

2. Your bot sends an invoice

Your bot sends an invoice message to the buyer, or creates an invoice link to share or open from a Mini App. The invoice includes a title, a description, the price and a payload.

The payload is a piece of data your bot receives back when the buyer pays. Use it to carry your order identifier and nothing else. Do not put the price or product details in it, because your server should look those up from its own record, not trust what comes back.

3. The buyer taps Pay

Telegram shows its own payment screen. For Stars, the buyer confirms with their Stars balance. For a provider, they enter payment details with the provider. Your bot never sees card numbers.

4. Telegram asks your bot to confirm

Before money moves, Telegram sends your bot a pre-checkout query. This is your one chance to say yes or no before the charge.

Your bot must answer quickly. Telegram allows only a short time, so keep this check fast. If you do not answer in time, the payment fails.

At this step, check:

1. The order identifier in the payload exists in your records.
2. The order is still valid and has not already been paid.
3. The amount and currency match exactly what you recorded.
4. The item is still available.

If anything is wrong, decline with a short, clear reason. Declining here costs the buyer nothing. Declining after payment means a refund.

5. Telegram reports a successful payment

Once the payment goes through, your bot receives a message saying the payment succeeded. It includes a charge identifier from Telegram, and for providers an identifier from the provider too.

Store these identifiers with the order before you do anything else. You need them to issue refunds and to answer support questions.

6. Your bot delivers

Mark the order as paid and deliver what was bought: unlock the feature, send the file, or confirm the shipment. Then tell the buyer what happened.

Making payments reliable

Payments are where small bugs cost real money and trust. A few principles help.

Check again on success

Telegram can deliver the same update more than once. When the successful payment message arrives, check that the order is not already marked as paid before you deliver. Make the "mark as paid" step a single conditional update, so two copies of the same message cannot both succeed.

Trust your own records

The price and product should always come from your database, written before the invoice existed. Treat the payload and any client-side information as a pointer, never as the truth about what was bought.

Do not trust the Mini App callback

If you open an invoice from a Mini App, the app may receive a status when the payment screen closes. That is a user-interface event, not proof of payment. Only the successful payment message to your bot counts. Use the callback to update the screen, for example to show "confirming", and nothing more.

Keep the timing tight

The pre-checkout answer must be fast. Avoid slow database queries, outside calls or heavy work at that step. Do the minimum check needed to say yes or no.

Refunds

Telegram provides a way for bots to refund Stars payments, using the charge identifier from the successful payment. For provider payments, refunds usually go through the provider.

Plan refunds from the start:

1. Store the charge identifier and the buyer's user ID with every order.
2. Decide your refund policy and state it clearly before people pay.
3. Make refunds an explicit action with a log entry, so you know what was refunded and why.
4. If a refund fails, record what is owed and retry, rather than losing track.

Telegram's rules for bots that sell things also expect buyers to be able to get support. Check the current developer terms for what you must provide.

Withdrawing earnings

Developers who earn Stars can convert them under Telegram's current rules, which have involved Fragment and TON. The process, waiting periods and conditions can change, so check Telegram's official information and Fragment before you plan around it.

Nothing in this guide is financial or tax advice. Income from Stars or crypto may be taxable where you live. See Telegram Income Taxes for Creators for general information, and check local rules or a professional.

Accounting tips

• Record Stars as Stars. Do not convert them into another currency in your records using a guessed rate. Keep the actual amounts and convert only when you have a real figure.
• Keep currencies separate. Do not add Stars and money together into one revenue number.
• Log the raw payment information. It helps when a buyer disputes a payment later.

Testing

Telegram offers a test environment for bots and some providers offer test modes. Use them before going live. Test the unhappy paths too: a declined pre-checkout, a duplicate success message, and a refund.

Common mistakes

• Putting the price in the payload. The payload comes back from outside your system. Look up the price from your own records.
• Answering pre-checkout too slowly. The payment fails if your bot does not respond in time.
• Doing all checks after payment. Refusing before payment is free; refusing afterwards needs a refund.
• Delivering twice. Repeat updates happen. Make the paid transition conditional.
• Trusting the Mini App status. Only the successful payment message to your bot proves payment.
• Not storing the charge identifier. Without it, refunds and support become difficult.
• Selling digital goods with a provider where Stars are required. Check Telegram's current rules for your product type.

FAQ

Do I need a payment provider to accept Stars?

No. Stars payments are handled by Telegram. A third-party provider is only needed for payment types that use one, such as physical goods.

Can my bot see the buyer's card details?

No. Card details go to the payment provider. Your bot receives only the payment result and identifiers.

What happens if my bot does not answer the pre-checkout query?

The payment does not go ahead. The buyer is not charged, but they will see a failed payment, so keep that step fast and reliable.

Can I refund a Stars payment?

Yes. Telegram provides a refund method for Stars that uses the charge identifier from the original payment. Store it with every order.

Can a channel owner use Stars too?

Yes. Telegram offers several Stars features for channels as well as bots. See Paid Telegram Channels Explained for an overview.

Is accepting crypto the same as accepting Stars?

No. Stars are Telegram's in-app currency. Crypto payments work differently and carry their own risks and rules.

Summary

Telegram bot payments follow one pattern: record the order, send an invoice with an order identifier in the payload, check everything in the pre-checkout query, then store the charge identifier and deliver once a successful payment arrives. Use Stars for digital goods where Telegram requires it, and a supported provider for physical goods. Trust your own records, guard against duplicate updates, plan refunds early, and keep Stars separate in your accounts. Before building, read Telegram's official documentation and current terms. For bot basics, start with How to Create a Telegram Bot With BotFather.