Manatee Crypto Gateway for WooCommerce

Manatee adds a non-custodial crypto payment gateway to WooCommerce. Customers choose Bitcoin (BTC), Bitcoin Cash (BCH), or Monero (XMR) within one “Pay with crypto” checkout method. The plugin creates an asset-scoped payment, shows the returned address, exact amount, wallet URI, and local QR code, then updates the order from signed webhook events. Test mode combines BTC/BCH Testnet4 with XMR Stagenet, and XMR is offered only after the selected environment reports a ready view-only receive wallet.

Manatee is non-custodial. The plugin does not hold customer funds, request wallet seeds or spending keys, or run blockchain node logic inside WordPress. BTC, BCH, and XMR are available on their test networks and mainnet. The plugin receives only XMR readiness state, never an address or view key, before displaying it to customers.

The plugin is built for merchants and developers who want to accept supported on-chain crypto payments while keeping checkout, order metadata, and webhook handling inside WordPress.

Features

• One WooCommerce crypto payment method with a clear BTC/BCH/XMR selector.
• Non-custodial flow: no wallet seed, private key, or hosted wallet custody is required by the plugin.
• Test mode with BTC/BCH Testnet4 and XMR Stagenet, plus Live mode for all three Mainnet assets.
• One environment-scoped API key and webhook secret shared by BTC, BCH, and XMR.
• Cached plan allowance and active webhook monitor overview at the top of settings.
• Read-only API connection and usage refresh from the gateway settings screen.
• Asset-specific customer payment screen with address, satoshi or exact piconero amount, wallet URI, local QR code, expiry, and automatic status polling.
• XMR is hidden until the selected environment has a configured, synchronized view-only receive wallet.
• Classic checkout and WooCommerce Checkout Blocks support.
• Signed webhook verification with timestamp and event ID handling.
• Automatic WooCommerce order updates after Manatee payment events.
• Pending Manatee payments are cancelled when the WooCommerce order is cancelled.
• Order metadata for asset, network, payment ID, address, satoshi amount, pricing data, environment, transaction ID, confirmations, status, and expiry.
• WooCommerce logging with secret redaction.
• WooCommerce HPOS compatibility.

How it works

1. A customer selects “Pay with crypto” and chooses BTC, BCH, or a ready XMR option.
2. The plugin sends the WooCommerce order total to Manatee as fiat_amount and fiat_currency.
3. The plugin calls the matching /v1/btc/payments, /v1/bch/payments, or /v1/xmr/payments route.
4. The customer sees asset-specific payment instructions on the order received page.
5. Manatee monitors the payment lifecycle and sends signed webhook events to the shop.
6. The plugin verifies signature, timestamp, event ID, payment ID, asset, network, and order mapping before mutation.
7. WooCommerce order status and Manatee payment metadata are updated automatically.
8. If a pending WooCommerce order is cancelled, the plugin asks Manatee to cancel the pending payment. Payments already detected on-chain are left for manual review.
9. The order received page polls the shop for verified status updates using the WooCommerce order key.

Setup

Before accepting payments, configure the gateway in WooCommerce > Settings > Payments > Crypto via Manatee:

• Environment Mode: choose Test for BTC/BCH Testnet4 plus XMR Stagenet, or Live for BTC/BCH/XMR Mainnet.
• API Base URL: use https://api.manatee-api.io unless Manatee support tells you otherwise.
• Environment API Key: enter one Test or Mainnet key for every enabled asset. The Test key maps XMR to Stagenet and BTC/BCH to Testnet4.
• Bitcoin / Bitcoin Cash: choose which configured assets customers may use.
• Monero: enable it after the selected Test or Live view-only receive wallet is configured and synchronized. The plugin checks network-specific readiness before offering XMR at checkout.
• Environment Webhook Secret: enter the single secret used for BTC, BCH, and XMR events in the selected environment.
• Webhook URL Override: leave empty unless Manatee cannot reach the automatically generated WordPress REST endpoint.
• BTC / BCH / XMR Confirmations Required: configure the confirmation target for each asset. XMR accepts 10–60 confirmations.
• Payment Expiry Minutes: define how long new payment requests remain payable.
• Order Status When Detected: choose the status used when a transaction is seen but not fully confirmed.
• Order Status When Confirmed: choose the fallback status used after confirmation if WooCommerce cannot complete the payment automatically.

The settings header shows remaining monthly confirmed mainnet payments and active webhook monitors by network. “Save, refresh and test connection” persists changed settings before sending a read-only GET /v1/usage request.
The API key and webhook secret fields include reveal controls so an authorized WooCommerce administrator can verify the entered values before saving.

Test mode

Use Test mode with one Test Manatee API key and webhook secret. That credential selects BTC/BCH Testnet4 and XMR Stagenet. Enable each asset only after configuring its receive wallet and wait until the XMR readiness check succeeds. A locally database-re-scoped Regtest credential can likewise be shared by all three assets.

When switching to Live mode, use a mainnet Manatee API key, review the webhook secret, confirm that the webhook URL is reachable from the public internet, and test a low-value payment before opening the payment method to customers.

Privacy / Data Sent to Manatee API

When a customer selects BTC, BCH, or XMR, the plugin sends the WooCommerce fiat amount, currency, webhook URL, required confirmation count, expiry window, underpayment tolerance, and order reference to the corresponding Manatee API route. For XMR, the plugin first reads a minimal API-key-scoped readiness result; it does not receive a view key or wallet address from that check.

The WooCommerce order stores asset, network, Manatee payment ID, payment address, pricing metadata, environment mode, status, transaction ID, confirmations, and expiry. BTC/BCH amounts are stored in satoshis; XMR amounts are stored exactly in piconero.

Webhook events are verified with the X-Manatee-Signature, X-Manatee-Timestamp, and X-Manatee-Event-Id headers before order mutation.

External services

This plugin connects to the Manatee Payment API to create and verify non-custodial BTC, BCH, and XMR payments for WooCommerce orders.

When a customer chooses an asset, the plugin sends the order amount, currency, webhook URL, required confirmations, expiry, tolerance, and reference to the asset-specific API route. The API returns asset, network, payment ID, address, exact atomic amount, exchange-rate metadata, expiry, and status. BTC/BCH use satoshis; XMR uses piconero.

The settings screen sends a briefly cached read-only usage request, and the merchant can refresh it with the connection-test action. When a pending order is cancelled, the plugin may send an asset-scoped cancellation request. Manatee sends signed webhook events back to update the order after detection or confirmation.

This service is provided by Manatee.

Privacy Policy: https://manatee-api.io/privacy-policy