MakePay Shopware Plugin And App

Overview

MakePay for Shopware adds a crypto payment method to Shopware 6.7+ stores. Shopware creates the order transaction, MakePay creates the payment link, and the integration returns the customer to Shopware after hosted or embedded checkout. Signed webhooks keep the Shopware transaction state in sync after the payment status changes.

Two installation formats are available:

• PHP plugin for self-hosted and PaaS Shopware stores.
• Shopware App for app-based installations on SaaS, PaaS, and self-hosted stores.

Before You Start

• Shopware 6.7 or newer
• Admin access to install extensions or apps
• A MakePay company where you can manage payment settings
• A public HTTPS shop URL so callbacks and webhooks can reach Shopware

Choose A Package

Use the PHP plugin when you control the Shopware filesystem and want the payment handler to run inside Shopware. Use the Shopware App when the merchant installation should use Shopware's app lifecycle and remote payment endpoints.

Download the Shopware PHP plugin Download the Shopware App package

Both packages register one payment method named MakePay with the technical name makepay_payment.

Install The PHP Plugin

Upload or extract the plugin so the extension directory is available to Shopware, then refresh the extension list from Shopware Administration.

For a CLI installation, run these commands from the Shopware root:

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

After activation, open Settings > Extensions > MakePay and choose the checkout mode. Hosted checkout redirects customers to MakePay. Embedded checkout opens a local Shopware bridge page with a MakePay iframe and a hosted checkout fallback link.

Install The Shopware App

Upload the Shopware App ZIP through Shopware Administration or install it using the Shopware app installation flow available for your hosting model. During registration, Shopware sends the shop ID and shop URL to MakeCrypto and receives the signed confirmation response required by the app lifecycle.

After installation, link the app installation to the MakePay company that should receive payments. The app backend stores the Shopware app secret and Admin API credentials encrypted, then uses them only for signed payment requests, finalization, and transaction updates.

Connect MakePay

For the PHP plugin, use Connect MakePay in the plugin settings. The OAuth flow:

1. Opens MakeCrypto in a browser tab.
2. Asks you to sign in and choose the company that should receive payments.
3. Shows the permissions required by the Shopware integration.
4. Returns you to Shopware after approval.
5. Stores DPoP-bound OAuth credentials and configures webhook callbacks.

Manual API-key credentials are available as a fallback for the PHP plugin. The Shopware App uses the app registration and the linked MakePay company on the MakeCrypto backend.

Configure MakePay

Review these settings after installation:

• API base URL, normally https://www.makecrypto.io
• Connection method, OAuth by default for the PHP plugin
• MakePay company ID
• Settlement currency or default asset
• Checkout mode, hosted or embedded
• Webhook secret status
• Last connection or webhook error

The integration sends payment link metadata including source=shopware, the Shopware order ID, the order number, the transaction ID, the shop URL, the Shopware version, and the installed plugin or app version.

Checkout Flow

When a customer selects MakePay, Shopware creates an order transaction and calls the MakePay payment handler or app payment endpoint. The integration creates a MakePay payment link with:

Field	Purpose
orderId=shopware_order_<id>	Maps MakePay activity back to Shopware
orderNumber	Human-readable Shopware order number
transactionId	Shopware order transaction ID
customerEmail	Customer email for receipts and dashboard search
successUrl, failureUrl, returnUrl	Shopware finalize flow URLs

Hosted mode returns the customer to the public MakePay checkout URL. Embedded mode returns the customer to a Shopware bridge page that embeds /embed/payment/<uid> and keeps a hosted checkout fallback link visible.

Order States

The finalize step checks the MakePay payment status when possible. Webhooks verify the X-MakePay-Signature header before loading the Shopware order transaction and updating it idempotently.

MakePay status	Shopware transaction state
paid, completed, succeeded	Paid
confirming, processing, underpaid	In progress
pending, waiting, created	Open
expired, cancelled, canceled	Cancelled
failed, chargeback	Failed
refunded	Refunded

Security Notes

The PHP plugin stores OAuth tokens, API-key fallback credentials, and webhook secrets in Shopware system configuration. Limit Shopware administration access to trusted operators and rotate the connection if a backup or admin account is exposed.

The OAuth connection asks for these permissions:

• company:read
• makepay:payment-links:read
• makepay:payment-links:write
• makepay:customers:read
• makepay:customers:write
• makepay:settings:read
• makepay:settings:write

Troubleshooting

If checkout does not redirect, confirm the payment method is active for the sales channel and that MakePay has a valid OAuth connection or API-key fallback.

If embedded checkout opens but the iframe does not load, switch to hosted mode temporarily and confirm the MakePay payment link URL is reachable from the storefront.

If order states do not update, compare the webhook URL in MakePay with the Shopware webhook endpoint, rotate the webhook secret, and retry the MakePay webhook event from the dashboard.