allow users to configure plugin

Author: eabdelmoneim

.gitignore

@@ -11,6 +11,11 @@ dist/
 .env.local
 .env.*.local
 
+# Test app
+test-app/node_modules/
+test-app/.env
+test-app/dist/
+
 # IDE
 .vscode/
 .idea/

CLAUDE.md

@@ -47,8 +47,9 @@ A WordPress/WooCommerce plugin that adds stablecoin payment support (USDC, USDT)
 1. Customer selects "Pay with Stablecoin" at checkout
 2. `ThirdwebCheckout.tsx` renders the CheckoutWidget with order total
 3. Customer connects wallet (MetaMask/Coinbase/WalletConnect) or pays with card
-4. Payment completes on-chain → thirdweb webhook fires to `/wp-json/thirdweb-wc/v1/webhook`
-5. PHP verifies transaction and marks WooCommerce order complete
+4. Payment completes on-chain → CheckoutWidget fires `onSuccess` callback with transaction data
+5. React component captures transaction hash and passes it to WooCommerce
+6. PHP verifies transaction on-chain via RPC and marks order complete
 
 ## Build Commands
 
@@ -80,9 +81,8 @@ Settings at: WooCommerce → Settings → Payments → Stablecoin Payment
 
 - **thirdweb Client ID**: From thirdweb dashboard
 - **Seller Wallet**: Address to receive payments
-- **Blockchain Network**: Base, Ethereum, Arbitrum, Polygon, Optimism
-- **Token Address**: USDC/USDT contract (optional, defaults to native token)
-- **Webhook Secret**: For verifying webhook signatures
+- **Chain ID**: Blockchain network chain ID (default: 8453 for Base). Supports any EVM chain
+- **Token Address**: USDC/USDT contract for the selected chain (optional, defaults to native token)
 
 ## CheckoutWidget Props Reference
 
@@ -94,10 +94,9 @@ Settings at: WooCommerce → Settings → Payments → Stablecoin Payment
   seller="0x..."                     // Merchant wallet address
   tokenAddress="0x..."               // USDC/USDT contract (optional)
   paymentMethods={['crypto', 'card']} // Enabled payment methods
-  onSuccess={handleSuccess}          // Success callback
+  onSuccess={handleSuccess}          // Success callback - receives Status[] with transaction data
   onError={handleError}              // Error callback
   onCancel={handleCancel}            // Cancel callback
-  purchaseData={{ orderId, source }} // Passed to webhook for order matching
   theme="light"                      // UI theme
   supportedTokens={{...}}            // Tokens users can pay with
 />
@@ -117,13 +116,13 @@ Settings at: WooCommerce → Settings → Payments → Stablecoin Payment
 - WooCommerce checkout blocks use React on frontend (not PHP server-rendered)
 - `@woocommerce/blocks-registry` provides `registerPaymentMethod()` API
 - `getSetting('thirdweb_stablecoin_data')` retrieves PHP config in React
-- Webhook endpoint must be publicly accessible for thirdweb to call
+- Transaction hash captured from CheckoutWidget's `onSuccess` callback
 - Transaction verification happens server-side via RPC for security
 
 ## TODO
 
 - [ ] Add refund support via thirdweb API
-- [ ] Implement proper webhook signature verification
 - [ ] Add transaction receipt email with block explorer link
 - [ ] Support multiple tokens per checkout
 - [ ] Add test mode toggle for testnet payments
+- [ ] Enhanced on-chain transaction verification (amount, recipient validation)

README.md

@@ -47,24 +47,53 @@ thirdweb-woocommerce-checkout/
 │       ├── index.tsx                    # React entry point
 │       └── ThirdwebCheckout.tsx         # CheckoutWidget wrapper
 ├── build/                               # Compiled JS (gitignored)
+├── test-app/                            # Standalone React test app
 ├── .env.example                         # Environment variables template
