Chấp Nhận Monero trên WooCommerce: Hướng Dẫn Tích Hợp

Why Accept Monero on Your WooCommerce Store

Accepting Monero (XMR) as a payment method on your WooCommerce store opens your business to a growing community of privacy-conscious cryptocurrency users. Unlike credit card payments that carry 2-4% processing fees and chargeback risks, Monero transactions are irreversible, carry minimal fees (typically under $0.01), and settle in approximately 2 minutes. This guide walks you through three approaches to integrating Monero payments into WooCommerce: using MoneroPay, leveraging BTCPay Server with XMR support, and building a custom payment gateway plugin.

Prerequisites and Architecture Overview

Before beginning the integration, ensure you have the following:

• WordPress 6.0+ with WooCommerce 8.0+ installed and configured.
• A Monero wallet with view key access. For automated payment detection, you will need either a Monero wallet RPC instance or a view-only wallet.
• VPS or dedicated server capable of running a Monero daemon (monerod) and wallet RPC. Minimum recommended specifications: 2 CPU cores, 4 GB RAM, 150 GB SSD storage for the pruned blockchain.
• SSL certificate on your WooCommerce store (required for webhook security).

Payment Flow Architecture

The general flow for Monero payments in WooCommerce follows this pattern:

• Customer selects Monero at checkout and clicks "Place Order."
• Your payment gateway generates a unique subaddress for the order using the wallet RPC or payment processor API.
• The customer is shown the payment address and amount in XMR (converted from the fiat price using a real-time exchange rate).
• A background process monitors the Monero blockchain for incoming transactions to the generated subaddress.
• Once the payment is confirmed (typically 10 confirmations, approximately 20 minutes), the order status is updated to "Processing" and the merchant is notified.

Option 1: MoneroPay Integration

MoneroPay is a lightweight, self-hosted Monero payment processor designed specifically for merchant integrations. It handles subaddress generation, payment monitoring, exchange rate conversion, and webhook notifications.

Setting Up MoneroPay

First, install MoneroPay on your server. MoneroPay requires a running monerod instance and provides a REST API for payment operations:

Step 1: Clone the MoneroPay repository and build it. MoneroPay is written in Go and compiles to a single binary. Configure it to connect to your local monerod instance and provide your wallet's primary address and private view key. The configuration file specifies the RPC host, RPC port, wallet address, view key, and the number of required confirmations.

Step 2: Start MoneroPay and verify it connects to your Monero daemon. The API will be available on the configured port (default 5000). Test the health endpoint to confirm everything is working.

Step 3: Install the MoneroPay WooCommerce plugin. This plugin adds "Monero (XMR)" as a payment option in WooCommerce and communicates with your MoneroPay instance via its REST API.

Configuring the WooCommerce Plugin

Navigate to WooCommerce > Settings > Payments and enable the MoneroPay gateway. Configure the following settings:

