Manatee Bitcoin Payment Gateway for WooCommerce

Description

Manatee Bitcoin Payment Gateway for WooCommerce adds a Bitcoin payment method to WooCommerce checkout. It creates Bitcoin payment requests through the Manatee Bitcoin Payment API, shows customers a Bitcoin address, amount, wallet URI, and local QR code, then updates WooCommerce orders from signed webhook events.

Manatee is non-custodial. The plugin does not hold customer funds, does not ask for wallet seeds or private keys, and does not run Bitcoin node logic inside WordPress. It connects WooCommerce orders with Manatee payment verification so your shop can detect incoming Bitcoin transactions and move orders through your configured order statuses.

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

Features

• WooCommerce payment gateway for on-chain Bitcoin payments.
• Non-custodial flow: no wallet seed, private key, or hosted wallet custody is required by the plugin.
• Test and live environment mode setting.
• API key, webhook secret, confirmation count, and payment expiry settings.
• Read-only API connection test from the WooCommerce gateway settings screen.
• Customer payment screen with Bitcoin address, satoshi amount, wallet URI, local QR code, expiry, and automatic status polling.
• 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 payment ID, Bitcoin address, satoshi amount, fiat amount, currency, exchange rate, rate timestamp, pricing source, environment mode, transaction ID, confirmations, status, and expiry.
• WooCommerce logging with secret redaction.
• WooCommerce HPOS compatibility.

How it works

1. A customer selects Bitcoin during WooCommerce checkout.
2. The plugin sends the WooCommerce order total to Manatee as fiat_amount and fiat_currency.
3. The plugin creates a Manatee Bitcoin payment through the configured API base URL and API key.
4. The customer sees the returned Bitcoin address, amount, wallet link, QR code, expiry, and current status on the order received page.
5. Manatee monitors the Bitcoin payment lifecycle and sends signed webhook events to the shop.
6. The plugin verifies the webhook signature, timestamp, event ID, payment ID, and order mapping before mutating the WooCommerce order.
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 > Bitcoin via Manatee:

• Environment Mode: choose Test or Live.
• API Base URL: use https://api.manatee-api.io unless Manatee support tells you otherwise.
• API Key: enter the Manatee API key for the selected environment.
• Webhook Secret: enter the secret used to verify Manatee webhook signatures.
• Webhook URL Override: leave empty unless Manatee cannot reach the automatically generated WordPress REST endpoint.
• Confirmations Required: choose how many Bitcoin confirmations are required before an order is treated as paid.
• 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.

After saving the API Base URL and API Key, use “Test API connection”. The test sends a read-only GET /v1/usage request and reports whether WooCommerce can reach Manatee with the configured key.

Test mode

Use Test mode with a testnet Manatee API key before going live. Test mode lets you verify checkout, payment instructions, webhook delivery, order metadata, and order status mapping without using mainnet Bitcoin payments.

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 Bitcoin, the plugin sends the WooCommerce fiat amount, currency, webhook URL, required confirmation count, expiry window, underpayment tolerance, and a WooCommerce order reference to the configured Manatee API.

The WooCommerce order stores the Manatee payment ID, Bitcoin address, satoshi amount, fiat amount, currency, exchange rate, rate timestamp, pricing source, environment mode, payment status, transaction ID, confirmation count, and expiry timestamp.

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 Bitcoin Payment API to create and verify non-custodial Bitcoin payments for WooCommerce orders.

When a customer selects Bitcoin at checkout, the plugin sends the WooCommerce order amount, currency, webhook URL, required confirmation count, payment expiry window, underpayment tolerance, and an order reference to the configured Manatee API. The API returns a Bitcoin payment ID, receiving address, satoshi amount, exchange-rate metadata, expiry timestamp, and payment status.

The plugin also sends read-only API requests when the merchant runs the connection test from the WooCommerce gateway settings screen. When a pending WooCommerce order is cancelled, the plugin may send a cancellation request for the related Manatee payment. Manatee sends signed webhook events back to the shop so the plugin can update the WooCommerce order status after payment detection or confirmation.

This service is provided by Manatee.

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