-├── .env                                 # Your environment variables (create from .env.example)
 ├── package.json
 ├── tsconfig.json
 └── webpack.config.js
 ```
 
 ## Installation & Setup
 
-### 1. Install Dependencies
+### For End Users (WordPress Admin)
+
+1. **Download the Plugin**
+   - Download the latest `thirdweb-woocommerce-checkout.zip` from the releases page
+
+2. **Install via WordPress Admin**
+   - Go to **WordPress Admin → Plugins → Add New → Upload Plugin**
+   - Choose the downloaded ZIP file
+   - Click **Install Now**
+   - Click **Activate Plugin**
+
+3. **Create thirdweb Account & Project**
+   - Go to [thirdweb.com/dashboard](https://thirdweb.com/dashboard) to create an account
+   - Create a new project in your dashboard
+   - Copy your **Client ID** from the project settings
+   - Copy your **project wallet address** (this will receive all payments)
+
+4. **Configure Payment Settings**
+   - Navigate to **WooCommerce → Settings → Payments**
+   - Find **Stablecoin Payment** and click **Manage**
+   - Enable the payment method
+   - Enter your **thirdweb Client ID**
+   - Enter your **wallet address** to receive payments
+   - Enter the **Chain ID** for your preferred blockchain (default: 8453 for Base)
+   - Optionally enter the **Token Address** for USDC/USDT on that chain
+   - Save changes
+
+### For Developers
+
+#### 1. Install Dependencies
 
 ```bash
 pnpm install
 ```
 
-### 2. Configure Environment Variables
+#### 2. Configure Environment Variables (Optional)
 
-Copy the example environment file and add your thirdweb Client ID:
+For development convenience, you can use a `.env` file:
 
 ```bash
 cp .env.example .env
@@ -76,26 +105,143 @@ Edit `.env` and add your thirdweb Client ID:
 THIRDWEB_CLIENT_ID=your_client_id_here
 ```
 
-You can get your Client ID from the [thirdweb Dashboard](https://thirdweb.com/dashboard).
+This provides a default value in WooCommerce settings but can be overridden in the admin panel.
+
+#### 3. Build the Plugin
+
+For development:
+```bash
+pnpm run start    # Watch mode
+```
+
+For production:
+```bash
+pnpm run build    # Build once
+```
+
+#### 4. Create Distribution Package
 
-### 3. Build the Plugin
+To create a production-ready ZIP for distribution:
 
 ```bash
