Building on TON in 2026: Crypto Payments in Telegram Mini Apps with TON Pay SDK

The TON Ecosystem in 2026

The Open Network (TON) has evolved from a blockchain project with Telegram roots into one of the most actively used cryptocurrency ecosystems in the world. As of March 2026, the numbers tell a compelling story:

• 500M+ monthly active users across Telegram Mini Apps
• 3,600+ live Mini Apps listed in the Telegram Mini App catalog
• 400M+ TON wallets created through Telegram Wallet, Tonkeeper, and TON Space
• $4.2B total value locked in TON DeFi protocols
• 12M daily on-chain transactions on the TON mainnet

These figures make TON the most widely distributed blockchain by active user count, surpassing Ethereum (including L2s) and Solana. The growth is driven by a single factor: Telegram integration. With 950M+ monthly active Telegram users worldwide, even a small conversion rate into Mini App and wallet usage produces massive numbers.

Why TON for Payments?

For developers building payment-enabled applications, TON offers three structural advantages over other blockchains:

1. Distribution — Your Mini App is discoverable inside Telegram, the messaging platform your users already use daily. No app store submission, no download friction, no wallet installation required.
2. Near-zero fees — TON transaction fees average $0.005-0.01, making micropayments and in-app purchases economically viable without batching or L2 complexity.
3. Sub-second finality — TON’s sharded architecture achieves block times of ~5 seconds with practical finality in 1-2 blocks. Users see confirmed payments within 10 seconds.

TON Pay SDK: Architecture Overview

TON Pay SDK is the official payment integration library for Telegram Mini Apps. Released in Q4 2025, it provides a unified API for:

• TON Connect wallet authentication
• Toncoin payments (native TON transfers)
• Jetton payments (TRC-20 token standard — USDT, NOT, and custom tokens)
• Subscription billing (recurring Jetton charges via pre-authorized smart contracts)
• Payment receipts (on-chain proof of payment with metadata)

The SDK is available as an npm package (@tonconnect/pay-sdk) and supports both client-side (browser) and server-side (Node.js) usage.

Prerequisites

Before integrating TON Pay SDK, ensure you have:

1. A registered Telegram Bot with Mini App capabilities (@BotFather → /newapp)
2. A TON wallet address for receiving payments (merchant wallet)
3. Node.js 20+ and TypeScript 5.x for the development environment
4. Basic familiarity with the Telegram Mini App API (window.Telegram.WebApp)

Step 1: TON Connect Wallet Authentication

TON Connect is the standard protocol for connecting TON wallets to dApps and Mini Apps. It serves as the authentication layer — before accepting payments, you need to know which wallet the user wants to pay from.

Setting Up TON Connect

import { TonConnect } from "@tonconnect/sdk";
import { TonPaySDK } from "@tonconnect/pay-sdk";

// Initialize TON Connect with your manifest
const tonConnect = new TonConnect({
  manifestUrl: "https://yourapp.com/tonconnect-manifest.json",
});

// The manifest describes your Mini App to wallets
// Host this JSON at your domain:
// {
//   "url": "https://yourapp.com",
//   "name": "Your Mini App",
//   "iconUrl": "https://yourapp.com/icon.png"
// }

// Check if user has a previously connected wallet
const existingWallet = tonConnect.wallet;
if (existingWallet) {
  console.log("Connected:", existingWallet.account.address);
}

Wallet Connection Flow

The wallet connection flow differs depending on the user’s wallet provider:

import { toUserFriendlyAddress } from "@tonconnect/sdk";

async function connectWallet(): Promise<string> {
  // Generate connection URL for external wallets (Tonkeeper, etc.)
  const walletList = await tonConnect.getWallets();

  // For Telegram Mini Apps, prioritize TON Space (built-in)
  const tonSpace = walletList.find(
    (w) => w.appName === "tonspace"
  );

  if (tonSpace) {
    // TON Space opens natively inside Telegram — no redirect
    await tonConnect.connect({
      jsBridgeKey: tonSpace.jsBridgeKey,
    });
  } else {
    // Fallback to universal link (opens Tonkeeper/MyTonWallet)
    const universalLink = tonConnect.connect({
      universalLink: walletList[0].universalLink,
      bridgeUrl: walletList[0].bridgeUrl,
    });
    // Display QR code or redirect
    window.open(universalLink, "_blank");
  }

  // Wait for connection confirmation
  return new Promise((resolve) => {
    tonConnect.onStatusChange((wallet) => {
      if (wallet) {
        const address = toUserFriendlyAddress(
          wallet.account.address
        );
        resolve(address);
      }
    });
  });
}

Session Persistence

TON Connect sessions persist across Mini App restarts. The SDK stores session data in localStorage. On subsequent launches, check for an existing connection before prompting the user:

async function initAuth(): Promise<string | null> {
  await tonConnect.restoreConnection();
  if (tonConnect.connected && tonConnect.wallet) {
    return toUserFriendlyAddress(
      tonConnect.wallet.account.address
    );
  }
  return null;
}

