Shopware 6 Crypto Payment Plugin

One package across Shopware 6.5, 6.6 and 6.7

Shopware changed its payment handler API between minor versions: 6.5 uses the asynchronous payment handler interface, while later 6.6 releases and 6.7 use a new abstract payment handler with a different pay() signature. A plugin written for one generation does not load on the other.

PayfimCryptoPayment contains both handler generations and registers the right one when Shopware compiles its container. Both use the same handler identifier, so when you or your client upgrade from 6.5 to 6.6 or 6.7, the existing payment method keeps working with the new handler - there is nothing to reconfigure. On 6.5.7 and newer the payment method also gets its technical name, which Shopware 6.7 requires.

For agencies that maintain several shops on different versions, that means one plugin zip, one set of instructions and one upgrade path.

On the merchant side nothing changes either: payments go to the merchant's own wallets through a Payfim Gateway the merchant hosts, with no processor account, no KYC with Payfim and no percentage fee. The plugin uses the modern PHP 8.1 syntax that Shopware 6.5 and newer require anyway.

Payment states that match Shopware

Shopware tracks payment on the order transaction, separately from the order and delivery states. The plugin moves that transaction through Shopware's standard state machine instead of inventing its own:

Because these are native state transitions, anything you already trigger on payment state changes - for example a Flow Builder flow - reacts to crypto payments too. Coin, amount received, blockchain transaction hash and the last Payfim note are stored in the order's custom fields, visible under Orders → [order] → Details → Custom fields → Payfim crypto payment.

What happens at checkout

1. The customer chooses Pay with Crypto and clicks Submit order.
2. The plugin creates the crypto invoice server-side from the transaction amount and order currency, and redirects to the merchant's Payfim checkout.
3. The customer pays. The gateway waits for the configured confirmations and posts a signed webhook to /api/_action/payfim/webhook.
4. The plugin checks the HMAC-SHA256 signature and timestamp, re-reads the invoice from the gateway, compares amount and currency with the transaction, and sets the state.
5. The customer returns to Shopware's finish page.

If the customer cancels on the crypto checkout, Shopware lets them pick another payment method for the same order - the plugin supports changing the payment method after ordering. If they then pay the crypto invoice anyway while it is still open, the payment is recognized and the transaction moves to Paid.

Because the invoice is created on the server from the order transaction, the amount cannot be changed in the browser, and a notification for another order or another shop is ignored.

One Shopware detail: the return link is valid for 30 minutes (Shopware's payment token). A customer who returns later sees Shopware's payment error page, but the order is still marked paid by the webhook.

Sales channels, rules and configuration

• Per sales channel. Gateway URL, API key and the other settings can be overridden per sales channel with the selector at the top of the plugin configuration, so one Shopware instance can send two storefronts to two different gateways and wallets.
• Native payment method fields. Name, description, position and availability rule are edited in Settings → Shop → Payment methods, with Shopware's translations.
• Test connection. A button in the plugin configuration checks the gateway and license using the values in the form.
• Webhook base URL. Webhooks go to your APP_URL. If .env points to an internal address, enter the public shop address here.
• Debug logging writes API calls and webhooks to var/log, never the API key.

Because the settings are ordinary Shopware system configuration, they can also be managed with bin/console system:config:set in deployment scripts, which keeps staging and production consistent without clicking through the administration.

Uninstalling deactivates the payment method (Shopware does not allow deleting plugin payment methods). Without "keep data", the plugin settings and custom field set definition are removed; orders are never touched.

How to test before launch

Payments that fail quietly are the expensive kind, so check the whole path once before the shop goes live:

1. Check the gateway first. Look at its system status page, and use its test payment tool, which lets you watch a checkout without involving Shopware.
2. Run Test connection in the plugin configuration for each sales channel that has its own settings.
3. Place a real order with a low-fee coin, such as Litecoin or USDT on TRON, for a small amount.
4. Watch the transaction state. It should move from Open to In progress while confirming, then to Paid. The order's custom fields should show the coin and transaction hash.
5. Check the webhook log in the gateway admin. Every delivery shows the HTTP status Shopware returned; anything other than success usually points to APP_URL, a firewall or HTTP authentication on a staging domain.
6. Trigger your flows. If you rely on Flow Builder or an external system reacting to the Paid state, confirm it fired.

Requirements

How to install the Shopware 6 crypto payment plugin

1. Install the Payfim gateway. Deploy the gateway on the merchant's hosting and add their wallet addresses - see installing the Payfim gateway.
2. Upload the plugin. In the administration go to Extensions → My extensions, click Upload extension, choose PayfimCryptoPayment.zip, then click Install and activate it. On the command line: unzip into custom/plugins/ and run bin/console plugin:refresh and bin/console plugin:install --activate PayfimCryptoPayment.
3. Connect. Open the plugin menu (…) and choose Configure. Enter the Gateway URL and API key, click Test connection and Save.
4. Assign to the sales channel. Go to Sales Channels → [your storefront], card Payment and shipping, add Pay with Crypto to Payment methods and save.
5. Test. Put a product in the cart, choose Pay with Crypto, click Submit order and pay a small amount. More in the Shopware 6 docs.