TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Telegram Stars Payments in a Bot: Invoice to Refund

· 4 min read · 18+ readers

Telegram Stars Payments in a Bot: Invoice to Refund: TSocial guide cover card

Telegram Stars star icon Telegram Stars let a bot sell digital goods and services without a payment provider. The flow has four steps: send an invoice, approve the checkout, record the payment and deliver. This guide shows each step with short examples and covers refunds. Always check core.telegram.org/bots/payments-stars and the Bot API reference for the current rules and field limits, and read Telegram's terms about what may be sold with Stars.

What you can sell

Digital goods and services used inside Telegram, such as access to a channel megaphone icon channel, a digital download or an extra feature. Physical goods follow a different payment system. Telegram's terms limit certain content, and the rules are enforced. See what creators can sell.

Mock Telegram Stars invoice sheet with a product title, description, a price in Stars and a Pay button
A Stars invoice sheet as a buyer sees it. Generic illustration, not a real chat or user data.

Step 1: Send an invoice

Use sendInvoice with currency XTR. For Stars, provider_token is empty or omitted, and prices must contain exactly one item.

{
  "chat_id": 123456789,
  "title": "Weekly guide",
  "description": "A 20 page PDF guide, delivered right after payment.",
  "payload": "order_8841",
  "currency": "XTR",
  "prices": [ { "label": "Guide", "amount": 50 } ]
}
  • amount is a whole number of Stars.
  • payload is a string up to 128 bytes that only you see. Use it to identify the order.
  • The invoice message shows a Pay button.

Check the documentation for optional fields such as photos. For Mini App icon (grid) Mini Apps and link icon links, use createInvoiceLink and open the result with Telegram.WebApp.openInvoice(url, callback).

Step 2: Answer the pre-checkout query

Before charging, Telegram sends a pre_checkout_query update. You must answer within about 10 seconds with answerPreCheckoutQuery:

{ "pre_checkout_query_id": "<id from the update>", "ok": true }

Use this moment to check that the order is valid and still in stock. To refuse, send "ok": false and an error_message that the user will see.

Step 3: Receive successful_payment

After the payment, a message update arrives with a successful_payment field:

{
  "message": {
    "from": { "id": 123456789 },
    "successful_payment": {
      "currency": "XTR",
      "total_amount": 50,
      "invoice_payload": "order_8841",
      "telegram_payment_charge_id": "abc...",
      "provider_payment_charge_id": "..."
    }
  }
}

Save the telegram_payment_charge_id with the order. You need it for refunds and for your records. Make this step idempotent: if the update arrives twice, do not deliver twice. See webhook retries.

Step 4: Deliver

Send the file or grant access, then confirm in chat. Do it only after you have recorded successful_payment. If delivery fails, log it and retry, because the user has already paid.

Refunds

Call refundStarPayment with the buyer's user id and the charge id:

{ "user_id": 123456789, "telegram_payment_charge_id": "abc..." }

On success, the Stars go back to the buyer. Write a refund policy and tell buyers how to ask. See refunds and disputes. Telegram's terms also require that you provide support for purchases, so make a contact available, for example a /support command, and mention it in your bot icon bot's description.

Seeing transactions

The Bot code icon API has getStarTransactions to list Star transactions for the bot. Use it to reconcile your own records. Check the documentation for pagination and fields.

Testing

Use a second account to buy a very small amount. Telegram also has a test environment for some features. Read the documentation before you rely on it for payments. Test failure cases: closing the invoice, a slow pre-checkout answer and a duplicate update.

Security and good practice

  • Never trust the client to say a payment happened. Rely on successful_payment from Telegram.
  • Keep the payload free of secrets.
  • Verify the amount and currency in successful_payment against the order.
  • Handle each charge id once.
  • Keep accounting records for tax. See record keeping.
  • Make the purchase flow clear, with the price and what is included.

Quick checklist

  • Invoice uses currency XTR with a single price item.
  • Payload identifies the order and contains no secrets.
  • pre_checkout_query is answered within about 10 seconds.
  • successful_payment is recorded with telegram_payment_charge_id.
  • Delivery happens once, even if the update repeats.
  • A refund path with refundStarPayment is tested.
  • Support contact and refund policy are visible.
  • Records are kept for accounting and tax.

Edge cases to test

Test what happens when a buyer closes the invoice, pays twice, pays while out of stock, or asks for a refund after delivery. Decide in advance what each case should do and write the answer into your policy. Payment code should be the most carefully tested part of your bot, because mistakes here cost real money and trust.

Frequently asked questions

Do I need a payment provider?

Not for Stars. Other currencies need a provider and its token.

Can I charge more than one item at once?

For Stars invoices, prices holds one item. Use one invoice per product or bundle.

How do I get paid?

Earnings accumulate as Stars subject to Telegram's payout rules. See Stars payouts.

What if the user never completes payment?

Nothing is charged and you receive no successful_payment. Do not deliver.

Related guides

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Telegram Stars Payments in a Bot: Invoice to Refund | TSocial