feat(ton-pay): update documentation based on TON Pay Widget

docs.json

@@ -232,10 +232,9 @@
               {
                 "group": "Payment integration",
                 "pages": [
-                  "ecosystem/ton-pay/payment-integration/transfer",
                   "ecosystem/ton-pay/payment-integration/payments-react",
-                  "ecosystem/ton-pay/payment-integration/payments-tonconnect",
-                  "ecosystem/ton-pay/payment-integration/status-info"
+                  "ecosystem/ton-pay/payment-integration/payments-server-side",
+                  "ecosystem/ton-pay/payment-integration/migration"
                 ]
               },
               {
@@ -245,7 +244,13 @@
                   "ecosystem/ton-pay/ui-integration/button-js"
                 ]
               },
-              "ecosystem/ton-pay/webhooks",
+              {
+                "group": "Legacy versions",
+                "pages": [
+                  "ecosystem/ton-pay/legacy/overview",
+                  "ecosystem/ton-pay/legacy/react-integration"
+                ]
+              },
               "ecosystem/ton-pay/api-reference"
             ]
           },

ecosystem/ton-pay/api-reference.mdx

@@ -5,66 +5,174 @@ sidebarTitle: "API reference"
 
 import { Aside } from "/snippets/aside.jsx";
 
-TypeScript exports for the TON Pay SDK packages `@ton-pay/api` and `@ton-pay/ui-react`. To install the packages, use:
+TypeScript exports for the current TON Pay packages.
+
+## Install
 
 ```bash
-npm install @ton-pay/api @ton-pay/ui-react
+npm install @ton-pay/ui-react
+```
+
+Install `@ton-pay/api` separately only when server-side helpers are required.
+
+## `@ton-pay/ui-react`
+
+```ts
+import { TonPayWidget } from "@ton-pay/ui-react";
+import type {
+  TonPayWidgetProps,
+  WidgetErrorPayload,
+  WidgetRouteChangedPayload,
+  WidgetSuccessPayload,
+} from "@ton-pay/ui-react";
+```
+
+### `TonPayWidget`
+
+Self-contained React widget button that:
+
+- resolves the TON Pay base URL from `chain`
+- creates and caches widget sessions
+- preloads the hosted iframe
+- maps merchant checkout props into widget intent
+- opens and closes the checkout UI
+- forwards widget lifecycle callbacks
+
+### `TonPayWidgetProps`
+
+```ts
+type TonPayWidgetProps = {
+  amount: number | string;
+  recipientWalletAddress: string;
+  asset?: string;
+  bgColor?: string;
+  borderRadius?: number | string;
+  chain?: "mainnet" | "testnet";
+  className?: string;
+  comment?: string;
+  currency?: string;
+  disabled?: boolean;
+  fontFamily?: string;
+  height?: number | string;
+  isLoading?: boolean;
+  itemTitle?: string;
+  onClose?: () => void;
+  onError?: (payload: WidgetErrorPayload) => void;
+  onReady?: () => void;
+  onRouteChange?: (payload: WidgetRouteChangedPayload) => void;
+  onSuccess?: (payload: WidgetSuccessPayload) => void;
+  referenceId?: string;
+  style?: React.CSSProperties;
+  text?: string;
+  textColor?: string;
+  variant?: "long" | "short";
+  width?: number | string;
+};
+```
+
+<Aside type="note">
+  `chain` defaults to `mainnet`. `TonPayWidget` selects the TON Pay base URL internally, so the host app does not pass a base URL prop.
+</Aside>
+
+### `WidgetErrorPayload`
+
+```ts
+type WidgetErrorPayload = {
+  code:
+    | "unknown"
+    | "invalid_intent"
+    | "route_blocked"
+    | "wallet_disconnected"
+    | "storage_access_denied"
+    | "network_error"
+    | "setup_required"
+    | "setup_failed"
+    | "unlock_failed"
+    | "payment_failed"
+    | "insufficient_balance"
+    | "signless_stopped";
+  message: string;
+  recoverable: boolean;
+  route?: string;
+};
 ```
 
