API reference

TypeScript exports for the TON Pay SDK packages @ton-pay/api and @ton-pay/ui-react. To install the packages, use:

npm install @ton-pay/api @ton-pay/ui-react

Imports

// 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?)

Build a canonical message and return tracking identifiers.

• params: CreateTonPayTransferParams.
• options: APIOptions.
• options.chain: mainnet | testnet.

getTonPayTransferByBodyHash(bodyHash, options?)

Fetch a transfer by Base64 hash of the signed message body content (payload).

• bodyHash: Base64 hash of the signed message body content (payload). Use bodyBase64Hash from createTonPayTransfer.
• options: APIOptions.
• Return CompletedTonPayTransferInfo.

getTonPayTransferByReference(reference, options?)

Fetch a transfer by reference.

• reference: use the reference returned by createTonPayTransfer.
• options: APIOptions.
• Return CompletedTonPayTransferInfo.

useTonPay(options?)

A React hook. Connect a wallet through TON Connect and send a transaction.

• pay(getMessage): Receive senderAddr, request { message } from the factory, and send through TON Connect. Resolve { txResult, ...factoryReturn }.

TonPayButton

Prebuilt button. Handle wallet connect or disconnect flow and call handlePay.

Types: @ton-pay/api

CreateTonPayTransferParams

Request payload for createTonPayTransfer.

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

Specify amount in asset units. Follow asset decimals. For example: TON 9 decimals, USDT 6 decimals.

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;
};

• status: pending, success, or error;
• errorCode: TON Pay error codes in Check status and retrieve info.

APIOptions

type APIOptions = {
  chain: "mainnet" | "testnet";
};

Constants: @ton-pay/api

import { TON, USDT } from "@ton-pay/api";
// TON: the string constant "TON" (use for Toncoin transfers)
// USDT: mainnet USDT jetton master address

Errors

All API helpers throw Error with an HTTP cause if the network call fails. For example, createTonPayTransfer may throw “Failed to create TON Pay transfer”.

Peer dependencies

• @tonconnect/ui-react – React UI kit for TON Connect SDK.
• React 18 or later and react-dom 18 or later.