Quick start

TON Connect manifest

Before installing and setting up the TON Pay SDK, the application must provide a TON Connect manifest, which is a JSON file that defines application metadata. Wallets use this manifest to discover the application.

First payment

1. Install necessary libraries

   React

   # API
   npm i @ton-pay/api
   
   # UI (install separately from API)
   npm i @ton-pay/ui-react @tonconnect/ui-react
   

   Vanilla JS

   # API
   npm i @ton-pay/api
   
   # UI (install separately from API)
   npm i @ton-pay/ui @tonconnect/ui
   
2. Add TON Connect provider

   TON Pay UI uses TON Connect UI for wallet communication.

   The application must be wrapped with TonConnectUIProvider and configured with an absolute URL to the TON Connect manifest. Add TonConnectUIProvider at the root of the application.

   import { TonConnectUIProvider } from '@tonconnect/ui-react';
   import AppContent from "./AppContent";
   
   export default function App() {
     return (
       <TonConnectUIProvider
         manifestUrl="https://myapp.com/tonconnect-manifest.json">
         <AppContent />
       </TonConnectUIProvider>
     );
   }
   
3. Add a payment button

   Add a TonPayButton and provide a handler. The handler uses useTonPay to connect a wallet if needed, send a transaction through TON Connect, and track the transaction result.

   • TonPayButton wraps wallet connect and disconnect UX and invokes the provided handler.
   • useTonPay accepts an async message factory that receives senderAddr and returns { message } along with any tracking fields to propagate.

   The returned { message } is a TON Connect transaction message. useTonPay forwards it to the wallet through TON Connect and initiates the transaction send; direct calls to the wallet SDK are not required.

   import { TonPayButton, useTonPay } from "@ton-pay/ui-react";
   import { useTonConnectUI } from "@tonconnect/ui-react";
   import { createTonPayTransfer } from "@ton-pay/api";
   
   export default function PayButton() {
     const { pay } = useTonPay();
     const [tonConnectUI] = useTonConnectUI();
   
     async function createMessage(senderAddr: string) {
       const { message, reference } = await createTonPayTransfer(
         {
           amount: 12.34,
           asset: "TON",
           recipientAddr: "<WALLET_ADDRESS>",
           senderAddr,
           commentToSender: "<THE_ORDER>",
         },
         {
           chain: "testnet", // use "mainnet" for production
           apiKey: "<TONPAY_API_KEY>" // optional
         }
       );
       return { message, reference };
     }
   
     return (
       <TonPayButton handlePay={() => pay(createMessage)} />
     );
   }
   

   Minimal server‑side flow quick sample

   // Backend: POST /api/create-payment
   import { createTonPayTransfer } from "@ton-pay/api";
   import { TON } from "@ton-pay/api";
   
   app.post("/api/create-payment", async (req, res) => {
       const { productId, senderAddr } = req.body;
   
       // Use the backend to create an order and calculate the amount using productId price
       const amount = 12.23; // order amount
       const orderId = 1; // ID of a new order
   
       // 1) Create transfer + get tracking identifiers
       const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
           { amount, asset: TON, recipientAddr: "<WALLET_ADDRESS>", senderAddr },
           { chain: "testnet", apiKey: "<TONPAY_API_KEY>" } // API key is optional
       );
   
       // 2) Persist identifiers the DB (orderId, reference, bodyBase64Hash) immediately
   
       // 3) Return only the message to the client
       res.json({ message });
   });
   
   

   // Frontend
   import { TonPayButton, useTonPay } from "@ton-pay/ui-react";
   
   export function PayOrder({ productId }: { productId: any }) {
     const { pay } = useTonPay();
   
     async function createMessage(senderAddr: string) {
       const response = await fetch("/api/create-payment", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ productId, senderAddr }),
       });
       const { message } = await response.json();
       return { message };
     }
   
     return <TonPayButton handlePay={() => pay(createMessage)} />;
   }
   

   Loading state and result handling

   This example shows a minimal loading state and how to surface the reference. If a transaction hash is available, an explorer link can be rendered.

   import { useState } from "react";
   import { TonPayButton, useTonPay } from "@ton-pay/ui-react";
   import { createTonPayTransfer, getTonPayTransferByReference, type CompletedTonPayTransferInfo } from "@ton-pay/api";
   
   export default function Checkout() {
       const { pay } = useTonPay();
       const [loading, setLoading] = useState(false);
       const [reference, setReference] = useState<string | null>(null);
       const [result, setResult] = useState<CompletedTonPayTransferInfo | null>(null);
   
       const options = { chain: "testnet", apiKey: "yourTonPayApiKey" } as const; // API key is optional
   
       async function createMessage(senderAddr: string) {
         const { message, reference } = await createTonPayTransfer(
           { amount: 12.34, asset: "TON", recipientAddr: "EQC...yourWalletAddress", senderAddr },
           options
         );
         setReference(reference);
         return { message, reference };
       }
   
       async function handlePay() {
         setLoading(true);
         try {
           const { reference } = await pay(createMessage);
             // Poll status until success
             for (;;) {
               try {
                 const t = await getTonPayTransferByReference(reference, options);
                 if (t.status === "success") {
                   setResult(t);
                   break;
                 }
               } catch {}
               await new Promise(r => setTimeout(r, 1000));
             }
         } finally {
           setLoading(false);
         }
       }
   
       return (
         <>
           <TonPayButton handlePay={handlePay} isLoading={loading} />
   
           {reference && !result && <div>Payment sent. Reference: {reference}</div>}
           {result && <div>Payment successful! Tx hash: {result.txHash}</div>}
           {/* If a transaction hash is available, render an explorer link:
                 <ExplorerLink txHash={result?.txHash!} />
            */}
         </>
       );
   }
   

   import { useTonWallet } from "@tonconnect/ui-react";
   import { CHAIN } from "@tonconnect/ui";
   
   function ExplorerLink({ txHash }: { txHash: string }) {
       const wallet = useTonWallet();
       const isTestnet = wallet?.account?.chain === CHAIN.TESTNET;
       const tonviewer = isTestnet
           ? `https://testnet.tonviewer.com/transaction/${txHash}`
           : `https://tonviewer.com/transaction/${txHash}`;
       const tonscan = isTestnet
           ? `https://testnet.tonscan.org/tx/${txHash}`
           : `https://tonscan.org/tx/${txHash}`;
   
       return (
           <div>
               <a href={tonviewer} target="_blank" rel="noreferrer">TonViewer</a>
               {" • "}
               <a href={tonscan} target="_blank" rel="noreferrer">Tonscan</a>
           </div>
       );
   }
   

