How to build a transfer

Use this server-side helper to generate a canonical TON message payload and a tracking reference.

import { createTonPayTransfer } from "@ton-pay/api";

const { message, bodyBase64Hash, reference } = await createTonPayTransfer(
  {
    amount: 10.5,
    asset: "TON",
    recipientAddr: "<RECIPIENT_ADDRESS>",
    senderAddr: "<SENDER_ADDRESS>",
    commentToSender: "Payment for Order #1234",
    commentToRecipient: "Order #1234",
  },
  {
    chain: "testnet",
    apiKey: "<TONPAY_API_KEY>", // optional
  }
);

Function signature

createTonPayTransfer(
  params: CreateTonPayTransferParams,
  options?: APIOptions
): Promise<CreateTonPayTransferResponse>

Transfer parameters

type CreateTonPayTransferParams = {
  amount: number;
  asset: string;
  recipientAddr?: string;
  senderAddr: string;
  queryId?: number;
  commentToSender?: string;
  commentToRecipient?: string;
};

API options

type APIOptions = {
  chain?: "mainnet" | "testnet";
  apiKey?: string; // optional
};

chain · string · default: "mainnet"

Target blockchain network. Use "mainnet" for production or "testnet" for development and testing.

apiKey · string

The optional TON Pay API key from the Merchant Dashboard. When provided, it enables:

• Transaction visibility in the TON Pay Merchant Dashboard.
• Webhook notifications for completed transactions.
• Receiving wallet management from the Merchant Dashboard.

Parameter details

amount · number · required

Human-readable payment amount. Decimals are allowed, for example, 10.5 TON.

asset · string · required

Asset to transfer. Use “TON” for Toncoin or a jetton master address or constant, for example, USDT.

recipientAddr · string

Payee wallet address. Optional if an API key is provided. Defaults to the merchant’s default wallet address configured in the Merchant Dashboard.

senderAddr · string · required

Payer wallet address. In UI flows, obtain it from TON Connect.

queryId · number

Jetton only. Numeric identifier embedded into the jetton payload for idempotency and tracking. Ignored for Toncoin payments.

commentToSender · string

Short note visible to the user in the wallet while signing.

commentToRecipient · string

Note visible to the recipient after the transfer is received.

Predefined asset constants

Built-in constants can be used instead of raw addresses.

import { createTonPayTransfer, TON, USDT } from "@ton-pay/api";

// Toncoin transfer
await createTonPayTransfer(
  {
    amount: 1,
    asset: TON, // same as "TON"
    recipientAddr: "<RECIPIENT_ADDRESS>", // shortened example; replace with a full wallet address
    senderAddr: "<SENDER_ADDRESS>",       // shortened example; replace with a full wallet address
  },
  {
    chain: "testnet",
    apiKey: "<TONPAY_API_KEY>", // optional
  }
);

// USDT jetton transfer
await createTonPayTransfer(
  {
    amount: 25,
    asset: USDT, // mainnet USDT jetton master address
    recipientAddr: "<RECIPIENT_ADDRESS>", // shortened example; replace with a full wallet address
    senderAddr: "<SENDER_ADDRESS>",       // shortened example; replace with a full wallet address
  },
  {
    chain: "testnet",
    apiKey: "<TONPAY_API_KEY>", // optional
  }
);

Response:

type CreateTonPayTransferResponse = {
  message: {
    address: string;
    amount: string;
    payload: string;
  };
  bodyBase64Hash: string;
  reference: string;
};

Response fields

message · object · required

Prebuilt TON Connect transaction message. Intended to be passed to sendTransaction as messages: [message].

bodyBase64Hash · string · required

Base64 hash of the signed message body content (payload). Used with getTonPayTransferByBodyHash.

reference · string · required

Tracking reference string. Used with getTonPayTransferByReference.

The SDK call returns a ready-to-send message along with identifiers for subsequent status lookups. Always persist tracking identifiers server-side before sending the transaction to the user.

Optional API key configuration

The TON Pay API key is optional but enables merchant features, including transaction visibility in the dashboard, webhook notifications, and centralized wallet management in the TON Pay Merchant Dashboard.

Obtain an optional API key

1. Open the Merchant Dashboard

   Open the TON Pay Merchant Dashboard and sign in to the merchant account.

2. Open Developer settings

   Navigate to Developer → API Keys sections to set up the optional API key.

3. Generate or copy an optional API key

   Generate a new API key (optional) or copy an existing one and store it securely.

