Telegram Stars Bot API Guide: sendInvoice, XTR, Webhooks, Subscriptions and Refunds

Prerequisites

• A bot token from @BotFather. No payment provider needs to be connected for Stars.
• A server (or serverless function) able to receive updates via webhook or long polling.
• Any Bot API library: python-telegram-bot, aiogram, grammY, Telegraf, node-telegram-bot-api, or raw HTTP calls.

1. Create a Stars invoice

Two methods create invoices. sendInvoice posts the invoice into a chat; createInvoiceLink returns a URL you can share anywhere or open from a Mini App. The parameters that matter for Stars:

Example: createInvoiceLink with raw HTTP

POST https://api.telegram.org/bot<TOKEN>/createInvoiceLink
Content-Type: application/json

{
  "title": "Premium Access",
  "description": "30 days of premium content",
  "payload": "order_7f3a9c",
  "currency": "XTR",
  "prices": [{ "label": "Premium Access", "amount": 250 }]
}

Example: sendInvoice with python-telegram-bot

from telegram import LabeledPrice

await context.bot.send_invoice(
    chat_id=update.effective_chat.id,
    title="Premium Access",
    description="30 days of premium content",
    payload="order_7f3a9c",
    provider_token="",          # empty for Telegram Stars
    currency="XTR",
    prices=[LabeledPrice("Premium Access", 250)],
)

Example: createInvoiceLink with grammY (Node.js)

const link = await bot.api.createInvoiceLink(
  "Premium Access",
  "30 days of premium content",
  "order_7f3a9c",
  "",            // provider_token: empty for Stars
  "XTR",
  [{ label: "Premium Access", amount: 250 }],
);
// share `link` or open it from a Mini App

2. Answer the pre-checkout query

When the user taps Pay, Telegram sends your bot an update containing pre_checkout_query. This is your last chance to validate the order (stock, user eligibility, payload integrity). You must reply within 10 seconds:

@router.pre_checkout_query()
async def on_pre_checkout(q: PreCheckoutQuery):
    if not order_exists(q.invoice_payload):
        await q.answer(ok=False, error_message="Order not found")
        return
    await q.answer(ok=True)

3. Handle successful_payment

After a successful charge Telegram sends a service message with the successful_payment field. Key fields:

• currency ("XTR") and total_amount (Stars).
• invoice_payload: your order ID.
• telegram_payment_charge_id: store this; it identifies the transaction for refunds and reconciliation.
• is_recurring, is_first_recurring, subscription_expiration_date for subscriptions.

bot.on("message:successful_payment", async (ctx) => {
  const sp = ctx.message.successful_payment;
  await db.orders.markPaid(sp.invoice_payload, {
    chargeId: sp.telegram_payment_charge_id,
    stars: sp.total_amount,
    userId: ctx.from.id,
  });
  await deliverProduct(ctx.from.id, sp.invoice_payload);
});

Make the handler idempotent: Telegram may redeliver updates, so check whether the order is already fulfilled before delivering twice.

4. Stars subscriptions

Recurring billing is built in. Pass subscription_period to createInvoiceLink; the only supported value is 2592000 seconds (30 days). Telegram charges the user automatically each period and sends a new successful_payment with is_recurring=true. Use editUserStarSubscription to cancel or re-enable a subscription on the user's behalf. Users can also manage subscriptions from their Telegram settings.

const link = await bot.api.createInvoiceLink(
  "Premium Monthly",
  "Renews every 30 days",
  "sub_user_42",
  "",
  "XTR",
  [{ label: "Premium Monthly", amount: 150 }],
  { subscription_period: 2592000 },
);

5. Refunds

Refund any Stars payment with refundStarPayment(user_id, telegram_payment_charge_id). The Stars return to the user and the transaction is reversed in your Stars balance. Refunds are possible even after delivery, so define a clear policy.

await bot.api.refundStarPayment(userId, chargeId);

6. Reconciliation with getStarTransactions

getStarTransactions(offset, limit) returns the bot's incoming and outgoing Stars transactions (payments, refunds, withdrawals). Run it periodically and compare it with your database; discrepancies usually mean a missed update. getMyStarBalance returns the current Stars balance of the bot.

7. Stars payments from a Mini App

In a Mini App, request an invoice link from your backend, then open it from the front end:

const url = await fetch("/api/invoice", { method: "POST" }).then(r => r.json());
window.Telegram.WebApp.openInvoice(url, (status) => {
  if (status === "paid") showSuccess();
  else if (status === "cancelled") showCancelled();
  else showFailed();
});

The successful_payment update still arrives at your bot; treat it as the source of truth, not the client callback.

8. Withdrawing the Stars your bot earns

Stars accumulate in the bot's balance and become withdrawable after 21 days. Withdraw to TON through Fragment (minimum 1,000 Stars) or spend them on Telegram Ads. See How to withdraw Telegram Stars to TON.

Common pitfalls

• Non-empty provider_token with XTR → Bad Request. Leave it empty.
• Multiple price items → rejected. Stars invoices accept exactly one LabeledPrice.
• Slow pre-checkout handler → payment fails after 10 seconds. Validate locally.
• Not storing telegram_payment_charge_id → you cannot refund later.
• Trusting the Mini App callback instead of the successful_payment update → fraud risk.
• Non-idempotent delivery → duplicate fulfilment on redelivered updates.

Build or buy?

The Bot API gives you full control, but a production-grade Stars business also needs a ledger, maturity tracking, payout management, refunds UI, analytics and multi-user support. Telegram Stars Payment Platform provides all of this out of the box, with a REST API (create invoices, list payments, request withdrawals) and webhooks for payment events, for a flat 3% fee. Many developers use it as their payment back office while keeping their own bot for the user-facing experience. See how it works.