TON Pay: the SDK for accepting TON payments in 2026

TON Pay is a payment-acceptance SDK published as part of TON Toolset in 2026. It competes with Crypto Pay API and Wallet Pay but with a fundamentally different architecture — non-custodial.

Architecture

[Mini App / web]  →  [TON Pay UI]  →  [User wallet]  →  [Merchant address]
                                                              ↓
                                                       [TON Pay backend]
                                                              ↓
                                                       [Order fulfillment]

vs Crypto Pay:

• Custodial (Crypto Pay): User → Crypto Pay wallet → (merchant requests withdrawal).
• Non-custodial (TON Pay): User → Merchant wallet directly, no intermediary holding funds.

Minimal backend

import { TonPayServer } from '@ton-pay/api';

const server = new TonPayServer({
  merchantAddress: 'EQDxxx...',  // your address
  network: 'mainnet',
});

// Create payment intent
const intent = await server.createIntent({
  amount: '15 TON',
  description: 'Premium subscription',
  orderId: 'order-42',
});
// intent: { id, paymentUrl, expiresAt, paymentMemo }

// When the user pays, webhook fires:
server.on('payment:confirmed', async ({ orderId, txHash, amount }) => {
  await db.markPaid(orderId);
  await sendConfirmation(orderId);
});

Frontend (React)

import { TonPayCheckout } from '@ton-pay/ui-react';

<TonPayCheckout
  intentId="intent-xyz"
  onSuccess={(tx) => navigate(`/orders/${tx.orderId}/confirmation`)}
  onCancel={() => console.log('User cancelled')}
/>

<TonPayCheckout> renders:

• QR code for desktop users.
• Deeplink (ton://transfer/...) for mobile.
• List of supported wallets with logos.
• Status polling — shows “pending”, “confirmed”, “error”.

On-ramp integration

The most valuable feature is the onramp flow. If the user doesn’t have TON:

<TonPayCheckout
  intentId="intent-xyz"
  enableOnramp={true}
  onrampProviders={['mercuryo', 'moonpay']}
/>

Gives the user a “Buy TON by card” button right in checkout — they buy TON from Mercuryo/MoonPay, it lands in their wallet, and they complete the payment — all in 5 minutes. More — fiat on-ramps for TON.

Jetton payments

const usdtIntent = await server.createIntent({
  amount: '50 USDT',
  jetton: 'usdt-jetton',
  orderId: 'order-43',
});

Backend determines the TON price by current rate (via DEX aggregator), builds the right jetton transfer, and validates receipt.

TON Pay vs Crypto Pay vs Wallet Pay

TON Pay is better for:

• Web apps outside Telegram.
• When non-custodial architecture matters (low risk).
• When you want your own backend (data control).

Crypto Pay / Wallet Pay better for:

• Simple TG bots where you don’t want a backend.
• Micro-payments and tipping.

More on alternatives — Crypto Pay vs Wallet comparison and Crypto Pay API guide.

Webhooks and events

server.on('payment:pending', ({ orderId, txHash }) => {
  // Transaction in mempool, waiting for confirmation
});

server.on('payment:confirmed', ({ orderId, txHash, amount }) => {
  // Transaction confirmed, OK to deliver
});

server.on('payment:failed', ({ orderId, reason }) => {
  // Something went wrong — insufficient funds, wrong memo, etc
});

server.on('intent:expired', ({ orderId }) => {
  // Intent expired (e.g., 24 hours without payment)
});

What’s not covered

• Recurring payments / subscriptions — TON Pay (yet) doesn’t natively support on-chain subscriptions. Workaround: your backend generates a new intent each month.
• Refunds — non-custodial, a refund = the merchant sends TON back. SDK has a refund(txHash) helper, but it’s manual.
• Chargebacks — don’t exist in crypto in principle.

What’s next

• Docs: docs.ton.org/ecosystem/ton-pay/overview.
• GitHub: RSquad/ton-pay.
• NPM: @ton-pay/api, @ton-pay/ui-react.

Building checkout in a Mini App or web — TON Pay saves weeks. Simple TG bot for tipping — Crypto Pay is simpler.

Full Toolset context — TON Foundation overview.