fix(ton-pay): streamline on-ramp documentation and remove legacy sections

- Updated the on-ramp documentation to clarify the integration process with MoonPay, enhancing user guidance.
- Removed outdated legacy version sections from the documentation to focus on current practices.
- Added details on regional availability and wallet funding processes to improve clarity for developers.

Author: an-kor

docs.json

@@ -244,13 +244,6 @@
                   "ecosystem/ton-pay/ui-integration/button-js"
                 ]
               },
-              {
-                "group": "Legacy versions",
-                "pages": [
-                  "ecosystem/ton-pay/legacy/overview",
-                  "ecosystem/ton-pay/legacy/react-integration"
-                ]
-              },
               "ecosystem/ton-pay/api-reference"
             ]
           },

ecosystem/ton-pay/legacy/overview.mdx

@@ -3,17 +3,35 @@ title: "On-ramp in TON Pay SDK"
 sidebarTitle: "On-ramp"
 ---
 
-import { Aside } from '/snippets/aside.jsx';
+import { Aside } from "/snippets/aside.jsx";
 
-The TON Pay SDK includes a built-in fiat-to-crypto on-ramp powered by [MoonPay](https://www.moonpay.com/). It allows users to top up their wallets with a bank card directly from the payment modal.
+TON Pay includes a built-in fiat-to-crypto on-ramp powered by [MoonPay](https://www.moonpay.com/). Inside `TonPayWidget`, MoonPay can appear as an embedded top-up step when the user needs additional funds to complete checkout.
+
+This lets users buy crypto with a bank card and receive funds directly into the wallet used for the payment flow. The merchant payment is completed only after the funds arrive in the user's wallet and the balance becomes sufficient.
 
 ## How it works
 
-1. The user opens `TonPayWidget`.
-1. TON Pay evaluates the current checkout state inside the hosted flow.
-1. If wallet funding is needed and on-ramp is available for that session, the widget can present a top-up step.
-1. After the top-up flow, the user can continue checkout in the same widget experience.
+When the user opens `TonPayWidget`, TON Pay evaluates the current checkout state. If the wallet balance is not enough to complete the purchase, the hosted flow can offer an on-ramp step.
+
+1. Balance check. TON Pay verifies whether the connected wallet has enough funds for the requested payment.
+1. MoonPay availability check. TON Pay checks whether the current session is eligible for MoonPay, including regional availability, supported asset, and provider-side limits.
+1. Amount calculation. TON Pay calculates the top-up amount required to continue checkout.
+1. Widget rendering. If the session is eligible, the MoonPay purchase widget opens inside the hosted TON Pay flow.
+1. Wallet funding. The purchased assets are sent directly to the user's wallet, not to the merchant.
+1. Checkout resume. After the wallet balance becomes sufficient, the user can continue and complete the merchant payment in the same flow.
+
+## Regional availability
+
+TON Pay offers the on-ramp step only when MoonPay supports purchases in the buyer's region. If MoonPay is unavailable for that region, the widget does not suggest topping up the wallet by card and the user can continue only with funds that are already available in the wallet or added externally.
+
+Availability can also depend on provider rules for the selected asset, payment method, and transaction amount.
 
 ## Merchant integration
 
-No dedicated on-ramp props are required in the host app. Render `TonPayWidget` with the checkout parameters and let the hosted flow decide when to surface on-ramp.
+No dedicated on-ramp setup is required in the host app for the default hosted flow. Render [`TonPayWidget`](/ecosystem/ton-pay/ui-integration/button-react) with the checkout parameters, and TON Pay will decide whether to surface the MoonPay top-up step for that specific session.
+
+If your integration uses custom server-side flows instead of the hosted widget, see the [server-side integration guide](/ecosystem/ton-pay/payment-integration/payments-server-side) for `@ton-pay/api` usage, including MoonPay-related helper calls outside the widget flow.
+
+<Aside type="note" title="Processing times and provider rules">
+  MoonPay purchases are subject to provider-side availability, limits, fees, and confirmation time. TON Pay can continue checkout only after the purchased funds reach the user's wallet.
+</Aside>

ecosystem/ton-pay/legacy/react-integration.mdx

@@ -103,6 +103,7 @@ The UI components provide a complete checkout experience for most web applicatio
 1. TON Pay backend generates a transaction message.
 1. The user reviews and signs the transaction in the wallet.
 1. The transaction is executed and confirmed on the TON blockchain.
+1. After the payment is submitted for signing, the SDK lets the application track completion by `reference` or `bodyBase64Hash`.
 
 ## Security
 
@@ -116,4 +117,4 @@ Install the [SDK](https://www.npmjs.com/package/@ton-pay/api) and configure the
 
 <sub>
   TON Pay SDK is open source software licensed under the Apache License 2.0.
-</sub>
+</sub>

ecosystem/ton-pay/on-ramp.mdx

@@ -18,7 +18,8 @@ import { Aside } from "/snippets/aside.jsx";
     ```
 
     <Aside type="tip">
-      `TonPayWidget` does not require `@ton-pay/api`. Install it only for server-side.
+      `TonPayWidget` does not require `@ton-pay/api`. Install it separately only
+      for server-side helpers or for flows that do not use the TON Pay UI.
     </Aside>
   </Step>