Usage in code

import { createTonPayTransfer } from "@ton-pay/api";

const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
  {
    amount: 10.5,
    asset: "TON",
    // recipientAddr is optional when API key is provided
    // Will use merchant's default wallet from the Merchant Dashboard
    senderAddr: userWalletAddress,
  },
  {
    chain: "testnet",
    apiKey: "<TONPAY_API_KEY>", // optional
  }
);

Optional API key capabilities

Capability	With optional API key	Without API key
Transaction visibility and monitoring	Transfers appear in the TON Pay Merchant Dashboard with status tracking and full transaction history.	Transfers are processed on-chain but are not visible in the Merchant dashboard.
Webhook notifications	Real-time HTTP POST notifications are sent for completed and failed payments.	No webhook notifications; payment status must be obtained through the manual polling.
Receiving wallet management	Receiving wallets are managed from the TON Pay Merchant Dashboard; addresses can be updated without code changes.	Receiving wallet addresses must be hard-coded in the application.
recipientAddr handling	Optional; when omitted, the merchant’s default wallet from the Merchant Dashboard is used automatically.	Required for every transfer.

With optional API key: recipientAddr is optional.

const result = await createTonPayTransfer(
  {
    amount: 10,
    asset: "TON",
    senderAddr: "<SENDER_ADDRESS>",
  },
  {
    chain: "testnet",
    apiKey: "<TONPAY_API_KEY>", // optional
  }
);

Without API key (the API key remains optional): recipientAddr is required.

// Works without API key (it is optional) - transaction processes normally
const result = await createTonPayTransfer(
{
  amount: 10,
  asset: "TON",
  recipientAddr: "<RECIPIENT_ADDRESS>",
  senderAddr: "<SENDER_ADDRESS>",
},
{ chain: "testnet" } // No optional apiKey - transaction works but no dashboard features
);

Testnet configuration

Set up testnet

1. Set chain to testnet

   Configure the chain option to "testnet" in the API calls:

   const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
   {
     amount: 5.0,
     asset: "TON",
     recipientAddr: "<RECIPIENT_ADDRESS>",
     senderAddr: "<SENDER_ADDRESS>",
   },
   {
     chain: "testnet", // Use testnet
     apiKey: "<TONPAY_API_KEY>", // optional
   }
   );
   
2. Use testnet wallet addresses

   Ensure all wallet addresses are valid testnet addresses.

3. Obtain testnet TON

   • Use testnet wallet account: Tonkeeper or other TON wallets.
   • Get testnet TON from a faucet to test transactions.
4. Configure testnet jettons

   If testing with jettons, use the correct testnet jetton master addresses; not mainnet addresses.

   // Example: Testnet USDT (use actual testnet address)
   await createTonPayTransfer(
   {
     amount: 10,
     asset: "<TESTNET_USDT_MASTER_ADDRESS>", // Testnet jetton address
     recipientAddr: "<RECIPIENT_ADDRESS>",
     senderAddr: "<SENDER_ADDRESS>",
   },
   { chain: "testnet" }
   );
   

Configure environment

Use environment variables to switch between mainnet and testnet:

// .env.development
TON_CHAIN=testnet
MERCHANT_WALLET_ADDRESS=EQC...TESTNET_ADDRESS

// .env.production
TON_CHAIN=mainnet
MERCHANT_WALLET_ADDRESS=EQC...MAINNET_ADDRESS

// In the application code
const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
  {
    amount: orderAmount,
    asset: "TON",
    recipientAddr: "<WALLET_ADDRESS>",
    senderAddr: "<CUSTOMER_WALLET_ADDRESS>",
  },
  {
    chain: "testnet",
    apiKey: "<TONPAY_API_KEY>", // optional
  }
);

Verify testnet transactions

Verify testnet transactions using testnet block explorers:

• Testnet Tonviewer
• Testnet Tonscan

// Replace txHash with the actual transaction hash.
// After transaction completes:
console.log(`View on explorer: https://testnet.tonscan.org/tx/${txHash}`);

Apply testing best practices

• Test all payment outcomes on testnet, including success, failures, user rejections, and edge cases.
• Verify webhook endpoint correctly processes testnet webhooks; payload structure matches mainnet.
• Validate behavior across different amounts, including small, large, and fractional values.
• Ensure reference and bodyBase64Hash are persisted and usable for status lookups.
• Exercise error paths such as insufficient balance, invalid addresses, and network issues.