Shopware 6

Our plugin for Shopware 6 gives you access to the native payment features of the Adyen payments platform.

Features

• Credit cards: accept credit card payments on your website and mobile application, without redirecting to an external website. Sensitive cardholder data is collected securely using our Card Component, which reduces your PCI DSS-compliance requirements.
• Dynamic 3D Secure 2 authentication, including AVS checks.
• Local payment methods: accept local payment methods including iDEAL, Sofort, Klarna, giropay, Google Pay, and many others.
• Tokenization: offer returning shoppers a faster checkout experience by saving their card details.
• Revenue Protect: use our risk management system to identify and block fraudsters, while reducing friction for legitimate shoppers. You can either fully automate the risk management process, or add manual review for certain payments.

Supported versions

This documentation reflects the latest version of the plugin. You can find the latest version on GitHub. Our plugin supports the following:

• Shopware version 6.3.1.1 or later, using PHP 7.0 or later.

We cannot offer support if you are not using the default Shopware checkout. We do not recommend customizing the plugin, because this could make it harder to upgrade and maintain your integration. If you decide to customize, we recommend that you:

• Keep track of the custom code added to your integration.
• Create an issue on GitHub if you want to suggest a new feature for the plugin.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

• Get an overview of the steps needed to accept live payments.
• Create your test account.

Step 1: Install the plugin

You have the following options for installing the plugin:

• Download from the Shopware Store: This is the easiest option if you have a Shopware Account.
• Install with Composer: This is the easiest option if you're working on your local environment.
• Download from GitHub: More advanced option for developers, but makes it easier to install updates to the plugin that we do between releases.

Step 2: Generate an API key

To authenticate API requests from Shopware, you need to provide an API key. You will need to enter the API key when setting up the Shopware back end in Step 5.

To generate an API key:

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
3. Under Server settings > Authentication select the API key tab.
4. Select Generate API key.
5. Select the copy icon and store your API key securely in your system.
6. Select Save changes.

Make sure that your API credential has the following permissions:

• API Clientside Encryption Payments role
• Checkout webservice role

Step 3: Generate a client key

The plugin needs the client key to show the input fields for card details.

The client key is linked to one or more allowed origins — the domains from which we expect to get your client-side requests. For example, if you're collecting shopper's payment information at: https://example.org/checkout, you would need to link the domain https://example.org as an allowed origin to your client key.

To generate a client key:

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the credential username for your integration, for example ws@Company.[YourCompanyAccount].
3. Under Client settings > Authentication select the Client key tab.
4. Select Generate client key.
5. Select the copy icon and store your client key securely in your system.
6. Under Add allowed origins, enter your domains and select Add.
7. Select Save changes.

You now have a client key for your test environment. To get a client key for your live environment, follow the same steps in your live Customer Area.

You will need to copy the test and live client keys and add them in the Shopware back end as described in Step 5.

Step 4: Set up notifications

Adyen uses notifications, our webhook service, to inform your Shopware platform of payment status changes. For more information, refer to Notifications. 

To receive notifications: 

1. Log in to your Customer Area with your company-level account.
2. Go to Developers > Webhooks.
3. In the upper-right corner, select the + Webhook button.
4. Next to Standard notification, select Add.
5. In the URL box, enter your website URL followed by /adyen/notification as a suffix. For example, https://www.example.com/adyen/notification.
6. Select Active.
7. Set Method to JSON.
8. In the User Name and Password boxes, enter a username and password for basic authentication.
   You will need to enter these when setting up the Shopware back end in Step 5.
9. Under Additional settings, select Generate new HMAC key.
   Securely save the HMAC key in your system - you won't be able to restore it later. You will need to enter the HMAC key when setting up the Shopware back end in Step 5.
10. Select Save Configuration.

You have now set up notifications for your test environment. To set up notifications for your live environment, follow the same steps in your live Customer Area.

Step 5: Configure the plugin

1. Log in to the Shopware back end and go to Settings > System > Plugins.
2. Find the Adyen Payment plugin, and select the action button (...) > Config.

