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 Settings > 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 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.

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

Field	Instruction
API Endpoint URL Prefix	The prefix for your live URL. Get it from your Adyen live Customer Area > Developers > API URLs > Prefix. This field is only required if you're using the live environment.
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 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.

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 Customer Area.
2. Select Developers > Webhooks.
3. Select + Webhook.
4. Under Recommended webhooks > Standard notification select Add.
5. Select the toggle to make the standard notification Enabled.
6. Select the edit icon for Server configuration.
7. Enter:
   • URL: Your website URL followed by adyenv6notification/adyen/v6/notification/[SiteId]/json.
   • Method: JSON
   • SSL Version: TLSv1.2
     Select Apply.
8. Under Security > Basic authentication, select the edit icon . Enter your server's username and password. Select Apply.
9. Select Save changes.

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: 

Your server must acknowledge webhooks with a response message.

1. Log in to your Customer Area.
2. Select Developers > Webhooks.
3. Select the edit icon for the webhook to test. You can test only the event codes you configured for this webhook.
4. Select Test configuration.
5. If you're on a company account, select a Merchant account from the dropdown list.
6. In the Event dropdown list, select the event code to test webhooks for.

If the test webhook failed, you get an error message with the reason. Troubleshoot the problem.

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.