Skip to content

Commit a6dd87d

Browse files
eabdelmoneimeabdelmoneim
committed
initial commit
0 parents  commit a6dd87d

19 files changed

Lines changed: 23020 additions & 0 deletions

‎.env.example‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# thirdweb Configuration
2+
# Copy this file to .env and fill in your values
3+
4+
# Your thirdweb Client ID from the dashboard
5+
# Get it from: https://thirdweb.com/dashboard
6+
THIRDWEB_CLIENT_ID=your_client_id_here

‎.gitignore‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Dependencies
2+
node_modules/
3+
vendor/
4+
5+
# Build output
6+
build/
7+
dist/
8+
9+
# Environment variables
10+
.env
11+
.env.local
12+
.env.*.local
13+
14+
# IDE
15+
.vscode/
16+
.idea/
17+
*.swp
18+
*.swo
19+
*~
20+
21+
# OS
22+
.DS_Store
23+
Thumbs.db
24+
25+
# Logs
26+
*.log
27+
npm-debug.log*
28+
pnpm-debug.log*
29+
30+
# WordPress
31+
wp-config.php
32+

‎.npmrc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Use pnpm as the package manager
2+
# The packageManager field in package.json is the primary way to specify this,
3+
# but this file helps ensure consistency across tools
4+

‎CLAUDE.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# WooCommerce thirdweb Stablecoin Checkout Plugin
2+
3+
## Project Overview
4+
5+
A WordPress/WooCommerce plugin that adds stablecoin payment support (USDC, USDT) using thirdweb's CheckoutWidget React component.
6+
7+
## Architecture
8+
9+
```
10+
┌─────────────────────────────────────────────────────────────────┐
11+
│ WooCommerce Checkout Page │
12+
│ ┌───────────────────────────────────────────────────────────┐ │
13+
│ │ Payment Methods │ │
14+
│ │ ○ Credit Card │ │
15+
│ │ ○ PayPal │ │
16+
│ │ ● Pay with Stablecoin ← Our Plugin │ │
17+
│ │ └─► CheckoutWidget (React) renders here │ │
18+
│ └───────────────────────────────────────────────────────────┘ │
19+
└─────────────────────────────────────────────────────────────────┘
20+
│
21+
┌───────────────┴───────────────┐
22+
▼ ▼
23+
PHP Gateway thirdweb Webhook
24+
(WC_Payment_Gateway) (payment confirmation)
25+
```
26+
27+
## Key Files
28+
29+
| File | Purpose |
30+
|------|---------|
31+
| `thirdweb-woocommerce-checkout.php` | Main plugin entry, registers gateway & webhook endpoint |
32+
| `includes/class-thirdweb-payment-gateway.php` | WC_Payment_Gateway extension with admin settings |
33+
| `includes/class-thirdweb-blocks-support.php` | Enables React-based checkout blocks support |
34+
| `src/checkout-block/index.tsx` | Registers payment method with `@woocommerce/blocks-registry` |
35+
| `src/checkout-block/ThirdwebCheckout.tsx` | Wraps thirdweb CheckoutWidget with WC integration |
36+
37+
## Tech Stack
38+
39+
- **PHP 7.4+**: WordPress plugin backend
40+
- **WooCommerce 8.0+**: Payment gateway API
41+
- **React/TypeScript**: Frontend checkout widget
42+
- **@wordpress/scripts**: Build tooling (Webpack)
43+
- **thirdweb SDK v5**: CheckoutWidget component
44+
45+
## Payment Flow
46+
47+
1. Customer selects "Pay with Stablecoin" at checkout
48+
2. `ThirdwebCheckout.tsx` renders the CheckoutWidget with order total
49+
3. Customer connects wallet (MetaMask/Coinbase/WalletConnect) or pays with card
50+
4. Payment completes on-chain → thirdweb webhook fires to `/wp-json/thirdweb-wc/v1/webhook`
51+
5. PHP verifies transaction and marks WooCommerce order complete
52+
53+
## Build Commands
54+
55+
```bash
56+
pnpm install # Install dependencies
57+
pnpm run build # Production build → /build/checkout-block.js
58+
pnpm run start # Development watch mode
59+
```
60+
61+
## Environment Configuration
62+
63+
The plugin supports configuration via a `.env` file for development convenience:
64+
65+
1. Copy `.env.example` to `.env`:
66+
```bash
67+
cp .env.example .env
68+
```
69+
70+
2. Add your thirdweb Client ID:
71+
```env
72+
THIRDWEB_CLIENT_ID=your_client_id_here
73+
```
74+
75+
The Client ID from `.env` will be used as a default value in the WooCommerce admin settings. You can override it in the admin panel if needed.
76+
77+
## Configuration (WooCommerce Admin)
78+
79+
Settings at: WooCommerce → Settings → Payments → Stablecoin Payment
80+
81+
- **thirdweb Client ID**: From thirdweb dashboard
82+
- **Seller Wallet**: Address to receive payments
83+
- **Blockchain Network**: Base, Ethereum, Arbitrum, Polygon, Optimism
84+
- **Token Address**: USDC/USDT contract (optional, defaults to native token)
85+
- **Webhook Secret**: For verifying webhook signatures
86+
87+
## CheckoutWidget Props Reference
88+
89+
```tsx
90+
<CheckoutWidget
91+
client={client} // thirdweb client instance
92+
chain={chain} // Target chain (e.g., Base)
93+
amount="149.99" // Order total as string
94+
seller="0x..." // Merchant wallet address
95+
tokenAddress="0x..." // USDC/USDT contract (optional)
96+
paymentMethods={['crypto', 'card']} // Enabled payment methods
97+
onSuccess={handleSuccess} // Success callback
98+
onError={handleError} // Error callback
99+
onCancel={handleCancel} // Cancel callback
100+
purchaseData={{ orderId, source }} // Passed to webhook for order matching
101+
theme="light" // UI theme
102+
supportedTokens={{...}} // Tokens users can pay with
103+
/>
104+
```
105+
106+
## Common Token Addresses
107+
108+
| Chain | USDC | USDT |
109+
|-------|------|------|
110+
| Base (8453) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | - |
111+
| Ethereum (1) | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | `0xdAC17F958D2ee523a2206206994597C13D831ec7` |
112+
| Arbitrum (42161) | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9` |
113+
| Polygon (137) | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | `0xc2132D05D31c914a87C6611C10748AEb04B58e8F` |
114+
115+
## Development Notes
116+
117+
- WooCommerce checkout blocks use React on frontend (not PHP server-rendered)
118+
- `@woocommerce/blocks-registry` provides `registerPaymentMethod()` API
119+
- `getSetting('thirdweb_stablecoin_data')` retrieves PHP config in React
120+
- Webhook endpoint must be publicly accessible for thirdweb to call
121+
- Transaction verification happens server-side via RPC for security
122+
123+
## TODO
124+
125+
- [ ] Add refund support via thirdweb API
126+
- [ ] Implement proper webhook signature verification
127+
- [ ] Add transaction receipt email with block explorer link
128+
- [ ] Support multiple tokens per checkout
129+
- [ ] Add test mode toggle for testnet payments

‎README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# WooCommerce Stablecoin Checkout with thirdweb CheckoutWidget
2+
3+
A WordPress/WooCommerce plugin that adds stablecoin payment support using thirdweb's CheckoutWidget.
4+
5+
## Architecture Overview
6+
7+
```
8+
┌─────────────────────────────────────────────────────────────────────┐
9+
│ WooCommerce Checkout Page │
10+
├─────────────────────────────────────────────────────────────────────┤
11+
│ │
12+
│ ┌─────────────────────────────────────────────────────────────┐ │
13+
│ │ Payment Methods │ │
14+
│ │ ○ Credit Card │ │
15+
│ │ ○ PayPal │ │
16+
│ │ ● Pay with Stablecoin (USDC/USDT) ← Our Plugin │ │
17+
│ └─────────────────────────────────────────────────────────────┘ │
18+
│ │ │
19+
│ ▼ │
20+
│ ┌─────────────────────────────────────────────────────────────┐ │
21+
│ │ thirdweb CheckoutWidget (React) │ │
22+
│ │ ┌─────────────────────────────────────────────────────┐ │ │
23+
│ │ │ 💳 Pay $50.00 │ │ │
24+
│ │ │ │ │ │
25+
│ │ │ Connect Wallet / Pay with: │ │ │
26+
│ │ │ [MetaMask] [Coinbase] [WalletConnect] │ │ │
27+
│ │ │ │ │ │
28+
│ │ │ Or pay with card 💳 │ │ │
29+
│ │ │ │ │ │
30+
│ │ │ Supported: USDC, USDT on Base, Ethereum, etc. │ │ │
31+
│ │ └─────────────────────────────────────────────────────┘ │ │
32+
│ └─────────────────────────────────────────────────────────────┘ │
33+
│ │
34+
└─────────────────────────────────────────────────────────────────────┘
35+
```
36+
37+
## Plugin Structure
38+
39+
```
40+
thirdweb-woocommerce-checkout/
41+
├── thirdweb-woocommerce-checkout.php # Main plugin file
42+
├── includes/
43+
│ ├── class-thirdweb-payment-gateway.php # WC_Payment_Gateway
44+
│ └── class-thirdweb-blocks-support.php # Block checkout support
45+
├── src/
46+
│ └── checkout-block/
47+
│ ├── index.tsx # React entry point
48+
│ └── ThirdwebCheckout.tsx # CheckoutWidget wrapper
49+
├── build/ # Compiled JS (gitignored)
50+
├── .env.example # Environment variables template
51+
├── .env # Your environment variables (create from .env.example)
52+
├── package.json
53+
├── tsconfig.json
54+
└── webpack.config.js
55+
```
56+
57+
## Installation & Setup
58+
59+
### 1. Install Dependencies
60+
61+
```bash
62+
pnpm install
63+
```
64+
65+
### 2. Configure Environment Variables
66+
67+
Copy the example environment file and add your thirdweb Client ID:
68+
69+
```bash
70+
cp .env.example .env
71+
```
72+
73+
Edit `.env` and add your thirdweb Client ID:
74+
75+
```env
76+
THIRDWEB_CLIENT_ID=your_client_id_here
77+
```
78+
79+
You can get your Client ID from the [thirdweb Dashboard](https://thirdweb.com/dashboard).
80+
81+
### 3. Build the Plugin
82+
83+
```bash
84+
pnpm run build
85+
```
86+
87+
### 4. Configure in WooCommerce
88+
89+
1. Go to **WooCommerce → Settings → Payments**
90+
2. Find **Stablecoin Payment** and click **Manage**
91+
3. Enable the payment method
92+
4. Enter your configuration (Client ID will be pre-filled from `.env` if set)
93+
5. Save changes
94+
95+
## How It Works
96+
97+
1. **Customer selects "Pay with Stablecoin"** at checkout
98+
2. **CheckoutWidget renders** with order total and merchant wallet
99+
3. **Customer connects wallet** (or pays with card via thirdweb)
100+
4. **Payment completes on-chain** → thirdweb webhook fires
101+
5. **PHP verifies transaction** and marks order complete

0 commit comments

Comments
 (0)