Step 2: Accepting Toncoin Payments

Once the wallet is connected, you can request native TON transfers using the TON Pay SDK.

Simple Payment Request

import { TonPaySDK, PaymentRequest } from "@tonconnect/pay-sdk";

const tonPay = new TonPaySDK({
  tonConnect,
  merchantWallet: "EQD...your-merchant-address",
  // Optional: webhook URL for server-side confirmation
  webhookUrl: "https://yourapi.com/webhooks/ton-pay",
});

async function requestPayment(
  amount: number,
  orderId: string
): Promise<string> {
  const payment: PaymentRequest = {
    amount: amount.toString(), // Amount in TON (e.g., "1.5")
    payload: orderId,          // Stored in the transaction comment
    description: `Order #${orderId}`,
  };

  // This opens the wallet confirmation screen
  const result = await tonPay.requestPayment(payment);

  if (result.status === "confirmed") {
    // Transaction confirmed on-chain
    return result.txHash;
  } else if (result.status === "rejected") {
    throw new Error("Payment rejected by user");
  } else {
    throw new Error(`Payment failed: ${result.error}`);
  }
}

Server-Side Payment Verification

Never trust client-side payment confirmations alone. Verify every payment on your backend:

import { TonClient } from "@ton/ton";
import { Address, fromNano } from "@ton/core";

const tonClient = new TonClient({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
  apiKey: process.env.TONCENTER_API_KEY,
});

async function verifyPayment(
  txHash: string,
  expectedAmount: string,
  expectedPayload: string,
  merchantAddress: string
): Promise<boolean> {
  const tx = await tonClient.getTransaction(
    Address.parse(merchantAddress),
    txHash
  );

  if (!tx) return false;

  // Verify amount
  const receivedAmount = fromNano(tx.inMessage?.value ?? 0n);
  if (parseFloat(receivedAmount) < parseFloat(expectedAmount)) {
    return false;
  }

  // Verify payload (order ID in transaction comment)
  const payload = tx.inMessage?.body?.toString() ?? "";
  if (payload !== expectedPayload) {
    return false;
  }

  return true;
}

Step 3: Jetton (Token) Payments

Jettons are the TON equivalent of ERC-20 tokens. The most common Jetton for payments is USDT on TON (Tether), which has over $1.2B in circulation on the TON network as of March 2026.

Requesting Jetton Payments

import { JettonPaymentRequest } from "@tonconnect/pay-sdk";

async function requestUSDTPayment(
  amount: number,
  orderId: string
): Promise<string> {
  const USDT_MASTER = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";

  const payment: JettonPaymentRequest = {
    jettonMaster: USDT_MASTER,
    amount: (amount * 1e6).toString(), // USDT has 6 decimals
    payload: orderId,
    description: `$${amount} USDT — Order #${orderId}`,
    // Forward TON for gas (Jetton transfers require ~0.05 TON)
    forwardTonAmount: "50000000", // 0.05 TON in nanotons
  };

  const result = await tonPay.requestJettonPayment(payment);

  if (result.status === "confirmed") {
    return result.txHash;
  }
  throw new Error(`Jetton payment failed: ${result.error}`);
}

Custom Jetton Integration

If you have your own Jetton (for in-app currency, loyalty points, etc.), the integration is identical — just replace the jettonMaster address:

const MY_TOKEN_MASTER = "EQA...your-jetton-master-contract";

const payment: JettonPaymentRequest = {
  jettonMaster: MY_TOKEN_MASTER,
  amount: "1000000000", // Amount in smallest unit
  payload: "premium-upgrade",
  description: "1000 APP Tokens — Premium Upgrade",
  forwardTonAmount: "50000000",
};

Step 4: Subscription Billing

TON Pay SDK supports recurring payments through pre-authorized subscription contracts. The user approves a maximum charge amount and frequency, and your backend can trigger charges without additional user interaction.

import { SubscriptionRequest } from "@tonconnect/pay-sdk";

async function createSubscription(
  userId: string
): Promise<string> {
  const subscription: SubscriptionRequest = {
    jettonMaster: USDT_MASTER,
    amount: "4990000",          // $4.99 per period
    period: 30 * 24 * 60 * 60,  // 30 days in seconds
    maxCharges: 12,              // Maximum 12 charges (1 year)
    payload: `sub-${userId}`,
    description: "Premium — $4.99/month",
  };

  const result = await tonPay.createSubscription(subscription);

  if (result.status === "active") {
    // Store subscription contract address for future charges
    return result.subscriptionAddress;
  }
  throw new Error("Subscription setup failed");
}

Monetization Strategies for Telegram Mini Apps

Payments are just one piece of the monetization puzzle. Here is how successful Mini Apps combine multiple revenue streams:

1. Telegram Ads Platform

Telegram’s native ad platform allows Mini Apps to display ads and earn revenue in TON. Integration requires registering as a publisher through @AdsBot:

import { TelegramAds } from "@tma.js/ads-sdk";