-## Imports
+### `WidgetRouteChangedPayload`
+
+```ts
+type WidgetRouteChangedPayload = {
+  pathname: string;
+  search: string;
+};
+```
+
+### `WidgetSuccessPayload`
+
+```ts
+type WidgetSuccessPayload = {
+  action: "setup" | "payment" | "topup" | "withdraw" | "reset";
+  reference?: string;
+  referenceId?: string;
+  sessionId?: string;
+  txHash?: string;
+  walletAddress?: string;
+};
+```
+
+### Checkout prop notes
+
+- `comment` is the payment comment sent to the backend flow. It maps to `commentToRecipient`.
+- `itemTitle` is UI-only text shown inside the widget.
+
+## `@ton-pay/api`
 
 ```ts
-// API helpers
 import {
+  TON,
+  USDT,
   createTonPayTransfer,
   getTonPayTransferByBodyHash,
   getTonPayTransferByReference,
-  type CompletedTonPayTransferInfo,
-  type CreateTonPayTransferParams,
-  type CreateTonPayTransferResponse,
+  verifySignature,
+  type TransferCompletedWebhookPayload,
+  type TransferRefundedWebhookPayload,
+  type WebhookPayload,
 } from "@ton-pay/api";
-
-// React UI
-import { TonPayButton, useTonPay } from "@ton-pay/ui-react";
 ```
 
-## Functions
+Use `@ton-pay/api` for backend and non-widget flows such as:
+
+- transfer creation for TON Connect or custom payment flows
+- explicit status lookups by `reference` or `bodyBase64Hash`
+- MoonPay helper calls outside the hosted widget flow
 
-### `createTonPayTransfer(params, options?)`
+### Functions
+
+#### `createTonPayTransfer(params, options?)`
 
 Build a canonical message and return tracking identifiers.
 
 - `params`: `CreateTonPayTransferParams`.
 - `options`: `APIOptions`.
 - `options.chain`: `mainnet | testnet`.
 
-### `getTonPayTransferByBodyHash(bodyHash, options?)`
+#### `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?)`
+#### `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](/ecosystem/ton-connect/overview) 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`
+### Types: `@ton-pay/api`
 
 ### `CreateTonPayTransferParams`
 
@@ -118,13 +226,13 @@ type CompletedTonPayTransferInfo = {
 ```
 
 - `status`: `pending`, `success`, or `error`;
-- `errorCode`: TON Pay error codes in [Check status and retrieve info](/ecosystem/ton-pay/payment-integration/status-info).
+- `errorCode`: TON Pay error code returned for failed transfers, when available.
 
 ### `APIOptions`
 
 ```ts
 type APIOptions = {
-  chain: "mainnet" | "testnet";
+  chain?: "mainnet" | "testnet";
 };
 ```
 
@@ -149,11 +257,9 @@ import { TON, USDT } from "@ton-pay/api";
   For testnet, explicitly pass the correct testnet jetton master address instead of using token constants.
 </Aside>
 
+
 ## 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`](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.
+See [server-side integration](/ecosystem/ton-pay/payments-integration/server-side) for end-to-end examples.

ecosystem/ton-pay/legacy/overview.mdx

@@ -0,0 +1,37 @@
+---
+title: "Legacy React UI overview"
+sidebarTitle: "Overview"
+---
+
+import { Aside } from "/snippets/aside.jsx";
+
+This section explains the React integration for `@ton-pay/ui-react` `0.3.2` and
+lower.
+
+<Aside type="note">
+  This section applies to `@ton-pay/ui-react` `0.3.2` and lower.
+</Aside>
+
+## Scope
+
+Use this section only if the application is still pinned to the old React flow
+based on:
+
+- `TonConnectUIProvider`
+- `TonPayButton`
+- `useTonPay`
+- shared backend helpers from `@ton-pay/api`
+
+## Legacy architecture
+
+1. The host app configures a [TON Connect manifest](/ecosystem/ton-connect/manifest) and wraps the React tree with `TonConnectUIProvider`.
+1. The backend creates transfers with `createTonPayTransfer()` and stores `reference` and `bodyBase64Hash`.
+1. The frontend calls `pay(createMessage)` from `useTonPay`.
+1. TON Connect opens the wallet and sends the transaction message.
+1. The backend reconciles the result through status lookups.
+
+## Next steps
+
+- [Legacy React integration guide](/ecosystem/ton-pay/legacy/react-integration)
+- [Server-side integration](/ecosystem/ton-pay/payments-integration/server-side)
+- [Migration to `TonPayWidget`](/ecosystem/ton-pay/payment-integration/migration)