Skip to content
merijndebeer-adyen edited this page Jul 25, 2024 · 64 revisions

Supported versions

Adyen PrestaShop integration supports PrestaShop versions 1.7.5.0 and up.

Supported features

Feature Support
Cards Integration Checkout API (component)
LPM Integration Checkout API (component)
Pay by link Yes
POS Integration No
Express checkout Yes
Adyen Giving Yes
Gift Cards HPP
Tokenization
Tokenize card details for one-off Yes
Tokenize local payment methods for one-off Yes
Subscriptions Yes
Card Installments Yes
Authorization
Sending level 2/3 data Yes
3D Secure 1 No
3D Secure 2.0 Yes
Order Status updated when in manual review Yes
Show risk score in order payment information Yes
Payment & order management
Cancel Yes
Full capture Yes
Partial capture Yes
Auto capture Yes
Manual capture Yes
Full Refunds Yes
Partial Refunds Yes
Refunds Available from the Customer Area only No
Other/Additional
MOTO (mail order, telephone order) No
Include open invoice data into request Yes

Supported payment methods

Credit and debit cards

Buy Now Pay Later

Cash and ATM payment methods

Direct Debit

Online payments

Wallets

Prepaid and gift cards

Mobile

Multistore support

Adyen PrestaShop integrations support configuring multiple sub shops within one PrestaShop administration panel. You can select the store context at any time during the integration configuration by using the store switcher.

screenshot of the store switcher

screenshot of the store switcher

Installation and setup

Step 1: Install the plugin

Download the latest plugin release from the GitHub repository and upload it through the PrestaShop Plugin Manager.

Step 2: Generate an API key

For authenticating API requests from PrestaShop, you need to provide an API key.

To generate an API key for your test environment:

  1. Log in to your Customer Area.
  2. Go to Developers > API credentials, and select the credential username for your integration, for example [email protected].
  3. Under Authentication, select Generate New API Key.
  4. Copy and securely store the API key in your system — you won't be able to retrieve it later.
  5. If your API key is lost or compromised, you need to generate a new one.
  6. Select Save at the bottom of the page.

API key should have the following roles:

  • Management API - Accounts read
  • Management API - Accounts read and write
  • Management API - API credentials read and write
  • Management API - Payout Account Settings Read
  • Management API - Webhooks read
  • Management API - Webhooks read and write
  • Management API - Payment methods read
  • Management API - Stores read
  • Management API - Stores read and write
  • Checkout encrypted cardholder data
  • Checkout webservice role
  • Data Protection API
  • Merchant PAL Webservice role
  • Merchant Recurring role
  • API Clientside Encryption Payments role

To get an API key for your live environment, follow the same steps in your live Customer Area.

You will need to add either the test or the live API key in the integration dashboard, depending on the selected environment, as described in Step 2.

screenshot of the connection page

Step 3: Set up the plugin in PrestaShop back office

After successfully authenticating with the provided API key from step 2, the integration will automatically register the client key and allowed origins on the Adyen API, and you will be requested to select the merchant account to link to the Adyen account. This will automatically generate a HMAC key and register webhooks for that merchant account.

screenshot of the merchant account page

Step 4: Set up payment methods

To enable a payment method, you need to add it in your Customer Area.

All available payment methods will be displayed on the payment methods configuration page.

screenshot of the payment methods page

You can configure their display properties, as well as define additional surcharges for each configured payment method.

screenshot of the payment method configuration page

The following payment methods provide some additional configuration:

Credit cards

  • Single click payments
  • Installment configuration
  • Sending L2/L3 data

Oney

  • Installment configuration

Apple Pay

  • Apple Pay merchant credentials
  • Enable express checkout

Amazon Pay

  • Amazon Pay merchant credentials
  • Enable express checkout

Google Pay

  • Google Pay merchant credentials
  • Enable express checkout

PayPal

  • Enable express checkout

Step 5: Configure payment status mappings

Upon installation, the integration will set default status mappings between PrestaShop order statuses and Adyen payment states. However, you can change this mapping at any time by navigating to the status mapping configuration page and changing how these statuses should map.

