Telegram Mini-App Star Commerce: WebApp In-Game Purchases, Virtual Goods Invoicing, and Inventory APIs
Build zero-friction digital economies inside Telegram Mini Apps (TMAs). Learn how to create dynamic server-side invoices in Stars (XTR), trigger native client checkout dialogs via openInvoice, handle idempotent fulfillment webhooks, and scale game monetization without traditional card processor chargebacks.
verified Native WebApp Star Checkout Flow
Traditional web payment gateways lose over 60% of impulse buyers at the payment card form. Telegram Stars solves this with native single-tap authorization: when a user clicks "Buy Gem Pack" inside a Mini App, the app calls Telegram.WebApp.openInvoice(). Telegram overlays a native confirmation sheet showing the user's current Star balance and one-click purchase button.
account_tree 1. The 4-Step Star Invoicing Lifecycle
Implementing digital goods purchases in Mini Apps requires secure coordination between your frontend JavaScript, backend game server, and the Telegram Bot API.
1. Server Invoice Creation
Backend calls createInvoiceLink with currency set to XTR, payload token, description, and price array. Never generate invoice links client-side to prevent price tampering.
2. Native WebApp Modal
Frontend invokes Telegram.WebApp.openInvoice(invoiceLink, statusCallback). A smooth native bottom sheet slides up, rendering product metadata and the Stars price tag.
3. Pre-Checkout Verification
Telegram sends a pre_checkout_query update to your webhook. Your server verifies stock availability and responds with answerPreCheckoutQuery(ok=true) within 10 seconds.
4. Idempotent Fulfillment
Upon payment authorization, Telegram fires successful_payment. The server credits in-game diamonds or skins to the player's account and updates the Mini App UI via WebSocket.
code Node.js / TypeScript Server Invoicing Example
// Backend: Create Invoice Link for Stars (XTR)
import { Bot } from "grammy";
const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
app.post("/api/create-star-order", async (req, res) => {
const { userId, itemId } = req.body;
const item = CATALOG[itemId]; // e.g. 500 Gold Coins = 100 Stars
const invoiceLink = await bot.api.createInvoiceLink(
item.title,
item.description,
JSON.stringify({ userId, itemId, nonce: crypto.randomUUID() }),
"", // provider_token is empty string for Telegram Stars!
"XTR",
[{ label: item.title, amount: item.starsPrice }]
);
return res.json({ invoiceLink });
});
Mini-App In-Game Economy & ARPU Simulator
verified_user 2. Zero-Loss Fulfillment & Anti-Tampering Rules
Digital goods delivery in high-velocity games requires defensive engineering against replay attacks and network drops.
Cryptographic Nonces
Embed unique UUID nonces in the invoice invoice_payload. When processing successful_payment, check a Redis atomic set to ensure the token has never been redeemed before.
Double-Confirmation Reconciliation
Do not rely solely on the frontend openInvoice callback. Always listen to server webhooks for authoritative confirmation before issuing scarce in-game assets.
Dynamic Tier Packaging
Offer tiered star bundles with progressive bonuses (e.g. 50 ⭐ Starter Pack vs 1,000 ⭐ Whale Chest) to maximize average transaction size and conversion velocity.
task_alt 3. Production Implementation Checklist
- Zero Provider Token: When billing in Telegram Stars, pass an empty string
""as theprovider_tokenin your Bot API calls. - Currency Code XTR: Always designate
currency: "XTR"to trigger native in-app Stars billing rather than fiat merchant gateways. - Pre-Checkout Timeout: Always respond to
pre_checkout_querywithin 10 seconds or Telegram will automatically abort the transaction and refund the user. - Reconciliation Sync: Maintain a pending transaction state table in your database to automatically detect unfulfilled orders during network interruptions.
One-Page Technical Summary Infographic
Click the poster below to inspect the complete 4-tier TMA commerce architecture: client purchase trigger, backend createInvoiceLink API, pre-checkout validation handshake, and atomic inventory fulfillment.