const ads = new TelegramAds({
  publisherId: "your-publisher-id",
});

// Display a rewarded video ad
async function showRewardedAd(): Promise<boolean> {
  const ad = await ads.loadRewarded();
  if (ad) {
    const result = await ads.showRewarded(ad);
    return result.completed; // User watched the full ad
  }
  return false;
}

Revenue per impression varies by geography, but top Mini Apps report $5-15 eCPM for rewarded video ads in Tier 1 countries.

2. In-App Purchases via Telegram Stars

Telegram Stars is Telegram’s built-in virtual currency, available since 2024. Users purchase Stars with fiat (Apple Pay, Google Pay, credit card) and spend them in Mini Apps. Developers receive 70% of Star revenue.

// Request Stars payment via Telegram WebApp API
function requestStarsPayment(
  title: string,
  amount: number
): void {
  window.Telegram.WebApp.openInvoice(
    {
      title,
      description: `${amount} Stars purchase`,
      payload: JSON.stringify({ item: title }),
      currency: "XTR", // Telegram Stars currency code
      prices: [{ label: title, amount }],
    },
    (status) => {
      if (status === "paid") {
        // Verify on your backend via Bot API
        verifyStarsPayment(title);
      }
    }
  );
}

3. Crypto-Native Monetization

Combine TON Pay SDK payments with DeFi mechanics:

• Token-gated access — require holding a specific Jetton or SBT (Soulbound Token) to access premium features
• NFT marketplace — sell digital collectibles (TON NFTs use the TEP-62 standard)
• Staking rewards — let users stake TON or Jettons in your Mini App’s smart contract for yield
• Referral commissions — pay referral bonuses in Jettons via smart contracts

Revenue Model Comparison

Model	Payment Method	Developer Share	User Friction	Best For
Telegram Ads	Ad impressions	50-70% of ad revenue	Low (passive)	Free apps with high DAU
Telegram Stars	Fiat → Stars	70%	Medium (in-app purchase)	Digital goods, casual games
TON Pay (Toncoin)	Crypto wallet	100% (minus gas)	Higher (wallet required)	Crypto-native users
TON Pay (USDT)	Crypto wallet	100% (minus gas)	Higher (wallet required)	Stable-value transactions
Subscriptions	Crypto wallet	100% (minus gas)	Medium (one-time approval)	SaaS, premium content

Production Deployment Checklist

Before launching your payment-enabled Mini App:

1. Merchant wallet security — use a multisig wallet (e.g., TON Safe) for receiving payments. Never use a single-key hot wallet for merchant funds.
2. Payment verification — always verify payments server-side. Check amount, payload, and sender address.
3. Error handling — handle network timeouts, rejected transactions, and insufficient balance gracefully. Show clear error messages to users.
4. Refund policy — implement a refund mechanism. TON transactions are irreversible, so refunds require a separate outgoing transaction.
5. Rate limiting — protect your payment webhook endpoint from abuse. Validate webhook signatures.
6. Logging — log all payment events with transaction hashes for dispute resolution.
7. Testing — use TON testnet for development. TON Pay SDK supports testnet mode via a configuration flag.

Frequently Asked Questions

How many users can TON Mini Apps reach?

Telegram has 950M+ monthly active users. Mini Apps are accessible to all of them without installing anything. The top Mini Apps (Notcoin, Hamster Kombat) have reached 30-40M users. The realistic addressable market for a well-distributed Mini App is 1-10M users.

What are the transaction fees for TON payments?

Native TON transfers cost approximately 0.005-0.01 TON (0.01-0.02 at current prices). Jetton transfers cost slightly more due to the additional smart contract execution, typically 0.03-0.05 TON (0.06-0.10). These fees are paid by the sender, not the merchant.

Can I accept fiat payments in a Telegram Mini App?

Yes, through Telegram Stars (built-in) or third-party payment providers. Telegram Stars uses Telegram’s native payment infrastructure with Apple Pay, Google Pay, and credit card support. For direct fiat processing, you can integrate Stripe or other providers, but Telegram’s terms require using their Bot Payments API.

Is KYC required for accepting TON payments?

For the merchant: it depends on your jurisdiction and transaction volume. Most countries require money transmitter or payment processor licensing above certain thresholds. For users: TON wallet creation does not require KYC, but centralized exchanges where users buy TON do enforce KYC.

What is the difference between TON and Ethereum for payments?

TON offers lower fees ($0.01 vs $0.50-5.00 on Ethereum L1), faster finality (10 seconds vs 12-15 minutes for strong finality on Ethereum), and built-in Telegram distribution. Ethereum has a larger DeFi ecosystem, more institutional adoption, and stronger decentralization guarantees. For consumer-facing payment applications, TON’s Telegram integration is a decisive advantage.

How do I handle disputes and chargebacks?

Blockchain payments are irreversible — there are no chargebacks. You must implement your own refund and dispute resolution system. Best practice: hold funds in an escrow smart contract for a dispute period (24-72 hours) before releasing to your merchant wallet.