-pnpm run build
+pnpm run package
 ```
 
-### 4. Configure in WooCommerce
+This creates `dist/thirdweb-woocommerce-checkout.zip` ready for WordPress installation.
+
+## Testing the CheckoutWidget
+
+Before integrating with WordPress, you can test the CheckoutWidget standalone using the React test app.
+
+### Standalone Test App (No WordPress Required)
+
+1. **Navigate to the test app**:
+   ```bash
+   cd test-app
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pnpm install
+   ```
+
+3. **Configure your credentials**:
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` with your credentials:
+   ```env
+   VITE_THIRDWEB_CLIENT_ID=your_client_id_here
+   VITE_SELLER_WALLET=0xYourWalletAddress
+   VITE_CHAIN_ID=8453
+   VITE_TOKEN_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+   VITE_AMOUNT=10.00
+   ```
+
+   **Get your credentials**:
+   - **Client ID**: From [thirdweb.com/dashboard](https://thirdweb.com/dashboard)
+   - **Wallet Address**: Your project wallet address from thirdweb dashboard
+   - **Token Address** (optional): USDC on Base `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` or leave empty for native ETH
+
+4. **Run the test app**:
+   ```bash
+   pnpm dev
+   ```
+
+   The app will automatically open at `http://localhost:3000`
+
+5. **Test the payment flow**:
+   - The CheckoutWidget loads with your configuration
+   - Connect your wallet (MetaMask, Coinbase Wallet, etc.) or pay with card
+   - Complete a test payment
+   - Transaction hash appears on success with block explorer link
+   - Verify the transaction on [BaseScan](https://basescan.org)
+
+See `test-app/README.md` for more details.
+
+### Local WordPress Testing
+
+After verifying the CheckoutWidget works standalone, test the full plugin integration:
+
+1. **Install WordPress locally** using one of these options:
+   - [LocalWP](https://localwp.com/) (recommended)
+   - [MAMP](https://www.mamp.info/)
+   - Docker with [docker-wordpress](https://hub.docker.com/_/wordpress)
+
+2. **Install WooCommerce**:
+   ```
+   WordPress Admin → Plugins → Add New → Search "WooCommerce" → Install & Activate
+   ```
+
+3. **Link the plugin** to your WordPress installation:
+
+   **Option A: Symlink (recommended for development)**
+   ```bash
+   # LocalWP example:
+   ln -s $(pwd) ~/Local\ Sites/YOUR_SITE/app/public/wp-content/plugins/thirdweb-woocommerce-checkout
+
+   # MAMP example:
+   ln -s $(pwd) /Applications/MAMP/htdocs/wordpress/wp-content/plugins/thirdweb-woocommerce-checkout
+   ```
+
+   **Option B: Copy files**
+   ```bash
+   cp -r $(pwd) ~/Local\ Sites/YOUR_SITE/app/public/wp-content/plugins/thirdweb-woocommerce-checkout
+   ```
+
+4. **Activate the plugin**:
+   - Go to **WordPress Admin → Plugins**
+   - Find "thirdweb Stablecoin Checkout for WooCommerce"
+   - Click **Activate**
+
+5. **Configure payment settings**:
+   - Navigate to **WooCommerce → Settings → Payments**
+   - Click **Manage** next to "Stablecoin Payment"
+   - Enter your Client ID, wallet address, chain ID, and token address
+   - Save changes
+
+6. **Create a test product and complete checkout**:
+   - Create a simple product in WooCommerce
+   - Add it to cart and proceed to checkout
+   - Select "Pay with Stablecoin" as payment method
+   - Complete the payment flow
 
-1. Go to **WooCommerce → Settings → Payments**
-2. Find **Stablecoin Payment** and click **Manage**
-3. Enable the payment method
-4. Enter your configuration (Client ID will be pre-filled from `.env` if set)
-5. Save changes
+### Common Token Addresses (Mainnet)
+
+| Chain | Chain ID | USDC | Native Token |
+|-------|----------|------|--------------|
+| Base | 8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ETH |
+| Ethereum | 1 | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | ETH |
+| Arbitrum | 42161 | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | ETH |
+| Polygon | 137 | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | MATIC |
+| Optimism | 10 | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` | ETH |
 
 ## How It Works
 
 1. **Customer selects "Pay with Stablecoin"** at checkout
 2. **CheckoutWidget renders** with order total and merchant wallet
 3. **Customer connects wallet** (or pays with card via thirdweb)
-4. **Payment completes on-chain** → thirdweb webhook fires
-5. **PHP verifies transaction** and marks order complete
+4. **Payment completes on-chain** → CheckoutWidget fires `onSuccess` callback
+5. **Transaction hash captured** and passed to WooCommerce
+6. **PHP verifies transaction** on-chain via RPC and marks order complete

demo/checkout-mockup.html

@@ -641,7 +641,7 @@ <h2>Order Summary</h2>
             </button>
 
             <p style="text-align: center; margin-top: 16px; font-size: 12px; color: #666;">
-                🔒 Secure checkout powered by thirdweb
+                🔒 Secure stablecoin checkout powered by thirdweb
             </p>
         </div>
     </div>

includes/class-thirdweb-payment-gateway.php

@@ -39,7 +39,6 @@ public function __construct() {
         $this->seller_wallet  = $this->get_option('seller_wallet');
         $this->chain_id       = $this->get_option('chain_id');
         $this->token_address  = $this->get_option('token_address');
-        $this->webhook_secret = $this->get_option('webhook_secret');
 
         // Save settings hook
         add_action('woocommerce_update_options_payment_gateways_' . $this->id, [$this, 'process_admin_options']);
@@ -72,42 +71,45 @@ public function init_form_fields() {
             'client_id' => [
                 'title'       => __('thirdweb Client ID', 'thirdweb-wc'),
                 'type'        => 'text',
-                'description' => __('Your thirdweb Client ID from the dashboard. Can also be set via .env file as THIRDWEB_CLIENT_ID.', 'thirdweb-wc'),
+                'description' => sprintf(
+                    __('Get your Client ID from <a href="%s" target="_blank">thirdweb Dashboard</a>. Create a new project if you haven\'t already. Can also be set via .env file for development.', 'thirdweb-wc'),
+                    'https://thirdweb.com/dashboard'
+                ),
                 'default'     => thirdweb_wc_get_env('THIRDWEB_CLIENT_ID', ''),
-                'desc_tip'    => true,
+                'placeholder' => __('e.g., abc123def456...', 'thirdweb-wc'),
             ],
             'seller_wallet' => [
                 'title'       => __('Seller Wallet Address', 'thirdweb-wc'),
                 'type'        => 'text',
-                'description' => __('Wallet address to receive payments', 'thirdweb-wc'),
+                'description' => sprintf(
+                    __('Your project wallet address that will receive all payments. Get this from your <a href="%s" target="_blank">thirdweb project dashboard</a>.', 'thirdweb-wc'),
+                    'https://thirdweb.com/dashboard'
+                ),
                 'default'     => '',
-                'desc_tip'    => true,
+                'placeholder' => __('0x...', 'thirdweb-wc'),
+                'custom_attributes' => [
+                    'pattern' => '^0x[a-fA-F0-9]{40}$',
+                ],
             ],
             'chain_id' => [
-                'title'       => __('Blockchain Network', 'thirdweb-wc'),
-                'type'        => 'select',
-                'description' => __('Select the blockchain to receive payments on', 'thirdweb-wc'),
+                'title'       => __('Chain ID', 'thirdweb-wc'),
+                'type'        => 'text',
+                'description' => sprintf(
+                    __('The blockchain network chain ID to receive payments on. Default is 8453 (Base). Common chains: 1 (Ethereum), 8453 (Base), 137 (Polygon), 42161 (Arbitrum), 10 (Optimism). See <a href="%s" target="_blank">chainlist.org</a> for more chains.', 'thirdweb-wc'),
+                    'https://chainlist.org'
+                ),
                 'default'     => '8453', // Base
-                'options'     => [
-                    '1'     => 'Ethereum Mainnet',
-                    '8453'  => 'Base',
-                    '42161' => 'Arbitrum One',
-                    '137'   => 'Polygon',
-                    '10'    => 'Optimism',
+                'placeholder' => __('8453', 'thirdweb-wc'),
+                'custom_attributes' => [
+                    'pattern' => '[0-9]+',
                 ],
             ],
             'token_address' => [
                 'title'       => __('Token Address (Optional)', 'thirdweb-wc'),
                 'type'        => 'text',
-                'description' => __('USDC/USDT contract address. Leave empty to accept native token (ETH).', 'thirdweb-wc'),
+                'description' => __('USDC/USDT contract address for the chain above. Make sure the token address matches your selected chain. Leave empty to accept the native token (ETH, MATIC, etc.). Default is USDC on Base (chain 8453).', 'thirdweb-wc'),
                 'default'     => '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
-                'desc_tip'    => true,
-            ],
-            'webhook_secret' => [
-                'title'       => __('Webhook Secret', 'thirdweb-wc'),
-                'type'        => 'password',
-                'description' => __('Secret key for verifying webhook signatures', 'thirdweb-wc'),
-                'default'     => '',
+                'placeholder' => __('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', 'thirdweb-wc'),
             ],
         ];
     }
@@ -214,18 +216,6 @@ private function verify_transaction($tx_hash, $order) {
         return true;
     }
 
-    /**
-     * Verify webhook signature
-     */
-    public function verify_webhook_signature($payload, $signature) {
-        if (empty($this->webhook_secret)) {
-            return true; // Skip if not configured
-        }
-
-        $expected = hash_hmac('sha256', json_encode($payload), $this->webhook_secret);
-        return hash_equals($expected, $signature);
-    }
-
     /**
      * Get config for frontend
      */

package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "build": "wp-scripts build src/checkout-block/index.tsx --output-path=build",
     "start": "wp-scripts start src/checkout-block/index.tsx --output-path=build",
+    "package": "pnpm run build && bash scripts/package.sh",
     "check-engines": "wp-scripts check-engines",
     "check-licenses": "wp-scripts check-licenses",
     "lint:js": "wp-scripts lint-js",