# API reference (https://docs-fpm2731fy-ton-core-docs.vercel.app/llms/ecosystem/ton-pay/api-reference/content.md)



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

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

## Imports [#imports]

```ts
// 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 [#functions]

### `createTonPayTransfer(params, options?)` [#createtonpaytransferparams-options]

Build a canonical message and return tracking identifiers.

* `params`: `CreateTonPayTransferParams`.
* `options`: `APIOptions`.
* `options.chain`: `mainnet | testnet`.

### `getTonPayTransferByBodyHash(bodyHash, options?)` [#gettonpaytransferbybodyhashbodyhash-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?)` [#gettonpaytransferbyreferencereference-options]

Fetch a transfer by reference.

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

### `useTonPay(options?)` [#usetonpayoptions]

A React hook. Connect a wallet through [TON Connect](/llms/ecosystem/ton-connect/overview/content.md) and send a transaction.

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

### `TonPayButton` [#tonpaybutton]

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

## Types: `@ton-pay/api` [#types-ton-payapi]

### `CreateTonPayTransferParams` [#createtonpaytransferparams]

Request payload for `createTonPayTransfer`.

```ts
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` [#createtonpaytransferresponse]

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

### `CompletedTonPayTransferInfo` [#completedtonpaytransferinfo]

```ts
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](/llms/ecosystem/ton-pay/payment-integration/status-info/content.md).

### `APIOptions` [#apioptions]

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

<Callout type="note">
  Default: `mainnet`.
</Callout>

## Constants: `@ton-pay/api` [#constants-ton-payapi]

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

<Callout type="danger" title="Mainnet address risk">
  Token constants such as `USDT` always reference mainnet jetton master addresses and are not affected by the `chain` option. Using them on testnet may send transactions to mainnet contracts.

  For testnet, explicitly pass the correct testnet jetton master address instead of using token constants.
</Callout>

## Errors [#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 [#peer-dependencies]

* [`@tonconnect/ui-react`](https://www.npmjs.com/package/@tonconnect/ui-react) – React UI kit for TON Connect SDK.
* [React 18](https://react.dev/) or later and `react-dom` 18 or later.