Shopware 6 Crypto Payment Plugin
The Manatee extension adds BTC, BCH, and XMR to one non-custodial crypto payment flow in Shopware 6. Customers pay directly to wallet addresses you control. The extension creates the asset-specific payment, displays correctly formatted instructions and a QR code, polls status, and updates the Shopware transaction from signed webhook events.
The Shopware extension is currently distributed directly and is not yet listed in the Shopware Store. To use it, create a Manatee account and request the extension package from contact@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 receive configuration for every enabled asset: BTC descriptor/address, BCH account xpub/address, or XMR primary address and private view key
Start with separate test wallets and the shared Test API key. Test mode maps BTC/BCH to Testnet4 and XMR to Stagenet. Test and Mainnet credentials cannot be used interchangeably.
Install the extension package
Only install an extension archive received directly from Manatee. 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:
- Go to Settings > Shop > Payment methods.
- Enable Pay with crypto and select BTC, BCH, and/or XMR in the extension configuration.
- Assign the payment method to the required Sales Channel.
- 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 | Shared Test 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. |
| Enabled Assets | Assets offered at checkout; XMR is shown only when its receive wallet is ready. |
| Confirmations Required | Asset-appropriate confirmation threshold before the transaction is considered paid. |
| Payment Expiry Minutes | Time available to pay the quoted crypto 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
- Configure the Manatee Test API key and its webhook secret.
- Assign the crypto payment method to the test Sales Channel.
- Create separate orders and select BTC, BCH, and XMR during checkout.
- Confirm that the payment page identifies the asset and network and formats satoshi or piconero amounts correctly.
- Send Testnet4 BTC/BCH or Stagenet XMR to the displayed address.
- Confirm that Shopware moves the transaction through the configured detected and confirmed states.
- 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 for BTC/BCH or piconero amount for XMR 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 a concurrent-payment 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 number of concurrent webhook-enabled payments 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 spend 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 Test or Mainnet environment.
- 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 crypto payment method is assigned to the active Sales Channel and the selected asset is enabled.
- Check the Manatee dashboard for the API key's concurrent webhook-enabled payment capacity.
- Verify that the selected asset has a ready receive configuration for the selected environment.
- 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 the extension package
Create a Manatee account to receive testnet credentials, then email contact@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.