These mappings will be used to transition the PrestaShop order into a status mapped to the Adyen payment state in the incoming webhook request from the Adyen API. Webhooks are triggered when there is a change to the created payment in the Adyen platform.

screenshot of the payment status mappings configuration page

Step 6: Make test payments

After you've set up the plugin, use our test card numbers to make test payments.

After your test payments, look up the payment status in your Customer Area. If a transaction has been refused due to a high-risk score, consider making adjustments to your risk profile scoring.

Payment method configuration

You can configure the following properties for each activated payment method:

Configuration Description
Payment method name Title displayed to customers on checkout.
Payment method description The description is displayed to customers at checkout.
Payment method logo The customizable image will be displayed to customers at checkout.
Surcharge type Available options:- None
  • Fixed surcharge: Fixed surcharge added to the order total
  • Percent surcharge: Percentage of the total order amount added as a surcharge
  • Combined surcharge: Combines fixed and percent surcharge | | Fixed surcharge amount  | Available only if the surcharge type is fixed or combined. Specifies a fixed surcharge in the current order currency that will be added to the order total. | | Percent surcharge | Available only if the surcharge type is a percent or combined. Specifies a percentage of the total order amount that will be added to the order total. | | Surcharge limit | Available only if surcharge type is a percent or combined. Specifies a fixed amount in the current order currency that represents a threshold that cannot be surpassed by the total surcharge amount. In case the total calculated surcharge amount is higher than the limit, the limit amount will be set as a surcharge. |

Some payment methods offer additional configuration options (single-click payments, installments, express checkout configuration, etc.)

Adyen Giving

With our Adyen Giving feature, you can give your shoppers the option to donate to a charity as part of your payment flow. This feature is available with credit cards and iDEAL payment methods.

You can configure the following options:

Configuration Description
Enable Adyen Giving Enable the Adyen Giving feature (merchants must also choose and enable a charity in their customer area)
Charity Name The name of the chosen charity.
Charity Description Description of the chosen charity.
Charity Merchant Account The Adyen account name of the charity. 
Donation Amounts Comma-separated suggested donation amounts.
Charity Logo Logo of the chosen charity
Background Image  The background image that appears in the Component
Charity Website The website URL of the charity

screenshot of Adyen Giving on the checkout page

Customer data sent from the integration

The integration sends the following PrestaShop customer data to the Adyen API:

  • ID
  • Name
  • Email
  • Birthday
  • Billing address
  • Shipping address
  • Checkout locale
  • Order items

Notifications

Whenever the system performs a significant action that requires the merchant's attention (or is simply informative), such notification will be forwarded to the notifications hub.

Notifications in the notifications hub are split to shop events and webhook events.

Shop events contain all integration actions that require the merchant's attention or serve to inform the merchant.

Webhook events effectively represent a transaction log of all payments made with Adyen payment methods in the shop system.

screenshot of the notification hub

screenshot of the notification hub

Order management

The integration extends the order details page with additional information about the payment on Adyen. You can perform one of the following actions on this page:

  • Cancel a payment
  • Capture a payment (partially or fully)
  • Refund a payment (partially or fully)

You can capture and/or refund Adyen payments only by amounts. Additionally, on this page you can see the full transaction history of that payment, with a timeline of all status changes on that payment.

screenshot of the order details page

Migrating from the older version

If you are using the plugin version 4.0.7 or below, you should migrate to the new version of the plugin.

If you are on an older version of the PrestaShop plugin, you might be using the Adyen API key that does not have sufficient roles to access the management API. An API key is considered invalid if it has insufficient roles or if webhook registration/HMAC registration/test fails.

If this is the case, during the migration process, the integration will detect that the current Adyen API key stored in the configuration does not have sufficient roles.

The migration process will migrate configured connection credentials, payment methods, transaction logs, and transaction details for orders placed with Adyen payment methods in the last 30 days.

All payment methods that are not supported by the new plugin will be deactivated. In the case of a multistore environment, after the migration process ends, payment methods will be available in shops where a valid API key is present. The merchant will have to manually reconnect and configure a plugin for every PrestaShop sub-store where an invalid API key was detected.

