Skip to main content

How to accept BTC, BCH and XMR in WooCommerce

Connect Manatee to your WooCommerce store and start accepting BTC, BCH and XMR directly to your own wallets.

No custom payment integration is required. Manatee handles payment monitoring while funds settle directly to your wallets. The plugin renders payment instructions, verifies signed webhooks, and updates WooCommerce orders.

Before you start​

  • WordPress 6.5+, PHP 8.1+, WooCommerce, and HTTPS
  • A Manatee account and Test API key
  • At least one configured Test wallet: BTC, BCH, or XMR
  • A current backup and a staging copy of your store
important

The plugin never needs wallet seeds, private keys, spend keys, or view keys. Wallet configuration happens in the Manatee dashboard; WooCommerce receives only payment details and XMR readiness state.

What you'll do​

Install the official plugin, connect a Test environment, choose assets, verify the webhook endpoint, complete a checkout, review order transitions, then prepare Live mode.

Step 1 — Install the plugin​

Install Manatee Crypto Gateway for WooCommerce from WordPress.org, or upload the release ZIP under Plugins → Add New → Upload Plugin. Activate it.

Expected result
WooCommerce → Settings → Payments lists Crypto via Manatee.

Step 2 — Open gateway settings​

Go to WooCommerce → Settings → Payments → Crypto via Manatee. Keep the payment method disabled until the connection and checkout tests pass.

Step 3 — Select the Test environment​

Choose Test (BTC/BCH Testnet + XMR Stagenet). Keep the API base URL at https://api.manatee-api.io.

BTC/BCH Testnet4 XMR Stagenet

Step 4 — Connect the environment​

Paste the Test Environment API Key and Environment Webhook Secret from the Manatee dashboard. Click Save, refresh and test connection.

Expected result
The read-only connection check succeeds and the settings header shows current plan usage.
warning

Do not copy a Mainnet credential into Test mode or send credentials to the browser. The plugin stores and uses them server-side.

Step 5 — Enable payment assets​

Enable Bitcoin, Bitcoin Cash, and/or Monero. XMR appears at checkout only when the selected environment reports a configured, synchronized view-only receive wallet.

Set asset-specific confirmation targets. BTC and BCH accept 1–6; XMR accepts 10–60. Keep conservative defaults until your fulfillment risk policy is documented.

Step 6 — Verify webhook delivery​

Use the generated endpoint unless routing requires the override:

https://shop.example/wp-json/manatee/v1/webhook

Ensure it is publicly reachable over HTTPS and is not blocked by a cache, maintenance plugin, firewall, or authentication layer. Send a synthetic test event from Manatee.

Expected result
The store accepts the signed event and rejects requests with an invalid signature, stale timestamp, wrong event ID, asset, network, or payment mapping.

Step 7 — Complete a test checkout​

Enable the payment method on the staging store. Create an order, select Pay with crypto, choose an asset, and place the order. Confirm the page shows the exact address, atomic amount, QR code, expiry, network, and payment ID.

Send test-network funds and leave the page open to observe verified polling updates.

Step 8 — Review order transitions​

The default mapping is:

Manatee resultWooCommerce behavior
pendingOrder remains unpaid while payment instructions are active
detectedConfigured detected status, normally On hold
confirmedWooCommerce payment completion; normally Processing
expired / terminal failureConfigured unpaid or failed status
Underpayment / overpaymentStore reconciliation case based on received amount; not a separate Manatee lifecycle status

Cancel a still-pending WooCommerce order and verify the plugin cancels the matching Manatee payment. Detected payments remain available for manual reconciliation.

Step 9 — Switch to Live​

Complete Going to production. Configure independent Mainnet receive wallets in Manatee, select Live, enter the Mainnet API key and webhook secret, re-run the connection test, and make one low-value payment for every enabled asset.

BTC Mainnet BCH Mainnet XMR Mainnet
warning

Switching the WooCommerce selector does not convert test wallets into production wallets. Confirm each Mainnet receive configuration and derived address independently.

Troubleshooting​

Plugin cannot connect​

  • Confirm environment, API base URL, and API key.
  • Save settings before re-running the connection test.
  • Confirm outbound HTTPS from the WordPress host.

XMR is not offered​

  • Verify XMR is enabled in the plugin.
  • Verify the selected environment's XMR wallet is configured, provisioned, and synchronized.
  • Confirm Test returns stagenet and Live returns mainnet; the plugin intentionally rejects a wrong-network readiness response.

Webhook does not update the order​

  • Exclude /wp-json/manatee/v1/webhook from caches and access-control middleware.
  • Compare the plugin environment webhook secret with Manatee.
  • Inspect WooCommerce logs and Manatee delivery attempts.
  • Query the authenticated payment endpoint before changing the order manually.

Checkout reports capacity​

A webhook-enabled payment occupies a plan slot while pending or detected. Cancel an abandoned pending order, wait for a terminal state, or review pricing and limits.

Next steps
Review Security, reconciliation, and the payment lifecycle before opening Live checkout to customers.
Last updated on