Unzer Payment Integration Guide for Shopware

1. Introduction

This guide helps store owners, developers, and agencies seamlessly integrate Unzer — a versatile European payment provider — into Shopware. It walks through each step, with clear instructions, structured sections, and mandatory screenshots to illustrate key parts of the implementation.

Purpose:

• Provide a structured, step-by-step integration process.
• Illustrate each phase with screenshots for clarity.
• Ensure you complete installation, testing, troubleshooting, and going live confidently.

Target Audience:

• Store Owners aiming to enable more payment options.
• Developers responsible for backend / frontend implementation.
• Agencies delivering professional integrations to clients.

Structure Overview:

• What Unzer is and why it matters.
• System and account requirements.
• How to install the plugin.
• Setup and configuration steps.
• Testing in sandbox mode.
• Troubleshooting common issues.
• Going live.
• Security best practices.
• FAQ answers.
• Screenshot placement guidance.

2. What Is Unzer?

Unzer (formerly Heidelpay) is a European payment service provider, currently servicing tens of thousands of merchants. It supports a wide range of payment methods across Europe:

• Credit and debit cards: Visa, Mastercard, Maestro
• Wallets: Apple Pay, Google Pay, PayPal
• Local options: iDEAL (Netherlands), Bancontact (Belgium), EPS (Austria), TWINT (Switzerland), Przelewy24 (Poland)
• Bank-based payments: SEPA Direct Debit, invoice, installment, prepayment

Why Unzer suits Shopware stores:

• Unified checkout flow: All payment choices handled through a single integration, reducing complexity.
• Trust and conversion uplift: Local payment options build trust with regional shoppers.
• Security and compliance: PCI-DSS Level 1 certified, includes advanced fraud prevention and risk analysis tools.
• White-label flexibility: Customize the checkout to match your brand — no visible external logos.
• Seamless backend: Easily manage transactions, captures, refunds through Shopware; synced with Unzer dashboard.
• Multichannel readiness: Works for both online store and potential future POS setups.

3. Requirements

3.1 Shopware and Server

• Shopware version: For Shopware 6, version 6.4.0 or higher; for Shopware 5, version 5.6.0 or higher.
• PHP version: Shopware 6 requires PHP 7.4+ with bc-math; set serialize_precision = -1 in php.ini. Shopware 5 requires PHP 7.2+.
• HTTPS required: SSL certificate active on your domain to secure payment and webhook endpoints.

3.2 Unzer Account

• A registered Unzer merchant account to access live API keys.
• A Sandbox account for testing with test credentials.
• Note: Live and test credentials are different — keep them clearly separated.

3.3 Server Capabilities

• Ability to install via Composer, or manually upload plugin files.
• Cron tasks enabled (for Shopware 6) to ensure order status updates and webhook handling.
• Outgoing HTTPS allowed to connect to Unzer’s API and services.

4. Installing the Unzer Plugin

You can install the plugin via Composer or manually.

4.1 Installation via Composer (Shopware 6)

composer require unzerdev/shopware6
php bin/console plugin:refresh
php bin/console plugin:install --activate UnzerPayment6
php bin/console cache:clear

4.2 Manual Installation (Shopware 6)

1. Download the plugin ZIP from Unzer’s GitHub repository.
2. Unzip into custom/plugins/UnzerPayment6 .
3. cd custom/plugins/UnzerPayment6 and run composer install --no-dev .
4. Activate via Admin → Settings → System → Plugins → UnzerPayment6.

4.3 Shopware 5 Installation (if applicable)

composer require unzerdev/shopware5

Or manually place the unzipped folder into custom/plugins/ , then activate via Plugin Manager.

5. Configuring the Unzer Plugin

5.1 Basic Settings (Shopware 6)

1. Go to Settings → Extensions → Unzer Payment.
2. Select sales channel or apply globally.
3. Enter Public Key and Private Key from Unzer (sandbox or live, depending on mode).
4. Enable Test mode for sandbox sync.
5. Enable Extended logging for debugging.
6. Click Register Webhooks to sync event handling.

5.2 Booking Modes

