Shopware 6 Bitcoin Payment Plugin

The Manatee extension adds a non-custodial Bitcoin payment method to Shopware 6. Customers pay directly to wallet addresses you control. The extension creates the payment through Manatee API, displays the Bitcoin address, amount, QR code, and expiry, and updates the Shopware transaction from signed webhook events.

Private beta

The Shopware extension is currently available as a private beta and is not yet listed in the Shopware Store. To evaluate it, create a Manatee beta account and request the extension package from beta@manatee-api.io.

Requirements

• Shopware 6.7
• PHP 8.2 through PHP 8.5
• A Manatee testnet or mainnet API key
• The webhook signing secret associated with that API key
• A publicly reachable HTTPS Shopware installation for production webhooks
• A Bitcoin receiving address or receive descriptor configured for the selected API key

Start with a separate testnet wallet and testnet API key. Testnet and mainnet API keys are network-scoped and cannot be used interchangeably.

Install a private-beta package

Only install an extension archive received through the Manatee private-beta process. Extract or copy the plugin directory to:

custom/plugins/manatee-bitcoin-payments

From the Shopware root directory, refresh the plugin list, install the extension, and clear the cache:

bin/console plugin:refresh
bin/console plugin:install --activate ManateeBitcoinPayments
bin/console cache:clear

Then open Shopware Administration:

1. Go to Settings > Shop > Payment methods.
2. Enable Bitcoin.
3. Assign the payment method to the required Sales Channel.
4. Review its availability rule before testing checkout.

Configure the extension

Open the Manatee extension configuration in Shopware Administration and set:

Setting	Purpose
API Base URL	Base URL of the Manatee API. Use the production URL for a deployed shop.
API Key	Network-scoped testnet or mainnet API credential used by the extension.
Webhook Secret	Secret used to verify signed Manatee webhook requests.
Environment Mode	Records whether an order was created using testnet or mainnet configuration.
Confirmations Required	Number of Bitcoin confirmations required before the transaction is considered paid.
Payment Expiry Minutes	Time available to pay the quoted Bitcoin amount.
Transaction States	Shopware states used for detected, confirmed, expired, and failed payments.
Debug Logging	Enables additional redacted diagnostic logging while troubleshooting.

Save the configuration and select Test saved API configuration. The test is made from the Shopware server, so the configured API URL must be reachable from the Shopware runtime rather than only from your browser.

The extension's webhook endpoint is:

https://your-shop.example/manatee/payment/webhook

The URL must be reachable by Manatee when you use asynchronous payment updates.

Test the checkout flow

1. Configure a Manatee testnet API key and its webhook secret.
2. Assign the Bitcoin payment method to the test Sales Channel.
3. Create an order and select Bitcoin during checkout.
4. Confirm that the payment page displays a testnet address, satoshi amount, QR code, and expiry.
5. Send Testnet4 Bitcoin to the displayed address.
6. Confirm that Shopware moves the transaction through the configured detected and confirmed states.
7. Check the Manatee dashboard and Shopware logs if the transaction does not update.

The extension submits the Shopware order total as fiat_amount and fiat_currency. Manatee fixes the corresponding satoshi amount when it creates the payment. Exchange-rate providers and credentials are managed by Manatee rather than configured in Shopware.

Payment and transaction states

The default mapping is:

Manatee status	Shopware transaction behavior
pending	No terminal transition. The extension waits for payment.
detected	Moves the transaction to in_progress.
confirmed	Moves the transaction to paid.
expired	Moves the transaction to cancelled unless it is already paid.
failed	Moves the transaction to failed unless it is already paid.
cancelled	Moves the transaction to cancelled unless it is already paid.

An already paid transaction is never reset by a later expired, failed, or cancelled event. If a confirmed payment arrives after Shopware has already moved the transaction to a terminal failure state, the extension records the Manatee metadata and flags the order for manual review instead of triggering automatic fulfillment.

For the complete API state model, see Payment Status Lifecycle and Reconciliation and Edge Cases.

Active payment capacity

A payment with a webhook occupies an active-monitor slot while it is pending or detected. Confirmed, expired, or cancelled payments release their slot. Cancelling an abandoned Shopware order does not by itself change the Manatee payment unless the integration has successfully sent the corresponding cancellation request.

Your dashboard shows the limits assigned to the API key. If payment creation returns plan_limit_exceeded, verify the active-monitor count and retry after an unused payment has been cancelled or expired. See Why does payment creation return plan_limit_exceeded? for the detailed behavior.

Webhook security

The extension verifies the signature over the raw request body together with the X-Manatee-Timestamp header. It rejects missing secrets, invalid signatures, stale timestamps, malformed payloads, payment mismatches, and Sales Channel mismatches.

Keep both the API key and webhook secret in Shopware's server-side configuration. Do not expose them in storefront JavaScript, templates, logs, screenshots, or support requests. Manatee never needs a wallet seed phrase or private key.

Read Webhook Signature Verification for the protocol details and Security for the production checklist.

Troubleshooting

The saved API configuration test fails

• Confirm that the saved URL includes the correct scheme and port.
• Confirm that the API key belongs to the selected Bitcoin network.
• Test connectivity from the Shopware runtime or container, not only from the host browser.
• Check whether a reverse proxy, firewall, or container network blocks the request.
• Review the redacted Manatee extension log for the response status and error category.

Checkout returns a payment-processing error

• Run Test saved API configuration again.
• Confirm that the Bitcoin payment method is assigned to the active Sales Channel.
• Check the Manatee dashboard for the API key's active-monitor capacity.
• Verify that the selected network has a receiving address or descriptor configured.
• Review the Shopware transaction and extension logs before retrying the order.

The order does not update after payment

• Confirm that the configured webhook URL is publicly reachable over HTTPS.
• Confirm that the saved webhook secret matches the API key used to create the payment.
• Check the Manatee dashboard for delivery attempts.
• Verify that Shopware has not already moved the transaction into an incompatible terminal state.

Request private-beta access

Create a Manatee beta account to receive testnet credentials, then email beta@manatee-api.io from the account address to request the current Shopware extension package.

Include your Shopware version, PHP version, target Sales Channel, and whether you are evaluating testnet only or preparing a production integration. Do not include API keys, webhook secrets, wallet descriptors, seed phrases, or private keys.