-
Notifications
You must be signed in to change notification settings - Fork 12
Home
Welcome to the Wiki page of the Adyen Shopware 5 plugin. Here you can find information about how to integrate and configure the Adyen Shopware 5 plugin.
Our plugin for Shopware 5 gives you access to all the features of the Adyen payments platform in one integration. This plugin is maintained by a specialised partner therefore any plugin related issues please reach out directly to [email protected]
This documentation reflects the latest version of the plugin. You can find the latest version on GitHub. Our plugin supports the following: Shopware version 5.7.3 or later, using PHP 7.0 or later.
- 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 Custom Card Component, which reduces your PCI DSS-compliance requirements.
- Dynamic 3D Secure 2 authentication, including AVS checks.
- Adyen 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.
- Local payment methods (supported on latest plugin version): iDEAL, Sofort, Klarna, Giropay, Google Pay, Apple Pay, Bancontact cards and mobile, Giftcards
| Feature Table | Support |
|---|---|
| Integration Supported | |
| Cards Integration | Checkout API (component) |
| LPM Integration | Checkout API (component) expect Gift cards (HPP) |
| POS Integration | No |
| Gift Cards | Checkout API - fallback to HPP |
| Tokenization | |
| Tokenize card details for one-off | Yes |
| Tokenize local payment methods for one-off | No |
| Subscriptions | No |
| Card Installments | No |
| Payment & order management | |
| Cancel | No |
| Full capture | Yes |
| Partial capture | No |
| Multiple partial capture | No |
| Auto capture | Yes |
| Manual capture | No |
| Authorization | |
| Level 2/3 data sending | No |
| Zero-value auth | No |
| Revenue Protect | |
| 3D Secure 1 | Yes |
| 3D Secure 2.0 | Yes |
| Order Status updated when in manual review | No |
| Show risk score in order payment information | No |
| Refunds | |
| Full Refunds | Yes |
| Partial Refunds | No |
| Refunds Available from the Customer Area only | No |
| Additional Features | |
| MOTO (mail order, telephone order) | No |
| Include open invoice data into request | Yes |
| Payment methods as full express option (Apple Pay, Google Pay, Amazon Pay, Paypal) | No |
| Pay by link | No |
| Basket items are sent in payment request | No |
| Adyen Giving | No |
| Adyen Restore | No |
| Payouts | No |
| Supports a headless integration | No |
Sign up for Adyen test account
Before you begin to integrate Shopware 5 with the Adyen payments platform, make sure that you have performed the following steps:
- Sign up for a test account with Adyen at https://www.adyen.com/signup.
- While you test your integration, you can apply for a live account with Adyen.
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 backend.
To generate an API Key:
- Log in to your Customer Area.
- Go to Developers > API credentials, and select the credential for your integration, for example ws.
- Under Authentication, select Generate New API Key.
- Copy and securely store the API key in your system — you won't be able to restore it later.
- If your API key is lost or compromised, you need to generate a new one.
- Select Save at the bottom of the page.
- Make sure that your API credential has the following permissions:
- API Clientside Encryption Payments role
- Checkout webservice role
To get an API key for your live environment, follow the same steps in your live Customer Area.
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:
- Log in to your Customer Area.
- Go to Developers > API credentials, and select the API credential for your integration, for example ws.
- Add your domains under Allowed origins. These are the domains from which you will be sending your client-side requests.
- Under Authentication, select Generate New Client Key.
- Select Save at the bottom of the page.
- 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 backend.
You have the following options for installing the plugin:
- Download from the Shopware Store
- Install with Composer
- Download from GitHub
Option 1: Download from the Shopware Store
To use this option, you need to have a valid Shopware Account, and a URL with a verified Shopware instance.
- Log in to the Shopware backend, and go to Configuration > Plugin Manager.
- Find the Adyen plugin, and select Download now.
- Enter your Shopware Account credentials.
- In the Plugin Manager, select Installed. Find the Adyen plugin, and select the pencil icon to open the plugin.
- Select Activate. The plugin is now ready to be configured.
Option 2: Install with Composer
Adyen's plugin for Shopware 5 is open-source and available on GitHub. The GitHub repository is connected to Packagist, so you can include it in your project through Composer:
- In your command-line tool, go to the root of your Shopware 5 application and run composer require adyen/adyen-shopware5.
- In your Shopware back end, go to Configuration > Plugin Manager.
- Select Installed. Find the Adyen plugin, and select the pencil icon to open the plugin.
- Select Activate.
The plugin is now ready to be configured.
Option 3: Download from GitHub
- Clone the adyen-shopware5 GitHub repository.
- Go to the downloaded folder, and run composer install --no-dev.
- Copy the entire adyen-shopware5 folder into the custom/plugins folder in the root of your Shopware 5 application.
- Rename the adyen-shopware5 folder to AdyenPayment, so you now have: custom/plugins/AdyenPayment.
- In your Shopware back end, go to Configuration > Plugin Manager.
- Select Installed. Find the Adyen plugin, and select the pencil icon to open the plugin.
- Select Activate.
The plugin is now ready to be configured.
In your Shopware backend, go to Configuration > Plugin Manager.
- Select Installed. Find the Adyen plugin, and select the pencil icon to open the plugin.
- Enter the required fields as described in the table below and then select Test API connection to save and test the connection details.
Configuration Fields If you have more than one shop, you have to set up the following configurations for each shop:
| Field | Notes | Required |
|---|---|---|
| Environment | Adyen has a test customer area and a live customer area. Select whether you want to use test or live (production) mode | Yes |
| Merchant account | Name of your Adyen merchant account for which the payments will be processed | Yes |
| API key (Test) | Your API key from Adyen test Customer Area. In the live environment, you can enter a dummy value here | Yes |
| API key (Live) | Your API key from Adyen live Customer Area. In the test environment, you can enter a dummy value here | Yes |
| Client Key (Test) | Your client key from your Adyen test Customer Area | Yes |
| Client Key (Live) | Your [client key](https://docs.adyen.com/development-resources/client-side-authentication#get-your-client-key from your Adyen live Customer Area | Yes |
| API: URL prefix | The URL live 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 | Yes (Live) |
| Notification HMAC (Live) | The HMAC key that you generated from your Adyen customer area | Yes |
| Notification Auth Username (Live) | The username for basic authentication from your Adyen customer area | Yes |
| Notification Auth Password (Live) | The password for basic authentication | Yes |
| Google Merchant ID | ID of your Google account for which the Google Pay payments will be processed (if applicable) | No |
| Enable Payment Methods cache | Cache the list of payment methods for better performance | No |
| Manual Risk Review Action | Select which action to perform if a risk rule sends a payment to case review and is rejected | No |
- Add all your payment methods in the Adyen Customer Area.
-
If you are using our Shopware 5 plugin version 3.0.0 and later: Select Import Adyen payment methods to import the payment methods that you have enabled in your Adyen Customer Area into Shopware.
-
If you are using our Shopware 5 plugin versions earlier than 3.0.0: You cannot configure any payment method within the Shopware platform. The plugin dynamically gets available payment methods from Adyen, based on the billing country and the amount in the shopping basket of the shopper.
You need to assign the relevant payment methods to a corresponding shipping cost. To do so:
- Login to the Shopware backend and go to Configuration > Shipping cost to edit the fields.
- In the Payment Method tab, move the required payment methods from blocked to allowed.
You can change the language of the payment method name and description. To do so, go to Snippets in your admin panel within Shopware, and set the translated information to the following:
| Field | Namespace | Name | Value |
|---|---|---|---|
| Payment method title | The value identified by adyen/method/name | ID of the payment method | The title you want to show for this payment method |
| Payment method description | The value identified by adyen/method/description | This value must match the one used for the adyen/method/name snippet | The description you want to show next to the payment method name |
Adyen uses notifications, our webhook service, to inform your Shopware platform of payment status changes. For more information, refer to Notifications Webhooks.
To receive notifications:
- Log in to your Adyen Customer Area with your company-level account.
- Go to Developers > Webhooks.
- In the upper-right corner, select the + Webhook button.
- Next to Standard notification, select Add.
- In the URL box, enter your website URL followed by /frontend/notification/adyen as a suffix. For example, https://www.example.com/frontend/notification/adyen.
- Select the Active checkbox.
- Set Method to JSON.
- 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 backend.
- 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 backend.
- Select Save Configuration.
When testing notifications from the Adyen backend, you'll receive a 'notification save error' because the notification couldn't be matched with an existing order.
ℹ️ : Info:
Test cards: https://docs.adyen.com/development-resources/test-cards/test-card-numbers#apple-pay
Apple pay set-up https://docs.adyen.com/payment-methods/apple-pay/web-component#set-up-apple-pay
For the Apple Pay payment method to be able to work you'll need the following:
- The AdyenPayment plugin must be updated to the latest possible version, minimum supported version: 3.3.0
- Webshop domain needs to be served over HTTPS, a self-signed SSL certificate is not supported by Apple pay
- Apple Pay must be active in the Adyen dashboard (ex. https://ca-test.adyen.com/) your test/live evironment: Customer Area > Transactions > Payments
Apple pay requires access to an merchant association file:
- The AdyenPaymenty plugin attempts to install a default merchant association file, if none is present (path: .well-known/apple-developer-merchantid-domain-association)
- If the file cannot be installed, the AdyenPayment plugin will serve the merchant association file directly from an endpoint
- The install process can be manually triggered in
- Shopware 5 backend / Configuration > Plugin Manager > Installed > Adyen Shopware Plugin > edit
- Click the button: Install Adyen default ApplePay Merchant association file
- An apple-developer-merchantid-domain-association file can be uploaded manually to the web server path /weshop root/.well-known/apple-developer-merchantid-domain-association
- By default the Adyen SW5 plugin will use the payment method additional description configured by: Configuration > Payment Methods. You can add html/css styling on the text field.
- If you want to use the shopware snippets, you can do this as well, by first leaving the additional description field blank in the payment method. In the Configuration > snippet, add a namespace adyen/method/description. For the name use the Adyen payment type (payment method > free text fields). Value can be html/css styling you want to provide for the snippet.
You can manage orders and view transaction summaries in Shopware, while switching to Adyen for more detailed reporting and conversion analytics. The two platforms are synchronized.
When a shopper makes a payment using a payment method option provided by Adyen, you can see a menu item called Adyen Notifications in the detail screen of an order in Shopware.
The Adyen plugin will always create an order before the payment and rely on notifications to update the payment status. The offer_closed notification which closes unsuccessful payments will automatically be sent after 12 hours for cards and up to 24 days for some local payment methods. You can enable this notification from your Adyen customer area. If you want to close the payment before this (minimum 1 hour) you can have the offer_closed notification set up for an 1 hour. The Adyen support team ([email protected]) can enable this feature for you. Enabling this event is not LPM-specific.
You can view the statuses of your payments in Shopware.
| Shopware payment status | Description |
|---|---|
| open | The default Shopware state, it means no notification was received or the capture has failed |
| the_credit_has_been_accepted | The payment authorization was successful |
| the_process_has_been_cancelled | The payment authorization failed or the payment was canceled |
| the_credit_has_been_accepted | The capture was successful |
| re_crediting | The full refund was successful |
In Shopware it is possible to modify the line items of an order after the order has been placed. However, this feature is currently not supported in the plugin. If you would like to request for this or for other additional features in the plugin, open a feature request in our GitHub repository.
You can order a full refund, but the plugin doesn't support partial refunds.
To refund an order:
- Log into Shopware and go to the menu.
- Go to Order details > Adyen Notifications > Refunds and select Full Refund.
We are happy to help and answer any of your questions as quickly as possible, therefore please follow the channels of communication below! :)
For quicker communication, if you have questions related to the Shopware 5 Adyen Plugin development please directly contact our partner [email protected]
If you have any questions related to Adyen our support team can help you. Please open a support ticket here. Found a bug in the plugin? Please open a Github issue and our developers will be happy to help you directly.