Payments

TMA.sh supports two payment methods for Telegram Mini Apps: TON Connect for cryptocurrency payments and Telegram Stars for in-app purchases.

Telegram Stars

Telegram Stars is Telegram’s built-in payment system. Users pay with Stars (purchased through Telegram), and you receive payouts via Fragment.

Quick start (recommended)

The SDK’s payments namespace handles everything — invoice creation, payment sheet, and result tracking. No bot token needed client-side:

import { createTMA } from '@tma.sh/sdk';

const tma = createTMA({ projectId: 'my-project' });

// Authenticate first
const { user } = await tma.auth.validate(
  window.Telegram.WebApp.initData,
  'my-project'
);

// One-liner payment
const result = await tma.payments.stars.pay({
  title: 'Premium Subscription',
  description: 'Access premium features for 30 days',
  payload: JSON.stringify({ userId: user.telegramId, plan: 'premium' }),
  prices: [{ label: 'Premium (30 days)', amount: 100 }],
});

if (result.status === 'paid') {
  // Payment successful - update UI
}

The pay() method creates the invoice via the platform (which uses your project’s stored bot token), opens the native Telegram payment sheet, and resolves with the result.

Advanced: server-side invoice creation

If you need more control, use the typed createInvoiceLink() method on TelegramApiClient in your own API routes:

import { createTelegramApiClient } from '@tma.sh/sdk/server';

app.post('/api/create-invoice', async (c) => {
  const telegram = createTelegramApiClient(c.env.BOT_TOKEN);

  const invoiceUrl = await telegram.createInvoiceLink({
    title: 'Premium Subscription',
    description: 'Access premium features for 30 days',
    payload: JSON.stringify({ plan: 'premium' }),
    currency: 'XTR',
    prices: [{ label: 'Premium (30 days)', amount: 100 }],
  });

  return c.json({ invoiceUrl });
});

Handle payment webhooks

After a successful Stars payment, Telegram sends a pre_checkout_query (which you must answer within 10 seconds) and then a successful_payment update. Use the typed answerPreCheckoutQuery() method in your bot handler:

import { defineBot } from '@tma.sh/sdk/bot';

export default defineBot({
  onPreCheckoutQuery: async (ctx) => {
    // Validate the order and confirm
    await ctx.answerPreCheckoutQuery(true);
  },
});

TMA.sh automatically tracks stars_payment analytics events with campaign attribution when payments complete through the bot webhook. Revenue is attributed to the user’s first-touch campaign startParam and shows up in the dashboard’s campaign metrics with ARPU.

TON Connect

TON Connect enables wallet-based cryptocurrency payments directly in the Mini App. TON payments are handled client-side using the @tonconnect/ui package directly — they are not part of the TMA.sh SDK.

Install the package

npm install @tonconnect/ui

Connect a wallet and send a transaction

import { TonConnectUI } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
  manifestUrl: 'https://myapp.tma.sh/tonconnect-manifest.json',
});

// Connect the user's wallet
await tonConnectUI.connectWallet();

// Send a transaction
const transaction = {
  validUntil: Math.floor(Date.now() / 1000) + 600, // 10 minutes
  messages: [
    {
      address: 'UQBx...your-wallet-address',
      amount: '1500000000', // 1.5 TON in nanotons
    },
  ],
};

const result = await tonConnectUI.sendTransaction(transaction);

The amount is specified in nanotons (1 TON = 1,000,000,000 nanotons). You need to host a tonconnect-manifest.json file at your app’s root describing your application.

Verify on the server

For order fulfillment, verify the transaction server-side by querying the TON blockchain directly using a TON API provider (such as TON Center or TON API). This is outside the scope of TMA.sh.

Choosing a payment method

Feature	TON Connect	Telegram Stars
Currency	TON (cryptocurrency)	Stars (in-app currency)
User experience	Wallet approval popup	Native Telegram payment sheet
Server required	Optional (for verification)	Yes (invoice creation)
Payout	Direct to your TON wallet	Via Fragment
Fees	Network gas fees only	Telegram’s standard cut
Best for	Crypto-native users, NFTs	Digital goods, subscriptions

Testing payments

During local development (tma dev), both payment methods work with test networks:

• TON Connect: Use the testnet flag in your TON Connect configuration to connect to TON testnet wallets
• Telegram Stars: Use Telegram’s test environment with test Stars (available via @BotFather in test mode)

See Local Development for setup details.