Skip to content

Installation Instructions

Jump to bottom
JL Alías E2Y edited this page May 16, 2023 · 1 revision

Before you begin

  • Create a test account with Adyen.
  • With this, you have access to the test Customer Area,
  • Apply for a live account.
  • While you wait for your live account credentials, you can start integrating by using your test account.

Installing 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 2005), 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 2005), 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

Configuring 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:

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

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:

  1. Log in to your Adyen Customer Area.
  2. Go to Account > Settings.
  3. 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.
  4. 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:

API Endpoint URL Prefix

Web Service User API Key

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:

Web Service User Client Key

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:

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 Customer Area.
  2. Select Developers > Webhooks.
  3. Select the edit icon for the webhook you wish to test.
  4. Select Test configuration.
  5. Select the notifications you want to test.
  6. Select Test to run the test. You can use the icon to see the details of the test notification that was sent.

Point of sale (POS) settings

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

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

Set up the OCC extension

The Adyen payments add-on supports SAP Omni Commerce Connect (OCC) V2 through com.adyen.v6.facades.AdyenCheckoutFacade.

With this integration, you can accept:

Return the stored cards associated with the shopping cart

  • OCC controller: UsersController.getPaymentInfos
  • Endpoint: GET /{USER_ID}/paymentdetails

Internally, this calls the following method:

  PaymentDetailsListWsDTO getPaymentDetails(String userId) throws IOException, ApiException;

Receive and store payment details

  • OCC controller: CartsController.addPaymentDetails
  • Endpoint: POST /{CART_ID}/paymentdetails

Depending on the payment method, you may need to pass some additional parameters:

  • Credit cards: Encrypted cardholder data. For more information, refer to Cards.
  • Stored cards: The recurringDetailReference, the shopperReference, and the encrypted CVC. For more information, refer to Create and use tokens.
  • Installments: The number of installments. For more information, refer to Credit cards.
  • Boleto: The social security number. For more information, refer to Boleto.

For example, to make an installments payment and store credit card details, submit a POST /{CART_ID}/paymentdetails request, providing:

{
   "encryptedCardNumber": "adyenjs_0_1_1 ...",
   "encryptedExpiryMonth": "adyenjs_0_1_1 ...",
   "encryptedExpiryYear": "adyenjs_0_1_1 ...",
   "encryptedSecurityCode": "adyenjs_0_1_1 ...",
   "installments": "10",
   "saveCardData": true,
   "accountHolderName": "ABC",
   "cardNumber": "4111111111111222",
   "expiryMonth": "03",
   "expiryYear": "2030",
   "cardType" : {"code": "visa"},
   "adyenPaymentMethod": "adyen_cc",
   "billingAddress" : {
     "titleCode": "mr",
     "firstName": "Joao",
     "lastName": "Paulo",
     "line1": "Rua Luiz Fernandes",
     "town": "SJC",
     "postalCode": "12236750",
     "country": {"isocode": "BR"},
     "shippingAddress": true,
     "region" : {
      "countryIso" : "BR",
      "isocode": "SP",
      "name": "Sao Paulo"
     }
   }
 }

Internally, this calls the following method:

PaymentDetailsWsDTO addPaymentDetails(PaymentDetailsWsDTO paymentDetails, DataMapper dataMapper);

Place an order using stored payment details

After storing payment information using the above methods, you can place an order:

  • OCC controller: OrdersController.placeOrder
  • Endpoint: POST /users/{USER_ID}/orders

Internally, this calls the following method:

  OrderData authorisePayment(CartData cartData) throws Exception;

After a successful response from the Adyen API, the system registers the payment response on the cart/order level. It returns an instance of OrderWSDTO obtained from OrderData of the placed order.

For Boleto, the response contains the URL to the PDF, the Base64 encoded data, the expiration date, and the due date.

Set up the notification extension

If you want to receive Adyen notifications, add the following Adyen extension to the config/localextensions.xml file:

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

After you have added the notification extension, set up notifications in your Adyen Customer Area.

 

