Beep Pay for WooCommerce

Accept USDC stablecoin payments via Beep Pay on WooCommerce. Supports QR code and direct wallet payments on the Sui blockchain.

✨ Features

Core Payment Features

• Accept USDC payments - Customers can pay with stablecoins on Sui
• QR Code support - Scan and pay with any Sui-compatible wallet
• Direct wallet connection - "Pay with Wallet" button opens wallet directly
• Real-time payment detection - Automatic payment verification and order completion
• Multi-currency exchange rate - Configure your own store currency to USDC rate

Checkout Integration

• Classic checkout support - Seamlessly integrated with WooCommerce classic checkout
• Cart page button - Quick checkout option directly from cart
• Mini cart widget - Payment option in mini cart sidebar
• USDC total display - Shows equivalent USDC amount at checkout

Admin Features

• Onboarding wizard - Step-by-step setup for first-time users
• Dedicated settings page - Centralized configuration under Beep Pay menu
• Order meta box - View payment details on order edit page
• Manual payment verification - Verify on-chain payments for pending orders
• Wallet balance display - View merchant wallet USDC balance in admin
• Debug logging - Comprehensive logging for troubleshooting

On-Chain Verification

• Sui RPC integration - Direct on-chain payment verification
• Payment Kit registry - Verify payments via Sui Payment Kit
• Transaction verification - Validate transaction digests directly
• Multi-method validation - Invoice API, Widget API, and on-chain fallback

Theming

• Light theme - Clean, bright payment interface
• Dark theme - Modern dark mode support
• Custom theme - Disable default themes for custom CSS
• Responsive design - Mobile-friendly payment page

📦 Installation

From WordPress Admin

1. Download the plugin ZIP file
2. Go to Plugins → Add New → Upload Plugin
3. Choose the ZIP file and click Install Now
4. Activate the plugin

Manual Installation

1. Upload the beep-pay-woocommerce folder to /wp-content/plugins/
2. Activate the plugin through the Plugins menu in WordPress
3. Complete the onboarding wizard, or go to Beep Pay → Settings to configure

⚙️ Configuration

Quick Setup (Onboarding Wizard)

When first activating the plugin, you'll be guided through an onboarding wizard:

1. API Keys - Enter your Beep Pay Publishable Key
2. Exchange Rate - Set your currency to USDC exchange rate
3. Display Settings - Choose theme and customize appearance
4. Test Payment - Verify everything works correctly

Settings Reference

API Settings

Setting	Description	Example
Publishable Key	Your Beep Pay publishable key (required)	beep_pk_...
Secret Key	For advanced server-side features (optional)	beep_sk_...
API Base URL	Beep Pay API endpoint	https://api.justbeep.it

Payment Settings

Setting	Description	Default
Title	Payment method title at checkout	Beep Pay (USDC)
Description	Payment method description	Pay with USDC on Sui
Exchange Rate	Store currency to USDC rate	27000 (for VND)

Display Settings

Setting	Description	Options
Theme	Payment page theme	Light, Dark, None
Poll Interval	Payment status check interval	3000 ms
Timeout	Maximum payment wait time	15 minutes

Advanced Settings

Setting	Description
Debug Log	Enable detailed logging for troubleshooting
Sui RPC URL	Custom Sui RPC endpoint (filterable)

🔄 How It Works

Payment Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                         Customer Checkout Flow                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   1. Customer adds items to cart                                        │
│          ↓                                                              │
│   2. Proceeds to checkout                                               │
│          ↓                                                              │
│   3. Selects "Beep Pay (USDC)" as payment method                       │
│          ↓                                                              │
│   4. Places order → Order created with "Pending" status                │
│          ↓                                                              │
│   5. Redirected to payment page showing:                               │
│      • Amount in USDC                                                   │
│      • QR code (scan with any Sui wallet)                              │
│      • "Pay with Wallet" button                                         │
│      • Countdown timer                                                  │
│          ↓                                                              │
│   6. Plugin polls for payment status                                    │
│          ↓                                                              │
│   7. Payment detected → Order status → "Processing"                    │
│          ↓                                                              │
│   8. Customer redirected to Thank You page                             │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Payment Verification Methods

The plugin uses multiple verification methods in order:

1. Invoice API - GET /v1/invoices/{invoiceId}
2. Widget API - GET /v1/widget/payment-status/{referenceKey}
3. On-Chain Verification - Query Sui Payment Kit registry directly

🛠️ Development

Project Structure

beep-pay-woocommerce/
├── beep-pay-woocommerce.php    # Main plugin file
├── includes/
│   ├── class-wc-gateway-beep-pay.php    # WooCommerce gateway
│   ├── class-beep-pay-api-client.php    # Beep API client
│   ├── class-beep-pay-rest-api.php      # REST API endpoints
│   ├── class-beep-pay-admin.php         # Admin settings
│   └── class-beep-pay-onboarding.php    # Setup wizard
├── assets/
│   ├── css/
│   │   ├── beep-pay.css       # Main styles
│   │   ├── admin.css          # Admin styles
│   │   ├── onboarding.css     # Wizard styles
│   │   └── themes/
│   │       ├── light.css      # Light theme
│   │       └── dark.css       # Dark theme
│   ├── js/                    # JavaScript files
│   ├── src/                   # Source TypeScript files
│   └── images/                # Plugin images
├── templates/
│   └── admin/
│       └── onboarding/        # Onboarding wizard templates
├── docs/                      # Documentation

Build Assets

cd wp-content/plugins/beep-pay-woocommerce
pnpm install
pnpm build

Watch Mode (Development)

pnpm dev

🔌 API Reference

REST Endpoints

Endpoint	Method	Description
/wp-json/beep-pay/v1/session	POST	Create payment session
/wp-json/beep-pay/v1/status	GET	Check payment status
/wp-json/beep-pay/v1/confirm	POST	Confirm payment
/wp-json/beep-pay/v1/order-status	GET	Check if order can be paid
/wp-json/beep-pay/v1/wallet-balance	GET	Get merchant wallet balance (admin)
/wp-json/beep-pay/v1/admin/invoice-history	POST	Add invoice to order history (admin)

Order Meta

The plugin stores the following order meta:

Meta Key	Description
_beep_reference_key	Unique payment reference key
_beep_payment_url	Payment URL for wallet redirect
_beep_qr_code	QR code image URL
_beep_expires_at	Session expiration timestamp
_beep_amount_usdc	Amount in USDC
_beep_rate	Exchange rate used
_beep_invoice_id	Beep Invoice ID
_beep_tx_digest	Sui transaction digest
_beep_invoice_ids	Historical invoice IDs (JSON array)

WordPress Filters

// Customize Sui RPC URL
add_filter('beep_pay_sui_rpc_url', function($url) {
    return 'https://your-custom-rpc.com';
});

// Customize Payment Kit Package ID
add_filter('beep_pay_payment_kit_package_id', function($id) {
    return 'your_package_id';
});

// Customize Payment Registry Object ID
add_filter('beep_pay_payment_registry_object_id', function($id) {
    return 'your_registry_id';
});

📋 Requirements

Requirement	Version
WordPress	5.8+
WooCommerce	5.0+
PHP	7.4+
WC tested up to	8.4

Compatibility

• ✅ WooCommerce HPOS (High-Performance Order Storage)
• ✅ Classic Checkout
• ✅ Mobile browsers
• ✅ All major Sui wallets

🔒 Security

• All API keys are sanitized and stored securely
• Nonce verification on all AJAX requests
• Capability checks for admin endpoints
• Input sanitization and output escaping

🐛 Troubleshooting

Enable Debug Mode

1. Go to Beep Pay → Settings
2. Enable Debug Log
3. Check wp-content/plugins/beep-pay-woocommerce/beep-pay-debug.log

Common Issues

Issue	Solution
Payment not detected	Enable debug log, check RPC connectivity
QR code not showing	Verify Publishable Key is correct
Exchange rate wrong	Check exchange rate in settings
Order stuck on pending	Use admin "Verify On-Chain" action

📚 Documentation

• Beep Pay Documentation
• Beep Pay Developer Guide
• Sui Blockchain

🤝 Support

For support and questions:

• 📧 Email: admin@justbeep.it
• 📖 Docs: documentation.justbeep.it
• 🐦 Twitter: @BeepPay

📜 License

This plugin is licensed under GPL-2.0+. See LICENSE for details.

---

Made with ❤️ by Beep Pay