• Charge mode: Capture payment immediately.
• Authorize mode: Only authorize; capture later (e.g., upon shipping).

Choose the mode per payment method (cards, wallets, invoice, etc.).

5.3 Advanced Delivery Settings

• Configure auto-capture triggers: On order status “Shipped” or “Completed”.
• Or choose manual capture in backend.

5.4 Activating Payment Methods

1. In Shopware Admin navigate to Settings → Shop → Payment.
2. Enable all Unzer methods you support (Unzer Credit Card, Unzer PayPal, Unzer Klarna Installments, Unzer SEPA Direct Debit, Unzer Apple Pay, etc.).
3. Assign each method to the relevant Sales Channels (e.g., Storefront).

6. Testing the Checkout with Unzer

6.1 Enable Sandbox Mode

With Test mode enabled and sandbox API keys entered, proceed with test purchases.

6.2 Complete Test Transactions

• A) Redirect-based methods (e.g., PayPal, Sofort) — choose method, complete on provider site, return to confirmation page.
• B) Card and wallet payments — enter test card info, complete checkout, review order success.
• C) Invoice / installment / book-on-account — use Authorize mode, simulate shipping, then manually capture.

6.3 Managing Orders in Backend

• Navigate to Orders → [order] → Transactions.
• Capture: enter desired amount, click button.
• Refund or Cancel from the same interface.

6.4 Logs, Reconciliation, and Workflow

• With Extended logging on, view logs under Administration → Log files.
• Check the Unzer dashboard: confirm payments, captures, and settlements match Shopware entries.

7. Troubleshooting Common Issues

Issue	Symptoms / Fix
API authentication errors	“Invalid credentials” or payment failed → double-check keys match “Test” vs “Live” mode.
Missing payment methods	No Unzer methods listed at checkout → ensure currency / country enabled in both Shopware and Unzer backend.
CSP issues	Buttons or scripts don’t work → add Unzer domains to Content-Security-Policy allow-list.
Redirect failures	Users never return to shop → ensure HTTPS and no directory-level authentication.
Webhook sync issues	Order status not updating → re-register webhooks in settings; check API logs for failures.

8. Go Live: Activating Production Mode

8.1 Switch to Live Mode

• Disable Test mode in Unzer plugin settings.
• Replace sandbox Public / Private Keys with live credentials.
• Click Re-register Webhooks to update.

8.2 Final Pre-Launch Checklist

• Run a small real payment (e.g., €1) and confirm success in Unzer dashboard.
• Verify captures, order workflow, and email notifications.
• Ensure all expected payment methods appear for live customers.

8.3 Notify Stakeholders

• Announce new payment options via site banners or emails.
• Update help documentation if relevant.
• Train staff on monitoring payments and refunds in backend.

9. Best Practices & Security

9.1 Security Standards

• Unzer maintains PCI-DSS Level 1 certification; transactions use high-level encryption and fraud detection.
• Always serve your store over HTTPS and configure CSP correctly.

9.2 Operational Recommendations

• Use Authorize mode for pre-orders; capture on shipping.
• Process refunds via Shopware backend to maintain sync.
• Keep Extended logging enabled during high-traffic periods.

9.3 Monitoring

• Check Shopware logs and Unzer dashboard regularly.
• Set alerts for failed webhook calls.
• Schedule weekly reconciliation to catch mismatches early.

10. Frequently Asked Questions (FAQ)

What if the Unzer connection fails?
Check API credentials, confirm sandbox vs live mode, re-register webhooks, verify HTTPS and firewall allowances, and clear plugin cache.

What fees does Unzer charge?
Typical fees are around 1.50 % + €0.20 per transaction, monthly fees from €19, and setup approx. €149. (Verify pricing in your merchant contract.)

How are refunds handled?
Initiate refunds in Shopware under Orders → Transactions (full or partial). This action also creates the refund in Unzer backend.

What if a payment method is unavailable?
Confirm the method is enabled in Unzer backend and Shopware settings, ensure you’re operating in a supported country / currency, and re-register webhooks.

How does Unzer Invoice Secured work?
It guarantees merchant payment regardless of eventual buyer default — ideal where payment risk must be mitigated.