Go-live checklist

Follow this checklist before you start accepting live payments.

The setup from your test environment is not copied over to your live environment, so you need to configure live settings for:

After you have configured your live Customer Area and the SAP back office, test your integration by making real payments.

Account

Set up your live account structure

Give team members access to the live environment

Set up payment methods

The add-on renders the payment methods based on what is enabled in your Customer Area.

Finance

Receive payouts from Adyen

Use reports for reconciliation

(Optional) Set up a Reserve

  • Consider setting up a Reserve: this is used for refunds and other operational expenses in case of insufficient in-process funds.

Risk and compliance

Risk webinar

By default, your Adyen account has a risk profile based on industry standards.

To learn more about risk management with Adyen, sign up for an upcoming webinar.

3D Secure

Note that for Visa and Mastercard, the enrollment for 3D Secure can take up to seven days. This means that you might not be able to offer 3D Secure to your shoppers immediately after your live Customer Area has been activated.

Compliance

When using our SAP Commerce add-on, you need to assess your PCI DSS compliance according to the Self-Assessment Questionnaire A (SAQ A).

API communication

  • Set up API credentials in your live Customer Area, and in the SAP back office.
  • Make sure your live API credentials have the following permissions:
    • Merchant PAL webservice role
    • Merchant Recurring role
    • Checkout webservice role
    • Checkout encrypted cardholder data

Notification webhooks

End-to-end testing

To make sure your integration can handle the entire payment lifecycle with real payment details, you need to test possible scenarios with real payment details.

Payments with real details incur fees. To have enough funds available for refunds, consider setting up a Reserve.

  • For each payment method that you offer, make a successful payment using real details.
  • Make a payment with resultCode: Refused, for example by entering incorrect card details.
  • Make a payment with refusalReason: FRAUD, by triggering multiple risk checks to achieve a risk score above 100.
  • Make a refund using our API, including a partial refund.

Capture

3D Secure

  • Make a successful payment with 3D Secure authentication.
  • Make a 3D Secure payment where the shopper fails to complete the challenge.
  • Make sure that 3D Secure is triggered correctly according to your Dynamic 3D Secure settings and your risk profile.

Upgrade the add-on

To stay up to date on the released fixes and features, subscribe to our releases on GitHub. We recommend that you upgrade when we have a major release, such as 11.0.0. The integration effort involved in upgrading depends on whether you have made any customizations to the add-on.

Default integration

  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. 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
  1. Run a database update on the Administration Console`

Customized integration

  1. Extract any custom code you have added to the add-on.
  2. Download the latest version available on GitHub.
  3. Copy the files to: ${HYBRIS_BIN_DIR} > Custom > [YourHybrisInstallationFolder].
  4. Verify the folder and file permissions of the copied files.
  5. 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
  1. Run a database update on the Administration Console
  2. Check if the custom code is compatible with the new version and apply any changes if needed.

Extra Configuration Steps for India Merchants

Merchants accepting payments in India have to make changes to the following configuration:

  1. In BackOffice, go to Base Commerce > Base store, and select the store that will accept payments from India, then open Adyen tab.
  2. Set the Adyen Test mode field to False.
  3. In the Region dropdown menu, select "IN".
  4. Replace test credentials with live credentials.
  5. Set the API Endpoint URL Prefix with the Indian Live URL prefix and the company name (e.g. 1797a841fbb37ca7-AdyenDemo).

Introduction

Supported Versions

Supported Features

Supported Payment Methods

Installation Instructions

Before you begin

Installing the Add-on

Configuring the add-on

Setting up the OCC extension

Go-live checklist

Upgrade the add-on

Extra configuration steps for India merchants

Checkout Flow

Default Flow

Checkout Image

Payment Flow Diagram

Order Management , Notifications and Events

Order Management

Payment Pending

Authorisation

Capture + partial

Cancellations

Refunds + partial

Notifications

basic auth

cronjob

event handling

supported list of events

API

Components

Facades

Services

Models

Populators

Controllers

Clone this wiki locally