Set up the add-on

To use the Adyen payments add-on for SAP Commerce, you need to install the add-on and configure it in your SAP back office and in the Adyen Customer Area.

Before you begin

Make sure that you have created a test account with Adyen. With this, you'll be able to access the test Customer Area, and apply for a live account. While you wait for your live account credentials, you can start integrating by using your test account. 

Install the add-on

Adyen's payments add-on for SAP Commerce is open-source and available on GitHub. To install it:

1. Download the latest version available on GitHub.
2. Copy the files to: ${HYBRIS_BIN_DIR} > Custom > [YourHybrisInstallationFolder].
3. Verify the folder and file permissions of the copied files.

4. Add the Adyen extensions to the config/localextensions.xml file:

   <extension dir="${HYBRIS_BIN_DIR}/custom/adyenv6core"/>
   <extension dir="${HYBRIS_BIN_DIR}/custom/adyenv6b2ccheckoutaddon"/>
   <extension dir="${HYBRIS_BIN_DIR}/custom/adyenv6backoffice"/>

   To configure the Adyen notification service, add:

   <extension dir="${HYBRIS_BIN_DIR}/custom/adyen-hybris/adyenv6notification"/>

   If you are using yacceleratorordermanagement (b2c_acc_oms recipe for 6.x and b2c_b2b_acc_oms for 1905), also add:

   <extension dir="${HYBRIS_BIN_DIR}/custom/adyenv6ordermanagement"/>

   If you are using yacceleratorfulfilment (b2c_acc recipe for 6.x and b2c_acc_plus_ for 1905), also add:

   <extension dir="${HYBRIS_BIN_DIR}/custom/adyen-hybris/adyenv6fulfilmentprocess"/>

5. Modify the config/local.properties file:

   • Append ,/[^/]+(/[^?]*)+(adyen-response)$,/adyen(/[^?]*)+$ to the csrf.allowed.url.patterns value.
   • Add is3DS2allowed = true.

6. Install the Adyen add-on into your existing storefront template:

   cd bin/platform
   . ./setantenv.sh
   ant addoninstall -Daddonnames="adyenv6b2ccheckoutaddon" -DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront"
   ant clean all

Configure the add-on

1. Log in to your SAP back office
2. Go to BaseStore > Adyen. 
   This opens a page with settings for the Adyen add-on. 
3. Configure the settings by following the instructions below.

Account settings

Fill out the following fields:

Field name	Instruction
Merchant account name	The name of your Adyen merchant account for which the payments will be processed. You can find this in the upper-right corner of your Customer Area.
Immediate capture flow	This has to match the capture delay that you set in the Adyen Customer Area. If you set Capture Delay to manual, set Immediate capture flow to False. Otherwise, set Immediate capture flow to True. To set the capture delay in the Adyen Customer Area: Log in to your Adyen Customer Area. Go to Account > Settings. In the Capture Delay drop-down menu, select one of the following:  immediate if you want payments to be captured immediately after authorisation (this is the default setting). the number of days between authorisation and automatic capture. manual if you want to capture all payments manually from the SAP back office. Select Submit.
Allowed Credit Card Types	Select which credit card types you want to allow in the checkout form. You also need to enable these credit card types in the Adyen Customer Area.
Recurring contract type	Select the type of recurring transactions that you want to enable. Possible values: RECURRING  – Enable stored payment methods for shopper-not-present transactions. ONECLICK – Enable stored payment methods for shopper-present transactions. For credit cards, the shopper needs to enter their CVC/CVV to complete the payment. RECURRING,ONECLICK – Enable stored payment methods for both shopper-present and shopper-not-present transactions.
Adyen Test mode	Select True if you are using the Adyen test environment, and False if you are using the Adyen live environment.
Enable Guest Checkout Tokenization	Select True if you want to enable tokenization of card payment details of guest users. Default is false.

API settings

For authenticating API requests from your SAP back office, you need to set up an API key. 

You first need to set up an API key in your Adyen Customer Area:

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the credential for your integration, for example ws.
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 restore it later.
   If your API key is lost or compromised, you need to generate a new one.
5. Select Save at the bottom of the page.

Then fill out the following fields in your SAP back office:

Field	Instruction
API Endpoint URL Prefix	Enter the URL prefix [random]-[company name] from your Adyen live Customer Area > Account > API URLs. For more information, refer to Checkout endpoints.
Web Service User API Key	The API key from your Adyen Customer Area.

Client key settings

When using the plugin on versions 9.0.0 and above, you need to set up client key for client-side authentication. The client key is linked to your API credential and a list of domains from which we expect to get your client-side requests.

You first need to set up a client key in your Adyen Customer Area:

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the API credential for your integration, for example ws@Company.[YourCompanyAccount].
3. Add your domains under Allowed origins. These are the domains from which you will be sending your client-side requests.
4. Under Authentication, select Generate New Client Key.
5. Select Save.

Then fill out the following field in your SAP back office:

Field	Instruction
Web Service User Client Key	The client key from your Adyen Customer Area.

Additional data in API response settings

To process the response received from Adyen, you need to configure your merchant account to include additional data in the API response.

1. Log in to your Customer Area with your merchant-level account.
2. Go to Developers > API URLs.

3. In the Additional data in API response section, select the following fields:

   • Variant: Required. This provides the payment method in the response.
   • Acquirer result: This provides additional information such as AuthCode and AvsResult.
   • Cardholder name
   • Card bin
   • Card summary
   • Expiry date
   • 3D Secure result: This provides 3D Secure-related information.
   • Fraud result: This provides fraud check results.

Server notification settings

To inform your SAP back office of payment status changes, Adyen uses notifications, sent as HTTP callbacks (webhooks) to endpoints on your server.

You first need to set up notifications in your Adyen Customer Area:  

1. Log in to your Adyen Customer Area.
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:
    adyenv6notification/adyen/v6/notification/[SiteId]/json
   For example: https://your-website-URL/adyenv6notification/adyen/v6/notification/electronics/json
6. Select the Active check box.
7. From the Method dropdown, select JSON.
8. In the Authentication pane, enter a User Name and Password for notifications.
9. Store these credentials securely in your system.
10. Select Save Configuration.

Then fill out the following fields in your SAP back office:

Field	Instruction
Server Communication HTTP Basic username	The username for notifications from your Adyen Customer Area.
Server Communication HTTP Basic password	The password for notifications from your Adyen Customer Area.

Test notifications

To test whether notifications have been configured correctly: 

1. Log in to your Adyen Customer Area.
2. Go to Developers > Webhooks.
3. Next to Standard Notification, select the edit webhook icon . 
4. In the Test Notifications pane, select Test Configuration. 
5. If the result is [Accepted], your notifications are working correctly.

Point of sale (POS) settings

To configure the add-on for in-person payments, fill out the following fields in your SAP back office:

Field name	Instruction
POS Merchant Account	The name of your Adyen merchant account for which the point of sale transactions will be processed. You can find this in the upper-right corner of your Customer Area. This can be the same merchant account that you added under Account settings.
POS API Key	The API key associated with your merchant account for point of sale. For instructions on how to find this, refer to API settings.
POS Store ID	The ID of your store for processing point of sale payments. To find this, log in to your Customer Area with your merchant account, and go to Point of sale > Stores.
Recurring contract type	If you want to save the payment details of an in-store shopper, you need to choose the type of recurring contract that you want to use: NONE – Do not enable stored payment methods. RECURRING – Enable stored payment methods for shopper-not-present transactions. ONECLICK – Enable stored payment methods for shopper-present transactions. For credit cards, the shopper needs to enter their CVC/CVV to complete the payment. RECURRING,ONECLICK – Enable stored payment methods for both shopper-present and shopper-not-present transactions.

To find the payment receipt for a point-of-sale transaction:

1. Log in to your SAP back office.
2. Go to the Orders section, and click on the transaction.
3. Go to the PAYMENT AND DELIVERY tab, and select PaymentInfo.
   This opens a new window containing the POS Receipt field.

Boleto

To accept Boleto payments:

1. In your SAP back office, go to the Advanced Settings section.
2. Set Enable Boleto to True.

PayPal

To accept PayPal payments, you need to add your PayPal Merchant ID to your configuration:

1. Follow the steps in Obtaining your PayPal Merchant ID
   to find your PayPal Merchant ID.
2. In your SAP back office, go to the Advanced Settings section.
3. In the PayPal Merchant ID field, enter your ID.