Full example

This minimal example scaffolds a React app, installs TON Pay dependencies, and renders a working button wired to TON Connect. Replace the manifest URL and recipientAddr with the necessary values.

npx create-react-app my-app --template typescript
cd my-app
npm i @ton-pay/api @ton-pay/ui-react @tonconnect/ui-react

// src/App.tsx
import { TonConnectUIProvider } from "@tonconnect/ui-react";
import { TonPayButton, useTonPay } from "@ton-pay/ui-react";
import { createTonPayTransfer } from "@ton-pay/api";

function AppContent() {
    const { pay } = useTonPay();

    async function createMessage(senderAddr: string) {
        const { message, reference } = await createTonPayTransfer(
            {
                amount: 12.34,
                asset: "TON",
                recipientAddr: "<WALLET_ADDRESS>",
                senderAddr,
                commentToSender: "Order #123",
            },
            {
                chain: "testnet",
                apiKey: "<TONPAY_API_KEY>" // optional
            }
        );
        return { message, reference };
    }

    return (
        <TonPayButton handlePay={() => pay(createMessage)} />
    );
}

export default function App() {
    return (
        <TonConnectUIProvider
          manifestUrl="https://ton-connect.github.io/demo-dapp-with-wallet/tonconnect-manifest.json"
        >
          <AppContent />
        </TonConnectUIProvider>
    );
}

See also

• Build a transfer
• Send payments using React
• Webhooks
• API reference