3. Fill out the following fields:

   If you have more than one Shopware shop, you need to set up these configurations for each shop.

   Field	Notes	Required field
   Merchant account	Name of your Adyen merchant account for which the payments will be processed.
   API Key for test	Your API key from Adyen test Customer Area. In the live environment, you can enter a dummy value here.
   API Key for live	Your API key from Adyen live Customer Area. In the test environment, you can enter a dummy value here.
   Client Key for test	Your client key from your Adyen test Customer Area.
   Client Key for live	Your client key from your Adyen live Customer Area.
   Environment	Select whether you want to enable live (production) mode or keep using test mode.
   Live endpoint URL prefix	The URL prefix [random]-[company name] from your Adyen live Customer Area > Developers > API URLs. For more information, refer to Checkout endpoints. This field is only required for live (production) mode.
   Username for standard notifications	The username for basic authentication that you generated in Step 4.
   Password for standard notifications	The password for basic authentication that you generated in Step 4.
   HMAC Key for test	The HMAC key that you generated in Step 4.
   HMAC Key for live	The HMAC key that you generated in Step 4.

4. In the Shopware back end, go to the desired sales channel, and add the payment methods to show in the checkout page. Make sure to also add the payment methods in your Adyen Customer Area.

Payment methods

Stored payment methods

The plugin allows you to securely store shopper's payment details giving your returning shoppers a faster checkout experience. To enable or disable this functionality:

1. Log in to your Shopware back end and go to Storefront.
2. Scroll down to the Payment and shipping section.
3. Add or remove the Stored Payment Methods | Adyen Payment payment method.
4. Save your changes.

Updating payment method logos

By default, the Shopware 6 plugin automatically keeps the logos for all your payment methods up to date.

To turn off automatic logo updating, in the Shopware 6 configuration file platform/src/Core/Framework/Resources/config/packages/shopware.yaml, set shopware.media.enable_url_upload_feature to false.

To manually update the logos, go to your Shopware 6 project root directory and run:

bin/console adyen:fetch-logos

Manage orders

The plugin creates an order before creating the payment.

To manage orders and view transaction summaries go to:

• Shopware 6 Administration > Orders > Overview.
• Your Adyen Customer Area where you can find more detailed reporting and conversion analytics.

The Shopware and Adyen platforms are synchronized using webhook notifications.

View payment status

You can find the statuses of your payments in Shopware orders overview.

Shopware payment status	Description
open	The default state for new orders, it means no notification was received.
in progress	The payment transaction is still in progress.
paid	The payment was successful.
failed	The payment authorization or capture failed or the payment expired or was canceled.
refunded	The payment has been refunded.

Change payment expiry

An order expires if the shopper doesn't complete the payment, for example if they abandon the session.

After you enable the OFFER_CLOSED webhook notifications in your Adyen Customer Area, an order expires if the shopper doesn't complete the payment after:

• 12 hours for card payments.
• up to 24 days for other payment methods.

When an order expires, the payment status changes to failed.

To change when orders expire, contact the Support Team and ask them to set the OFFER_CLOSED notification to when you want orders to expire. You can request to set it to 1 hour or longer.

Refund an order

If you need to refund an order, you can do this in:

• the Adyen Customer Area. When refunding in your Customer Area, you can issue both full and partial refunds.
• the Shopware back end. This is supported in plugin version 3.1.0 and later, or 2.2.0 and later. When refunding in the Shopware back end, you can currently only make full refunds. Partial refunds will be supported in a future version of the plugin.

When your refund request has been processed, you see the outcome of the refund request in the Shopware back end.

Refund in the Shopware back end

To issue a full refund in the Shopware back end:

1. Go to Orders > Overview and select the order that you want to refund.
2. Move through the page to the Adyen Refunds section.
3. Click on Create new, and confirm your request.

Get the outcome of the refund request

After you've submitted the refund request, either in your Customer Area or in the Shopware back end, an entry with a Pending Webhook status is created in the table below the Create new button. This means that the refund has been submitted, but not yet processed.

When the refund is processed by Adyen, we send a REFUND notification. When this notification is processed by Shopware, the Pending Webhook status is updated to Success or Failed, depending on the outcome of the refund request.

Next steps