Use the API and UI packages as needed:
// API helpers
import {
createTonPayTransfer,
getTonPayTransferByBodyHash,
getTonPayTransferByReference,
type CompletedTonPayTransferInfo,
type CreateTonPayTransferParams,
type CreateTonPayTransferResponse,
} from "@ton-pay/api";
// React UI
import { TonPayButton, useTonPay } from "@ton-pay/ui-react";
Functions
createTonPayTransfer(params, options?)
Builds a canonical message and returns tracking identifiers.
params — see CreateTonPayTransferParams.options.chain — mainnet | testnet.
getTonPayTransferByBodyHash(bodyHash, options?)
Fetch by Base64 hash of the signed message body content (payload).
getTonPayTransferByReference(reference, options?)
Fetch by reference.
useTonPay(options?)
React hook that connects a wallet (TonConnect) and sends a transaction.
pay(getMessage) — receives senderAddr, asks your factory for { message }, and sends via TonConnect. Resolves { txResult, ...factoryReturn }.
Prebuilt button that encapsulates wallet connect/disconnect UX and invokes handlePay.
Types
CreateTonPayTransferParams
type CreateTonPayTransferParams = {
amount: number;
asset: string;
recipientAddr?: string;
senderAddr: string;
queryId?: number;
commentToSender?: string;
commentToRecipient?: string;
};
CreateTonPayTransferResponse
type CreateTonPayTransferResponse = {
message: { address: string; amount: string; payload: string };
bodyBase64Hash: string;
reference: string;
};
CompletedTonPayTransferInfo
type CompletedTonPayTransferInfo = {
amount: string;
rawAmount: string;
senderAddr: string;
recipientAddr: string;
asset: string;
assetTicker?: string;
status: string;
reference: string;
bodyBase64Hash: string;
txHash: string;
traceId: string;
commentToSender?: string;
commentToRecipient?: string;
date: string;
errorCode?: number;
errorMessage?: string;
};
APIOptions
type APIOptions = {
chain: "mainnet" | "testnet";
};
Constants
import { TON, USDT } from "@ton-pay/api";
// TON: the string constant "TON" (use for TON coin transfers)
// USDT: mainnet USDT jetton master address
Asset constants map to MAINNET addresses and are not affected by the chain
option. For testnet, pass the correct jetton master address explicitly in
asset.
Errors
All API helpers throw Error with an HTTP cause if the network call fails. For example, createTonPayTransfer throws Failed to create TON Pay transfer.
Peer Dependencies
@tonconnect/ui-react- React 18+