> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/ton-pay/ui-integration/button-react",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# How to add a TON Pay button using React

export const Image = ({src, darkSrc, alt = '', darkAlt, href, target, height = 342, width = 608, noZoom = false, center = false}) => {
  const isSVG = src.match(/\.svg(?:[#?].*?)?$/i) !== null;
  const shouldInvert = isSVG && !darkSrc;
  const shouldCreateLink = href !== undefined;
  const minPx = 9;
  const maxPx = 608;
  const expectedPx = `a number or a string with a number that is greater than ${minPx - 1} and less than or equal to ${maxPx}`;
  const createInvalidPropCallout = (title, received, expected) => {
    return <Danger>
        <span className="font-bold">
          Invalid <code>{title.toString()}</code> passed!
        </span>
        <br />
        <span className="font-bold">Received: </span>
        {received.toString()}
        <br />
        <span className="font-bold">Expected: </span>
        {expected.toString()}
        {}
      </Danger>;
  };
  const checkValidDimensionValue = value => {
    switch (typeof value) {
      case "string":
      case "number":
        const num = Number(value);
        return Number.isSafeInteger(num) && num >= minPx && num <= maxPx;
      default:
        return false;
    }
  };
  let callouts = [];
  if (height && !checkValidDimensionValue(height)) {
    callouts.push(createInvalidPropCallout("height", height, expectedPx));
  }
  if (width && !checkValidDimensionValue(width)) {
    callouts.push(createInvalidPropCallout("width", width, expectedPx));
  }
  if (callouts.length !== 0) {
    return callouts;
  }
  const heightPx = Number(height);
  const widthPx = Number(width);
  const shouldCenter = center === "true" || center === true ? true : false;
  const shouldNotZoom = noZoom === "true" || noZoom === true ? true : false;
  const images = <>
      <img className="block dark:hidden" src={src} alt={alt} {...height && ({
    height: heightPx
  })} {...width && ({
    width: widthPx
  })} {...(shouldCreateLink || shouldInvert || shouldNotZoom) && ({
    noZoom: "true"
  })} />
      <img className={`hidden dark:block ${shouldInvert ? "invert" : ""}`} src={darkSrc ?? src} alt={darkAlt ?? alt} {...height && ({
    height: heightPx
  })} {...width && ({
    width: widthPx
  })} {...(shouldCreateLink || shouldInvert || shouldNotZoom) && ({
    noZoom: "true"
  })} />
    </>;
  if (shouldCreateLink) {
    if (shouldCenter) {
      return <div style={{
        display: "flex",
        justifyContent: "center"
      }}>
          <a href={href} target={target ?? "_self"}>
            {images}
          </a>
        </div>;
    }
    return <a href={href} target={target ?? "_self"}>
        {images}
      </a>;
  }
  if (shouldCenter) {
    return <div style={{
      display: "flex",
      justifyContent: "center"
    }}>{images}</div>;
  }
  return images;
};

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

`TonPayButton` is a ready-to-use React component that handles wallet connection and payment flow with configurable styling for TON payments. The default button appearance is shown below.

<div style={{ display: "flex", justifyContent: "center" }}>
  <Image src="/resources/images/ton-pay/button.png" alt="TON Pay button" width={300} noZoom={true} />
</div>

## Install packages

<Steps>
  <Step title="Install necessary libraries">
    ```bash 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"]}}
    npm install @ton-pay/ui-react @ton-pay/api @tonconnect/ui-react
    ```
  </Step>

  <Step title="Create a TON Connect manifest">
    Create [`tonconnect-manifest.json`](/ecosystem/ton-connect/manifest) in the app public directory:

    ```json 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"]}}
    {
      "url": "<APP_URL>",
      "name": "<APP_NAME>",
      "iconUrl": "<APP_ICON_URL>"
    }
    ```
  </Step>

  <Step title="Wrap the app with the provider">
    Wrap the root component 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 (
        <TonConnectUIProvider manifestUrl="https://<APP_URL>/tonconnect-manifest.json">
          <AppRoutes />
        </TonConnectUIProvider>
      );
    }
    ```
  </Step>
</Steps>

<Aside type="note" title="HTTPS required">
  To receive webhooks in production, ensure corresponding endpoints use HTTPS. Regular HTTP endpoints would be ignored by TON Pay.
</Aside>

## Option 1: use useTonPay hook

The `useTonPay` hook simplifies wallet connection and transaction handling. Use it for a direct integration path.

<Steps>
  <Step title="Import required dependencies">
    ```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 { TonPayButton } from "@ton-pay/ui-react";
    import { useTonPay } from "@ton-pay/ui-react";
    import { createTonPayTransfer } from "@ton-pay/api";
    import { useState } from "react";
    ```
  </Step>

  <Step title="Set up the component">
    ```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"]}}
    function PaymentComponent() {
      const { pay } = useTonPay();
      const [isLoading, setIsLoading] = useState(false);
    ```
  </Step>

  <Step title="Create the payment handler">
    ```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 handlePayment = async () => {
        setIsLoading(true);
        try {
          const { txResult, reference, bodyBase64Hash } = await pay(
            async (senderAddr: string) => {
              // Build the payment message
              const { message, reference, bodyBase64Hash } =
                await createTonPayTransfer(
                  {
                    amount: 3.5,
                    asset: "TON",
                    recipientAddr: "<RECIPIENT_ADDRESS>",
                    senderAddr,
                    commentToSender: "Order #12345",
                  },
                  { chain: "testnet" } // change to "mainnet" only after full validation
                );
              return { message, reference, bodyBase64Hash };
            }
          );

          console.log("Payment sent:", txResult);
          console.log("Tracking:", reference, bodyBase64Hash);
        } catch (error) {
          console.error("Payment failed:", error);
        } finally {
          setIsLoading(false);
        }
      };
    ```

    <Aside type="note">
      The `useTonPay` hook automatically checks wallet connection. If the user is not connected, it opens the TON Connect modal first.
    </Aside>
  </Step>

  <Step title="Render the button">
    ```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"]}}
      return (
        <TonPayButton
          handlePay={handlePayment}
          isLoading={isLoading}
          loadingText="Processing payment..."
        />
      );
    }
    ```
  </Step>
</Steps>

## Option 2: use TON Connect directly

Use TON Connect hooks directly when full control over the connection flow is required.

<Steps>
  <Step title="Import TON Connect hooks">
    ```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 { TonPayButton } from "@ton-pay/ui-react";
    import {
      useTonAddress,
      useTonConnectModal,
      useTonConnectUI,
    } from "@tonconnect/ui-react";
    import { createTonPayTransfer } from "@ton-pay/api";
    import { useState } from "react";
    ```
  </Step>

  <Step title="Set up hooks and state">
    ```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"]}}
    function DirectPaymentComponent() {
      const address = useTonAddress(true);
      const modal = useTonConnectModal();
      const [tonConnectUI] = useTonConnectUI();
      const [isLoading, setIsLoading] = useState(false);
    ```
  </Step>

  <Step title="Create the payment handler">
    ```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 handlePay = async () => {
        // Check if wallet is connected
        if (!address) {
          modal.open();
          return;
        }

        setIsLoading(true);
        try {
          // Create the payment message
          const { message } = await createTonPayTransfer(
            {
              amount: 1.2,
              asset: "TON",
              recipientAddr: "<RECIPIENT_ADDRESS>",
              senderAddr: "<SENDER_ADDRESS>",
              commentToSender: "Invoice #5012",
            },
            { chain: "mainnet" } // can be changed to testnet
          );

          // Send the transaction
          await tonConnectUI.sendTransaction({
            messages: [message],
            validUntil: Math.floor(Date.now() / 1000) + 5 * 60,
            from: address,
          });

          console.log("Payment completed!");
        } catch (error) {
          console.error("Payment failed:", error);
        } finally {
          setIsLoading(false);
        }
      };
    ```
  </Step>

  <Step title="Render the button">
    ```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"]}}
      return <TonPayButton handlePay={handlePay} isLoading={isLoading} />;
    }
    ```
  </Step>
</Steps>

## TonPayButton props

All props are optional except `handlePay`.

| Prop                    | Type                        | Default           | Description                                                                                                     |
| ----------------------- | --------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `handlePay`             | `() => Promise<void>`       | required          | Payment handler called when the button is selected.                                                             |
| `isLoading`             | `boolean`                   | `false`           | Shows a loading spinner and disables the button.                                                                |
| `variant`               | `"long"` \| `"short"`       | `"long"`          | Button text variant: "Pay with TON Pay" (long) or "TON Pay" (short).                                            |
| `preset`                | `"default"` \| `"gradient"` | -                 | Predefined theme preset; overrides `bgColor` and `textColor`.                                                   |
| `onError`               | `(error: unknown) => void`  | -                 | Called when `handlePay` throws. A built-in error popup is also shown unless `showErrorNotification` is `false`. |
| `showErrorNotification` | `boolean`                   | `true`            | Shows the built-in error notification popup on error.                                                           |
| `bgColor`               | `string`                    | `"#0098EA"`       | Background color (hex) or CSS gradient.                                                                         |
| `textColor`             | `string`                    | `"#FFFFFF"`       | Text and icon color (hex).                                                                                      |
| `borderRadius`          | `number` \| `string`        | `8`               | Border radius in pixels or CSS value.                                                                           |
| `fontFamily`            | `string`                    | `"inherit"`       | Font family for button text.                                                                                    |
| `width`                 | `number` \| `string`        | `300`             | Button width in pixels or CSS value.                                                                            |
| `height`                | `number` \| `string`        | `44`              | Button height in pixels or CSS value.                                                                           |
| `loadingText`           | `string`                    | `"Processing..."` | Text shown during loading state.                                                                                |
| `showMenu`              | `boolean`                   | `true`            | Shows the dropdown menu with wallet actions.                                                                    |
| `disabled`              | `boolean`                   | `false`           | Disables the button.                                                                                            |
| `style`                 | `Record<string, any>`       | -                 | Additional inline styles.                                                                                       |
| `className`             | `string`                    | -                 | Additional CSS class name.                                                                                      |

## Customization

### Button variants

[Use `useTonPay`](/ecosystem/ton-pay/ui-integration/button-react#option-1:-using-usetonpay-hook-recommended) for a complete example.

<CodeGroup>
  ```tsx Long variant (default) 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"]}}
  <TonPayButton
    variant="long"
    handlePay={handlePay}
  />
  // Displays: "Pay with [TON icon] Pay"
  ```

  ```tsx Short variant 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"]}}
  <TonPayButton
    variant="short"
    handlePay={handlePay}
  />
  // Displays: "[TON icon] Pay"
  ```
</CodeGroup>

### Presets

[Use `useTonPay`](/ecosystem/ton-pay/ui-integration/button-react#option-1:-using-usetonpay-hook-recommended) for a complete example.

<CodeGroup>
  ```tsx Default preset 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"]}}
  <TonPayButton
    preset="default"
    handlePay={handlePay}
  />
  // Blue theme: #0098EA
  ```

  ```tsx Gradient preset 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"]}}
  <TonPayButton
    preset="gradient"
    handlePay={handlePay}
  />
  // Gradient: #2A82EB to #0355CF
  ```
</CodeGroup>

### Custom styling

[Use `useTonPay`](/ecosystem/ton-pay/ui-integration/button-react#option-1:-using-usetonpay-hook-recommended) for a complete example.

```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"]}}
<TonPayButton
  bgColor="#7C3AED"
  textColor="#FFFFFF"
  borderRadius={12}
  width={400}
  height={56}
  fontFamily="'Inter', sans-serif"
  handlePay={handlePay}
/>
```

CSS gradients can be used in `bgColor`. For example: `"linear-gradient(135deg, #667eea 0%, #764ba2 100%)"`.

### Button states

[Use `useTonPay`](/ecosystem/ton-pay/ui-integration/button-react#option-1:-using-usetonpay-hook-recommended) for a complete example.

```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"]}}
<TonPayButton
  handlePay={handlePay}
  isLoading={isLoading}
  loadingText="Processing payment..."
  disabled={cartTotal === 0}
  showMenu={false}
/>
```

## Advanced patterns

### Error handling

```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 { TonPayButton, useTonPay } from "@ton-pay/ui-react";
import { createTonPayTransfer } from "@ton-pay/api";
import { useState } from "react";

function PaymentWithErrors() {
  const { pay } = useTonPay();
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handlePayment = async () => {
    setIsLoading(true);
    setError(null);

    try {
      await pay(async (senderAddr: string) => {
        const { message, reference, bodyBase64Hash } =
          await createTonPayTransfer(
            {
              amount: 5.0,
              asset: "TON",
              recipientAddr: "<RECIPIENT_ADDR>",
              senderAddr,
            },
            { chain: "testnet" }
          );
        return { message, reference, bodyBase64Hash };
      });
      // Show success message...
    } catch (err: any) {
      setError(err.message || "Payment failed. Please try again.");
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div>
      <TonPayButton handlePay={handlePayment} isLoading={isLoading} />
      {error && <div style={{ color: "red" }}>{error}</div>}
    </div>
  );
}
```

#### Built-in error notification

`TonPayButton` catches errors thrown from `handlePay` and shows a notification pop-up with the error message.

If a custom error UI is also rendered, both messages appear. Use either the built-in pop-up or a custom UI, but not both.

#### Add a custom error handler

Use `onError` for logging or custom notifications. Set `showErrorNotification={false}` to disable the built-in pop-up.

```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 { TonPayButton, useTonPay } from "@ton-pay/ui-react";
import { createTonPayTransfer } from "@ton-pay/api";
import { useState } from "react";

function PaymentWithCustomHandler() {
  const { pay } = useTonPay();
  const [isLoading, setIsLoading] = useState(false);

  const handlePayment = async () => {
    setIsLoading(true);
    try {
      await pay(async (senderAddr: string) => {
        const { message } = await createTonPayTransfer(
          {
            amount: 3,
            asset: "TON",
            recipientAddr: "<RECIPIENT_ADDR>",
            senderAddr,
          },
          { chain: "testnet" }
        );
        return { message };
      });
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <TonPayButton
      handlePay={handlePayment}
      isLoading={isLoading}
      onError={(error) => {
        analytics.track("payment_error", {
          message: (error as any)?.message ?? String(error),
        });
        // The toast/notification can go here
      }}
      showErrorNotification={false}
    />
  );
}
```

Replace the pop-up with a custom UI. Catch errors inside `handlePay` and do not rethrow. When `handlePay` resolves, the button does not show the default pop-up.

```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 { TonPayButton, useTonPay } from "@ton-pay/ui-react";
import { createTonPayTransfer } from "@ton-pay/api";
import { useState } from "react";

function PaymentWithOwnUI() {
  const { pay } = useTonPay();
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handlePayment = async () => {
    setIsLoading(true);
    setError(null);
    try {
      await pay(async (senderAddr: string) => {
        const { message } = await createTonPayTransfer(
          {
            amount: 2.5,
            asset: "TON",
            recipientAddr: "<RECIPIENT_ADDR>",
            senderAddr,
          },
          { chain: "testnet" }
        );
        return { message };
      });
    } catch (e: any) {
      // Handle the error here and DO NOT rethrow
      setError(e?.message ?? "Payment failed. Please try again.");
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div>
      <TonPayButton handlePay={handlePayment} isLoading={isLoading} />
      {error && <div style={{ color: "red" }}>{error}</div>}
    </div>
  );
}
```

## Server-side payment creation

Create the payment message on a backend to store tracking identifiers and validate parameters before sending.

<Steps>
  <Step title="Create a backend endpoint">
    Build an endpoint that returns the message for `TonPayButton`.

    ```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"]}}
    // /api/create-payment
    app.post("/api/create-payment", async (req, res) => {
      const { amount, senderAddr, orderId } = req.body;

      const { message, reference, bodyBase64Hash } = await createTonPayTransfer(
        {
          amount,
          asset: "TON",
          recipientAddr: "<RECIPIENT_ADDR>",
          senderAddr,
          commentToSender: `Order ${orderId}`,
        },
        { chain: "testnet" }
      );

      // Store reference and bodyBase64Hash in the database
      await db.savePayment({ orderId, reference, bodyBase64Hash });

      res.json({ message });
    });
    ```
  </Step>

  <Step title="Call the endpoint from the frontend">
    ```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 { TonPayButton, useTonPay } from "@ton-pay/ui-react";
    import { useState } from "react";

    function ServerSidePayment() {
      const { pay } = useTonPay();
      const [isLoading, setIsLoading] = useState(false);

      const handlePayment = async () => {
        setIsLoading(true);
        try {
          await pay(async (senderAddr: string) => {
            const response = await fetch("/api/create-payment", {
              method: "POST",
              headers: { "Content-Type": "application/json" },
              body: JSON.stringify({
                amount: 10.5,
                senderAddr,
                orderId: "<ORDER_ID>",
              }),
            });
            const data = await response.json();
            return { message: data.message };
          });
        } finally {
          setIsLoading(false);
        }
      };

      return <TonPayButton handlePay={handlePayment} isLoading={isLoading} />;
    }
    ```
  </Step>
</Steps>

<Aside type="tip">
  Creating payments server-side allows storing tracking identifiers and validating payment parameters before sending.
</Aside>

## Test the integration

Run the interactive button showcase to test variants and styling.

```bash 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"]}}
npm run test:button-react
# or
bun test:button-react
```

<Aside type="danger" title="Funds at risk">
  Running tests on mainnet can result in irreversible loss of real TON. Always use `chain: "testnet"` and testnet wallet addresses during development. Verify the network before switching to mainnet.
</Aside>

## Best practices

* Wrap payment calls in try-catch blocks and display user-friendly error messages. Network issues and cancellations are common.
* Set `isLoading={true}` during payment processing to prevent double submissions and provide visual feedback.
* Verify cart totals, user input, and business rules before calling the payment handler.
* Use `chain: "testnet"` during development. Switch to `"mainnet"` only after validation.
* Save `reference` and `bodyBase64Hash` to track payment status using [webhooks](/ecosystem/ton-pay/webhooks).
* After successful payment, show a confirmation message, redirect to a success page, or update the UI.