Since integration cannot keep track of which orders were captured before the migration process, the integration will enable all actions for those orders (cancel, capture, refund). It will rely on Adyen API to refuse invalid actions.


Release notes

We are excited to introduce a significant update to the PrestaShop plugin, packed with a fresh and enhanced user experience (UI/UX). Version 5.0.0 brings forth a range of new features, improvements, and optimizations that elevate your store's capabilities.

What's Changed

  • New admin user interface and experience - Navigate effortlessly through an enhanced interface designed for simplicity and seamless plugin configuration.
  • Expanded payment method options - Introducing new supported payment methods, giving customers more choices and convenience during checkout.
  • Payment methods as a full express option - Offer customers more options with new supported payment methods, including the checkout express lineup: Apple Pay, Google Pay, Amazon Pay, and Paypal.
  • Revamped checkout - Benefit from the latest version of Adyen's Checkout API, but also with the new implementation of the checkout and payment process that meets PrestaShop best practices.
  • Partial refunds - Easily process partial refunds, providing greater flexibility in handling customer returns.
  • Partial capture - Seamlessly capture funds partially, granting you flexibility in managing complex orders.
  • Capture control - Choose between manual and auto-capture of funds, tailoring the payment process to your business needs.
  • Advanced data sending - Send L2 and L3 data for enhanced transaction insights, facilitating smoother business operations.
  • Risk score visibility - View risk scores in order payment details, assisting in informed decision-making and fraud prevention.
  • Adyen Giving - Enable charitable donations through Adyen Giving, allowing your customers to contribute effortlessly during transactions.

Migration From Older Versions

To benefit from all these exciting enhancements, simply update your current plugin to version 5.0.0 through the PrestaShop Moudule Manager. If you are on an older version of the Adyen plugin (version 4.0.7 or older), we strongly recommend reviewing migration notes here before migrating to this major version.

Additionally, it is strongly recommended that migration from the previous version to the new major version is performed on the test environment first.

Troubleshoot

Async process

  1. Issue: Webhook notifications remain in the queue status and orders remain in progress in the shop.

Aden plugin performs most of its work in the background. In order to be able to detect and start background jobs, the {Adyen} plugin simulates long-running (background) the process by asynchronously invoking background worker. In order to work properly with multiple asynchronous operations, the plugin needs the possibility to send a web request to itself. In order to work properly with multiple asynchronous operations, the plugin needs the possibility to send a web request to itself .

Async process URL for Prestashop: [SHOP_URL]/module/adyenofficial/asyncprocess

Please check their server configuration and configure the server so the plugin will be able to send requests to itself.

Connection issues

  1. Issue: “We didn’t recognize this API key” error.

Please make sure that the API key is generated using a merchant account and not the company account.

To confirm that your API key is generated using a merchant account follow these steps in the Adyen Customer Area:

  • Navigate to the bottom of the page within the API credential you created and expand the Accounts section.
  • You will see two options: Company account and all associated merchant accounts and Only selected account groups and merchant accounts.
  • Choose Only selected account groups and merchant accounts, then select the specific merchant account

These steps ensure that the API key is associated with the desired merchant account and not the company account.

  1. Issue: Connecting with the merchant account gives an error in the interface 'Merchant account is not connected to the provided credentials'.

Check web server configuration and verify if PHP’s $_SERVER array is empty, as Adyen’s library for verifying webhook uses $_SERVER in order to retrieve webhook’s username and password sent in the request, but if they are empty, the verification will fail. Therefore, check if the server supports and allows the creation of PHP_AUTH_USER and PHP_AUTH_PW fields (PHP: HTTP authentication with PHP - Manual ).

Note: php-cgi under Apache does not pass HTTP Basic user/pass to PHP by default, there is a workaround for this case to work, add these lines to your .htaccess file:

RewriteCond %{HTTP:Authorization} ^(.+)$ RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

The plugin will pick up .htaccess-specific authorization headers.

Help

We are happy to help and answer any of your questions as quickly as possible, therefore please follow the channels of communication below! :)

If you have encountered issue with Adyen plugin for PrestaShop, you can either:

Clone this wiki locally