@mnee-pay/checkout

The official React SDK for integrating MNEE Pay crypto payments into your application. This library provides a customizable, pre-built checkout experience that handles wallet connection, transaction signing, and order flow.

🚀 Features

• Complete Checkout Flow: Handles item selection, shipping collection, and payment processing.
• Multiple Modes: Supports Donations, E-commerce (Physical/Digital), and Paywalls.
• Wallet Integration: Built-in support for Yours Wallet and other EVM-compatible wallets via Wagmi/RainbowKit.
• Customizable: Extensive theming and styling options to match your brand.
• Developer Friendly: Written in TypeScript with full type definitions.

📦 Installation

pnpm add @mnee-pay/checkout
# or
npm install @mnee-pay/checkout
# or
yarn add @mnee-pay/checkout

💻 Usage

1. Import Styles

Import the CSS file at the root of your application (e.g., in _app.tsx, layout.tsx, or main.tsx).

import "@mnee-pay/checkout/styles.css";

2. Basic Implementation

The simplest way to use the SDK is via the standalone MneeCheckout component, which handles all necessary providers internally.

import { MneeCheckout } from "@mnee-pay/checkout";

export default function Page() {
  return (
    <div className="p-10">
      <h1>Donate to our Cause</h1>

      <MneeCheckout
        buttonId="btn_your_button_id_here"
        onSuccess={(result) => console.log("Payment successful", result)}
        onCancel={() => console.log("User closed checkout")}
        onError={(error) => console.error("Payment failed", error)}
      />
    </div>
  );
}

3. Advanced Usage (Shared Providers)

If you have multiple checkout buttons on a single page, or if you are already using Wagmi/TanStack Query in your app, you should use the MneeSharedProviders wrapper to avoid provider conflicts and optimize performance.

import {
  MneeSharedProviders,
  MneeCheckoutWithoutProviders,
} from "@mnee-pay/checkout";

export default function ShopPage() {
  return (
    <MneeSharedProviders>
      <div className="product-grid">
        <div className="product-card">
          <h2>Basic Plan</h2>
          <MneeCheckoutWithoutProviders buttonId="btn_basic_plan" />
        </div>

        <div className="product-card">
          <h2>Premium Plan</h2>
          <MneeCheckoutWithoutProviders buttonId="btn_premium_plan" />
        </div>
      </div>
    </MneeSharedProviders>
  );
}

⚙️ Configuration (Props)

| Prop | Type | Default | Description | | ---------------- | ------------------------------ | ----------- | ------------------------------------------------------------------------- | | buttonId | string | preview | The unique ID of the payment button configured in the MNEE Pay dashboard. | | triggerMode | button | custom | button | | open | boolean | undefined | Controls the modal visibility (required when triggerMode="custom"). | | onOpenChange | (open: boolean) => void | - | Callback triggered when the modal's open state changes. | | theme | auto | light | dark | | previewMode | boolean | false | If true, disables actual payment processing for UI testing. | | showConfetti | boolean | true | Whether to show the confetti animation upon successful payment. | | enabledWallets | string[] | - | Array of wallet IDs to enable. Defaults to all if undefined. | | disabled | boolean | false | Disables the trigger button and prevents the checkout from opening. | | apiBaseUrl | string | - | Overrides the default API URL. | | styling | StyleConfig | - | Object for custom styling (colors, fonts, border radius). | | onSuccess | (res: PaymentResult) => void | - | Callback fired after a successful transaction. | | onError | (error: Error) => void | - | Callback fired if an error occurs. | | onCancel | () => void | - | Callback fired if the user closes the modal without paying. |

🎨 Styling

You can customize the appearance of the checkout button and modal by passing a styling object or overriding CSS variables.

<MneeCheckout
  buttonId="..."
  styling={{
    primaryColor: "#ff5722",
    buttonColor: "#000000",
    buttonTextColor: "#ffffff",
    customCSS: ".mnee-checkout-root { border-radius: 8px; }",
  }}
/>

🛠️ Development

This package uses Vite for building and Storybook for component development.

Commands

• pnpm dev: Build the library in watch mode.
• pnpm build: Build the production distribution (dist/).
• pnpm storybook: Start the Storybook development server on port 6006.
• pnpm lint: Run TypeScript type checking.

Project Structure

• src/components: React components (Modal, Button, Forms).
• src/store: State management (Zustand) for cart and checkout flow.
• src/lib: Utilities for Bitcoin transactions, formatting, and validation.
• src/hooks: Custom React hooks.