---
title: Payment Button
description: Drop-in React component for Solana payments
---

<Callout type="caution">
  The Commerce Kit is currently in beta. APIs may change before the stable
  release. For additional details on Commerce Kit, see the [Commerce Kit
  documentation](/docs/tools/commerce-kit).
</Callout>

The `PaymentButton` component from the
[Commerce Kit](https://www.npmjs.com/package/@solana-commerce/kit) provides a
complete payment interface—handling wallet connection, token selection,
transaction processing, and UI state out of the box.

## Installation

```bash
pnpm add @solana-commerce/kit
```

## Basic Usage

```tsx
import { PaymentButton } from "@solana-commerce/kit";

function Checkout() {
  return (
    <PaymentButton
      config={{
        merchant: { name: "My Store", wallet: "your-wallet-address" },
        mode: "tip"
      }}
      onPaymentSuccess={(signature) => {
        console.log("Payment confirmed:", signature);
      }}
    />
  );
}
```

Check out the
[Commerce Kit Playground](https://launch.solana.com/products/commercekit/playground)
to configure and test the component.

### Tip Button

![Tip Button](/assets/docs/payments/tip-button.png)

### Pay Modal

![Pay Modal](/assets/docs/payments/pay-modal.png)

### Solana Pay QR Code Modal

![Solana Pay QR Code Modal](/assets/docs/payments/scan-modal.png)

## Payment Modes

The `mode` option determines the button behavior:

| Mode  | Description                                    |
| ----- | ---------------------------------------------- |
| `tip` | User chooses their own amount (donations/tips) |

## Configuration

### Required Config

| Property          | Type     | Description                               |
| ----------------- | -------- | ----------------------------------------- |
| `merchant.name`   | `string` | Business name shown during checkout       |
| `merchant.wallet` | `string` | Solana wallet address to receive payments |
| `mode`            | 'tip'`   | Payment flow type                         |

### Optional Config

| Property       | Type                    | Description                                        |
| -------------- | ----------------------- | -------------------------------------------------- |
| `network`      | `'mainnet' \| 'devnet'` | Solana network (default: `'mainnet'`)              |
| `rpcUrl`       | `string`                | Custom RPC endpoint                                |
| `allowedMints` | `string[]`              | Restrict accepted tokens by mint address           |
| `showQR`       | `boolean`               | Enable QR code payment option                      |
| `theme`        | `ThemeConfig`           | Visual customization (colors, border radius, etc.) |

## Event Callbacks

| Callback           | Parameters            | Description                   |
| ------------------ | --------------------- | ----------------------------- |
| `onPaymentSuccess` | `(signature: string)` | Transaction confirmed onchain |
| `onPaymentError`   | `(error: Error)`      | Payment failed at any stage   |
| `onPaymentStart`   | `()`                  | Payment flow initiated        |
| `onCancel`         | `()`                  | User cancelled the payment    |

## Custom Trigger

Replace the default button with your own element:

```tsx
<PaymentButton
  config={{
    merchant: { name: "Shop", wallet: "address" },
    mode: "tip"
  }}
>
  <button className="my-custom-button">Pay with Solana</button>
</PaymentButton>
```