Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
The `useTonPay` hook provides a React interface for creating TON Pay transfers. It integrates with [TON Connect](/ecosystem/ton-connect/overview) to connect a wallet, sign transactions, and surface transfer errors through the hook state.
## How `useTonPay` works
The `useTonPay` hook manages the client-side flow for sending a TON Pay transfer. It performs the following steps:
1. Checks whether a wallet is connected and, if not, opens the TON Connect modal and waits for a successful connection.
2. Calls an application-provided factory function that builds the transaction message, either in the client-side or by requesting it from a backend service.
3. Sends the transaction message to the connected wallet for user approval and signing.
4. Returns the transaction result along with tracking identifiers that can be used for reconciliation.
## Integration approaches
`useTonPay` can be integrated in two ways, depending on where the transaction message is created.
### Client-side message building
* Message construction happens in the browser.
* All transaction fields are provided by the client.
### Server-side message building
* Message construction happens on the backend.
* Tracking identifiers are stored on the server before the message is returned to the client for signing.
## Client-side implementation
### Prerequisites
The application must be wrapped with the TON Connect UI provider:
```tsx theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { TonConnectUIProvider } from "@tonconnect/ui-react";
export function App() {
return (
{/* Application components */}
);
}
```
[The TON Connect manifest](/ecosystem/ton-connect/manifest) file must be publicly accessible and include valid application metadata. Replace `` with the public HTTPS origin that serves `tonconnect-manifest.json`.
### Basic implementation
```tsx expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { useTonPay } from "@ton-pay/ui-react";
import { createTonPayTransfer } from "@ton-pay/api";
export function PaymentButton() {
const { pay } = useTonPay();
const handlePayment = async () => {
try {
const { txResult, message, reference, bodyBase64Hash } = await pay(
async (senderAddr: string) => {
const result = await createTonPayTransfer(
{
amount: 3.5,
asset: "TON",
recipientAddr: "",
senderAddr,
commentToSender: "Payment for Order #8451",
},
{
chain: "testnet",
// Optional API key can be shown on the client-side, but the secret key never
apiKey: "", // optional
}
);
return {
message: result.message,
reference: result.reference,
bodyBase64Hash: result.bodyBase64Hash,
};
}
);
console.log("Transaction completed:", txResult.boc);
console.log("Reference for tracking:", reference);
console.log("Body hash:", bodyBase64Hash);
// Store tracking identifiers in the database
await savePaymentRecord({
reference,
bodyBase64Hash,
amount: 3.5,
asset: "TON",
});
} catch (error) {
console.error("Payment failed:", error);
// Handle error appropriately
}
};
return ;
}
```
### Response fields
The `pay` function returns the following fields:
Transaction result returned by TON Connect. It contains the signed transaction [bag of cells](/foundations/serialization/boc) and additional transaction details.
The transaction message that was sent, including the recipient address, amount, and payload.
Unique tracking identifier for this transaction. Use it to correlate webhook notifications with orders.
Base64-encoded hash of the transaction body. Can be used for advanced transaction verification.
## Server-side implementation
### Backend endpoint
Create an API endpoint that builds the transaction message and stores tracking data:
```typescript expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { createTonPayTransfer } from "@ton-pay/api";
app.post("/api/create-payment", async (req, res) => {
const { amount, senderAddr, orderId } = req.body;
try {
const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
{
amount,
asset: "TON",
recipientAddr: "",
senderAddr,
commentToSender: `Payment for Order ${orderId}`,
commentToRecipient: `Order ${orderId}`,
},
{
chain: "testnet",
apiKey: "yourTonPayApiKey", // optional
}
);
// Store tracking identifiers in your database
await db.createPayment({
orderId,
reference,
bodyBase64Hash,
amount,
asset: "TON",
status: "pending",
senderAddr,
});
// Return only the message to the client
res.json({ message });
} catch (error) {
console.error("Failed to create payment:", error);
res.status(500).json({ error: "Failed to create payment" });
}
});
```
### Frontend implementation
```tsx expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { useTonPay } from "@ton-pay/ui-react";
export function ServerPaymentButton({
orderId,
amount,
}: {
orderId: string;
amount: number;
}) {
const { pay } = useTonPay();
const handlePayment = async () => {
try {
const { txResult } = await pay(async (senderAddr: string) => {
const response = await fetch("/api/create-payment", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ amount, senderAddr, orderId }),
});
if (!response.ok) {
throw new Error("Failed to create payment");
}
const { message } = await response.json();
return { message };
});
console.log("Transaction sent:", txResult.boc);
// Optionally redirect or show success message
window.location.href = `/orders/${orderId}/success`;
} catch (error) {
console.error("Payment failed:", error);
alert("Payment failed. Please try again.");
}
};
return ;
}
```
## Error handling
The `useTonPay` hook throws errors in the following scenarios:
### Wallet connection errors
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const { pay } = useTonPay();
try {
await pay(getMessage);
} catch (error) {
if (error.message === "Wallet connection modal closed") {
// User closed the connection modal without connecting
console.log("User cancelled wallet connection");
} else if (error.message === "Wallet connection timeout") {
// Connection attempt exceeded 5-minute timeout
console.log("Connection timeout - please try again");
}
}
```
### Transaction errors
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
try {
await pay(getMessage);
} catch (error) {
// User rejected the transaction in their wallet
if (error.message?.includes("rejected")) {
console.log("User rejected the transaction");
}
// Network or API errors
else if (error.message?.includes("Failed to create TON Pay transfer")) {
console.log("API error - check your configuration");
}
// Other unexpected errors
else {
console.error("Unexpected error:", error);
}
}
```
## Best practices
* Persist tracking identifiers immediately.
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// Good: Store before transaction
const { message, reference } = await createTonPayTransfer(...);
await db.createPayment({ reference, status: "pending" });
return { message };
// Bad: Only storing after successful transaction
const { txResult, reference } = await pay(...);
await db.createPayment({ reference }); // Too late if network fails
```
* Always validate or generate amounts server-side to prevent manipulation. Never trust amount values sent from the client.
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// Server-side endpoint
app.post('/api/create-payment', async (req, res) => {
const { orderId, senderAddr } = req.body;
// Fetch the actual amount from your database
const order = await db.getOrder(orderId);
// Use the verified amount, not req.body.amount
const { message } = await createTonPayTransfer({
amount: order.amount,
asset: order.currency,
recipientAddr: '',
senderAddr,
});
res.json({ message });
});
```
* Wrap the payment components with React error boundaries to handle failures.
```tsx theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
class PaymentErrorBoundary extends React.Component {
componentDidCatch(error: Error) {
console.error('Payment component error:', error);
// Log to the error tracking service
}
render() {
return this.props.children;
}
}
```
* Payment processing can take several seconds. Provide clear feedback to users during wallet connection and transaction signing.
```tsx theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const [loading, setLoading] = useState(false);
const handlePayment = async () => {
setLoading(true);
try {
await pay(getMessage);
} finally {
setLoading(false);
}
};
return (
);
```
* Use environment variables for sensitive data and chain configuration.
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const { message } = await createTonPayTransfer(params, {
chain: process.env.TON_CHAIN as 'mainnet' | 'testnet',
apiKey: process.env.TONPAY_API_KEY, // optional
});
```
## Troubleshooting
Wrap the application with `TonConnectUIProvider`:
```tsx theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { TonConnectUIProvider } from "@tonconnect/ui-react";
function App() {
return (
);
}
```
1. Verify that the TON Connect manifest URL is accessible and valid.
2. Check the browser console for TON Connect initialization errors.
3. Ensure the manifest file is served with correct [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) headers.
4. Open the manifest URL directly in the browser to verify it loads.
1. Verify that the recipient address is [a valid TON address](/foundations/addresses/formats).
2. Ensure the address format matches the selected chain; mainnet or testnet.
3. Verify that the address includes the full base64 representation with workchain.
1. Check whether the optional API key is missing or invalid for endpoints that require authentication.
2. Verify network connectivity.
3. Validate parameter values. For example, non-negative amounts and valid addresses.
4. Confirm the correct chain configuration; mainnet or testnet.
To inspect the underlying API error:
```ts theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
try {
await createTonPayTransfer(...);
} catch (error) {
console.error("API Error:", error.cause); // HTTP status text
}
```
1. Note that TON Connect may not emit an explicit error on rejection.
2. Add timeout handling:
```ts theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const paymentPromise = pay(getMessage);
const timeoutPromise = new Promise((_, reject) =>
setTimeout(() => reject(new Error("Transaction timeout")), 60000)
);
await Promise.race([paymentPromise, timeoutPromise]);
```
## Optional API key configuration
When using `useTonPay` with server-side message building, the optional API key can be included in the backend endpoint to enable dashboard features and webhooks:
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// Backend endpoint
app.post("/api/create-payment", async (req, res) => {
const { amount, senderAddr, orderId } = req.body;
const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
{
amount,
asset: "TON",
recipientAddr: process.env.MERCHANT_WALLET_ADDRESS!,
senderAddr,
},
{
chain: "testnet",
apiKey: process.env.TONPAY_API_KEY, // Optional: enables dashboard features
}
);
await db.createPayment({ orderId, reference, bodyBase64Hash });
res.json({ message });
});
```
## Testnet configuration
A complete description of testnet configuration, including obtaining testnet TON, testing jetton transfers, verifying transactions, and preparing for mainnet deployment, is available in the [Testnet configuration](/ecosystem/ton-pay/payment-integration/transfer#testnet-configuration) section.
## Next steps
Receive real-time notifications when payments complete.
Query payment status using reference or body hash.