• MoneroPay API URL: The URL where your MoneroPay instance is running (e.g., https://pay.yourdomain.com).
• API Secret: The shared secret for webhook verification.
• Confirmations required: Number of block confirmations before marking payment as complete (recommended: 10).
• Exchange rate source: Select from CoinGecko, Kraken, or Binance for XMR/fiat conversion.
• Payment timeout: How long (in minutes) to wait for payment before expiring the order (recommended: 60).

Webhook Handling

MoneroPay sends webhook notifications to your WooCommerce store when payment events occur. The webhook handler must verify the HMAC signature, parse the payment status, and update the WooCommerce order accordingly. The webhook payload includes the order ID, payment status (pending, confirming, confirmed, expired), the amount received, the number of confirmations, and a transaction hash. Your handler should verify the HMAC-SHA256 signature using the shared secret, then use a switch statement on the payment status to either mark the order as on-hold (for pending), add an order note with the confirmation count (for confirming), mark payment as complete (for confirmed), or cancel the order (for expired payments).

Option 2: BTCPay Server with Monero Support

BTCPay Server is a mature, self-hosted payment processor that supports Monero through its altcoin plugin system. This is an excellent choice if you already run BTCPay Server for Bitcoin payments or want a battle-tested solution with a rich admin interface.

Enabling Monero on BTCPay Server

Step 1: If you are deploying a new BTCPay Server instance, enable the Monero plugin during setup by setting the appropriate environment variable (BTCPAY_INCLUDE_XMR=1) before running the deployment script.

Step 2: For existing BTCPay Server installations, you can add Monero support by modifying the docker fragment configuration. After updating the configuration, restart the BTCPay Server stack. The Monero daemon and wallet will sync with the network, which may take several hours on first run.

Step 3: In the BTCPay Server admin panel, navigate to your store settings, then "Wallets," and configure the Monero wallet. You can either use the built-in wallet or connect to an external Monero wallet RPC instance.

WooCommerce Integration via BTCPay Plugin

Install the official BTCPay Server WooCommerce plugin from the WordPress plugin directory. Configure it with your BTCPay Server URL and API key. The plugin automatically handles Monero payments when XMR is enabled on your BTCPay Server store. Customers will see both Bitcoin and Monero payment options at checkout, and can choose their preferred cryptocurrency.

Option 3: Custom Payment Gateway Plugin

For maximum control over the payment flow, you can build a custom WooCommerce payment gateway that communicates directly with the Monero wallet RPC. This approach eliminates the need for an intermediate payment processor but requires more development effort.

Plugin Structure

A custom Monero payment gateway extends the WC_Payment_Gateway class and implements the core payment processing methods. The main class constructor sets the gateway ID, icon, method title and description, and initializes form fields and settings including the wallet RPC host and port, the number of required confirmations, and the exchange rate API endpoint.

Subaddress Generation

For each order, generate a unique Monero subaddress using the wallet RPC create_address method. This function makes a JSON-RPC call to the Monero wallet, specifying account index 0 and using the order ID as a label. It returns the newly created subaddress and its index, which you then store as order metadata for later payment verification.

Payment Monitoring with WP-Cron

Set up a WP-Cron job that runs every 2 minutes to check for incoming payments on pending orders. The monitoring function queries WooCommerce for orders with "pending" status and the Monero payment method, then for each order retrieves the stored subaddress index and calls the wallet RPC get_transfers method to check for incoming transfers. When a transfer is found with sufficient confirmations, the function completes the payment and updates the order status.

Exchange Rate Handling

Convert the order total from fiat to XMR using a reliable exchange rate API. Cache the rate for 60 seconds to avoid excessive API calls while keeping the price relatively current. The function checks for a cached rate in WordPress transients first, and if not found, fetches the current rate from the CoinGecko API for the appropriate fiat currency, caches it, and returns the converted amount.

Refund Flow

Monero refunds cannot be automated through the blockchain since transactions are one-way and irreversible. Implement a manual refund workflow where the admin initiates a refund through WooCommerce, the customer is prompted to provide a Monero address for the refund via an email notification, and the merchant sends the refund manually from their wallet. The process_refund method in your gateway should record the refund amount and send a notification email to the customer requesting their XMR refund address, then return true to mark the WooCommerce refund as pending.

Security Best Practices

When accepting Monero payments, follow these security guidelines to protect both your business and your customers:

• Use view-only wallets for payment detection: The wallet connected to your WooCommerce store should be a view-only wallet (created with the primary address and view key only). Keep the spend key offline. This way, even if your server is compromised, the attacker cannot steal funds.
• Run your own Monero node: Do not rely on remote nodes for payment verification. A compromised remote node could report fake transactions or withhold legitimate ones. Running your own monerod instance ensures you have accurate blockchain data.
• Secure webhook endpoints: Always verify HMAC signatures on incoming webhooks. Use HTTPS and restrict webhook source IPs if possible.
• Handle exchange rate volatility: XMR/fiat rates can move significantly during the payment window. Consider setting a tolerance of 1-2% below the exact required amount to account for exchange rate fluctuations between when the customer sees the price and when they send the payment.
• Monitor for underpayments: Implement logic to detect partial payments and notify the customer to send the remaining balance rather than silently failing the order.

Testing Your Integration

Before going live, thoroughly test your Monero payment integration using the Monero stagenet. Stagenet is a separate Monero network designed for testing, where coins have no real value. Configure monerod and your wallet RPC to run on stagenet by adding the appropriate flag. Update your payment gateway configuration to point to the stagenet RPC instance. Create test orders and verify the complete payment flow from order creation through subaddress generation, payment detection, confirmation waiting, and order completion.

Conclusion

Accepting Monero on your WooCommerce store is a practical way to offer customers a private, low-fee payment option while eliminating chargeback fraud. Whether you choose the simplicity of MoneroPay, the robustness of BTCPay Server, or the flexibility of a custom gateway, the integration is well within reach for any WordPress developer. For customers looking to acquire Monero to spend at your store, MoneroSwapper provides a fast, KYC-free exchange service that makes obtaining XMR straightforward.