Accept Telegram Stars Inside a Mini App

The flow that actually gets you paid

1. The Mini App asks your backend for an invoice for a known product ID. Do not trust a price sent by the client.
2. The backend calls createInvoiceLink with currency: "XTR".
3. The Mini App passes that URL to Telegram.WebApp.openInvoice.
4. Telegram shows the native sheet. The user pays or cancels.
5. Your bot receives pre_checkout_query (answer within 10 seconds) and then successful_payment.
6. Only then do you unlock the item, credit the balance, or mark the order paid.

Create the link on the server

Stars invoices use one price line. The amount is the number of Stars, not cents. provider_token stays empty.

const link = await bot.api.createInvoiceLink(
  "Extra lives",
  "5 extra lives in this Mini App",
  orderId,          // payload, 1–128 bytes, your order id
  "",               // provider_token empty for XTR
  "XTR",
  [{ label: "Extra lives", amount: 50 }],
);

Full parameter notes and the pre-checkout handler are in the Bot API guide.

Open it from the Mini App

const invoiceUrl = await fetch("/api/invoice", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ sku: "lives-5" }),
}).then((r) => r.text());

Telegram.WebApp.openInvoice(invoiceUrl, (status) => {
  if (status === "paid") {
    // Optimistic UI only. Confirm with your server.
    pollOrderUntilPaid();
  } else if (status === "cancelled") {
    showIdle();
  } else {
    showFailed();
  }
});

Load telegram-web-app.js before this runs, and call Telegram.WebApp.ready(). The invoice URL is a Telegram link. Do not wrap it in your own domain if you want the native sheet; a redirect is fine only if it ends on that URL without an extra interstitial.

Statuses you will see

Answer pre_checkout_query

If nobody answers within 10 seconds, Telegram fails the payment and the Mini App sees failed. The handler should check that the order exists and the amount matches, then call answerPreCheckoutQuery. Do not call a slow third party from that handler.

When not to build this

Build a Mini App checkout when the purchase is an item inside a game or a tool the user already has open. Do not build one when the product is a link in a channel bio, an ebook, or a private channel. Those are payment links:

• A reusable or single-use link: payment links.
• A file sent after payment: automatic delivery.
• A 30-day channel: subscriptions.

Telegram Stars Payment Platform exposes a REST API and a webhook for the same ledger, 21-day maturity and TON withdrawal, with a 3% fee. Use that when you want the money movement without operating pre_checkout_query yourself.