Introduction

Adyen is a payment provider that offers a range of additional payment options. Aurora's integration with Adyen allows your customers to make use of Adyen's payment methods when placing orders via the Aurora Front-end.

Supported Payment Services/Providers

Adyen provides access to a range of payment providers and services, many of which are fully compatible with Aurora's Adyen Payment Integration. This includes card payments (e.g. Debit and Credit Cards) and other 'Local Payment Methods', such as ApplePay and Google Pay.

While this is true, and successful implementation of any one of these is little more then a matter of integrating the appropriate Adyen Component into your Front-end Checkout Template's, we have produced a list of services that during development and deployment, we have been able to confirm have been tested and confirmed to work:

• ApplePay
• Credit/Debit Cards (Scheme in Adyen), including the 3D Secure v1 and v2 flows.
• GiroPay (for Germany in Euros only).
• Google Pay
• Klarna - Pay Later

❗️

Note that Klarna only supports the DEFERRED payment type, as described in the Adyen documentation here.

🚧

Aurora Commerce has made an effort to provide all of the data it can currently support to Adyen and so most other Adyen Local Payment Methods should work. This being said, they have not yet been tested and it is strongly recommended that you test any new service thoroughly before planning a Go-Live proposal to ensure that it works as desired and that no additional development is required to support it.

Initial Setup

🚧

The Adyen Integration uses the Aurora Microservice (MS) framework, and as such must be set-up in advance of it's full activation on your Store.

Doing this requires a one-off development to configure your Server(s) to provide the service, after which, you can then configure the integration at your own leisure.

If you have not yet had (or do not know if you have had) the Adyen MS set up and configured for your Store, then please contact your Agency for more details regarding how to get this done.

Configuration which need to be set up:

• Generate API key
• Enable Merchant account
• Generate HMAC Secret
• Generate Origin key
• Capture Delay
• Fraud data sent with Adyen API responses

The Aurora integration requires you to have a web service user,  HMAC signatures and notifications systems on your Adyen account. Find out more detail regarding how to do this below (if this is not done, the Adyen payment service will not operate as expected with Aurora):

• How to create a Web Service user can be read here.
• How to enable HMAC signatures can be read here.
• How to set up notifications system can be read here.
• Change Capture delay to "manual" in Adyen admin console  Account > Configure > Settings > Capture Delay
• To add Fraud data to API responses:
  • in Adyen admin console Account > Configure > API URLs > Additional data settings
  • check the box Risk > Fraud result and save
• To add credit card summary data (name, last 4 digits, expiry & card type) to API responses:
  • in Adyen admin console Account > Configure > API URLs > Additional data settings
  • check the boxes Card > Cardholder name, Card > Card summary, Card > Expiry Date & Card > Variant and save

Aurora Backend Settings

👍

This section describes how to configure the Adyen integration for use on your Store's Front-end once it has been enabled for use on your Store(s).

Once the Adyen integration has been enabled for your Store(s) to use (which is a process that requires you to contact your Agency to complete), you can follow these steps to allow your customers to use it on your Store(s) checkout.

Enable the Adyen Microservice

Store > Settings > Feeds > Microservice > Proxy Adyen

Configure visibility of the Adyen payment option (in conjunction with the "Payment Types Accepted at Checkout" setting):

🚧

This 'visibility behaviour' is enforced entirely within the Aurora Front-end Templates and so is the default behaviour offered by the Aurora Demo Example Front-end Templates, but may not be how your own Front-end Templates are configured.

If you run into issues with payment option visibility, please check your Front-end Templates for the appropriate logic.

Payment Types Accepted at Checkout

Store > Settings > Payment Providers

Configure Aurora to accept orders using the Adyen payment type:

🚧

This 'visibility behaviour' is enforced entirely within the Aurora Front-end Templates and so is the default behaviour offered by the Aurora Demo Example Front-end Templates, but may not be how your own Front-end Templates are configured.

If you run into issues with payment option visibility, please check your Front-end Templates for the appropriate logic.

Microservice Settings

The Adyen settings are configured from the Store > Microservices > Proxy Adyen section of the Aurora Back-end. This page controls the settings used by Aurora to contact the Adyen service.

Enable the Adyen Payment Provider

Once the MS is enabled and configured, you should tell Aurora that it can accept orders using the Adyen payment option(s). To do this go to the Store > Settings > Payment Providers section of the Aurora Back-end and enable Adyen provider checkbox.

Frontend Template Integration

Assets and Templates

The Adyen integration requires a range of changes to be applied to Front-end templates in order to include it in your checkout process. This section describes what templates and/or JavaScript files are required for the Adyen integration, and so may need to be added to your Front-end Templates.

There are two implementations for using Adyen payments on your website:

1. Adyen Payment Options Integration - For use on your checkout which displays a list of payment options to your customer
2. Adyen Payment Components Integration - For use on the Basket & PDP (Product display page) to render "Pay with" components, such as Apple Pay & Google Pay.

There are two implementations due to the fact that the process is very different. The checkout renders all available Adyen payment methods where as the Adyen Payment Components render only specific components.

Please refer to the relevant page for implementation notes. Both implementations can be used on your website at the same time.

Mapping additional LineItems data from the templates

The Adyen PaymentPlugin sends LineItem data to the Adyen API Adyen LineItems. You may submit additional line item data by submitting Ordered Item Additional Fields during payment-setup with a specific prefix adyen_li_map_. For example, if you wish to submit the Adyen LineItem DataPoint productUrl you could do this by submitting an Ordered Item Additional Field with the name adyen_li_map_productUrl. You can see more information about how to submit Ordered Item Additional Fields during checkout in this document: Submitting Ordered Item Fields. However, Adyen specific instructions follow:

📘

Ensure you create the Ordered Item Additional Fields

Ordered Item Additional Fields will not be stored unless the field is first created within the Ordered Item Additional Fields UI within Aurora.

Please see Ordered Item Fields UI for more information.

See the following AuroraDemo templates with changes that enables this:

• Hidden field template files. In the following files, see the new hidden fields added to the form to submit the productUrl and imageUrl Adyen LineItem data points (examples given in the following code block)
  • example.com/checkout/adyen/payment-methods.tpl.html
  • example.com/basket/adyen-component-buttons.tpl.html
  • example.com/products/adyen-component-buttons.tpl.html
• example.com/_js/aapc.js Ensure the changes from this file which serialises the fields and includes them in the submit data in the method $.aapc.setupSubmit are included in your implementation of this file.

{foreach from=$mini_basket item=basket_item}
	<input name="ordered_items_additional_fields[{$basket_item.id}][adyen_li_map_productUrl]" type="hidden" value="http{if $smarty.server.HTTPS}s{/if}://{$smarty.server.HTTP_HOST}{$basket_item.product.product_filename}">
	<input name="ordered_items_additional_fields[{$basket_item.id}][adyen_li_map_imageUrl]" type="hidden" value="{product_image_uri product=$basket_item.product width=280 height=280 https=1}">
{/foreach}

<div id="adyen-order-fields">
  {*
   * Fields submitted with name "ordered_items_additional_fields" and keyed by the Basket Item ID
   * will result in the ordered_item for that basket item getting the additional field value set.
   * Please note the following:
   * - The Ordered Items Additional Fields records named must have been created in Aurora for this to work.
   *}
  {foreach from=$minibasket item=basket_item}
  <input name="ordered_items_additional_fields[{$basket_item.id}][adyen_li_map_productUrl]" type="hidden" value="http{if $smarty.server.HTTPS}s{/if}://{$smarty.server.HTTP_HOST}{$basket_item.product.product_filename}">
  <input name="ordered_items_additional_fields[{$basket_item.id}][adyen_li_map_imageUrl]" type="hidden" value="{product_image_uri product=$basket_item.product width=280 height=280 https=1}">
  {/foreach}
</div>

<div id="adyen-order-fields">
  {*
   * Fields submitted with name "ordered_items_additional_fields[FIELD_NAME]" will result in the ordered_item having
   * the additional field value set.
   * Please note the following:
   * - This is slightly different to the similar implementation of this in the basket
   *   (see templates/example.com/basket/adyen-order-fields.tpl.html) where basket items are looped and the field
   * - The Ordered Items Additional Fields records named must have been created in Aurora for this to work.
   *}
  <input name="ordered_items_additional_fields[adyen_li_map_productUrl]" type="hidden" value="http{if $smarty.server.HTTPS}s{/if}://{$smarty.server.HTTP_HOST}{$basket_item.product.product_filename}">
  <input name="ordered_items_additional_fields[adyen_li_map_imageUrl]" type="hidden" value="{product_image_uri product=$basket_item.product width=280 height=280 https=1}">
</div>

LineItems data which Aurora defines and cannot be overridden

The following Adyen LineItems data points are defined by the Aurora Adyen Payment Plugin. Any attempts to map these from the Ordered Item Additional Fields as documented above will be ignored:

• quantity
• description
• taxPercentage
• amountExcludingTax
• taxAmount
• amountIncludingTax

LineItems data which can be mapped from Ordered Item Additional Fields

Any Adyen LineItems data points not in the list above can be mapped from Ordered Item Additional Fields as documented above, providing the Additional Field has been added to Auroras Ordered Item Additional Fields UI.

For example:

🚧

We do not validate LineItem keys

Please note that we do not maintain a list of valid Adyen LineItem data points. If you were to submit an Ordered Item Additional Field with name adyen_li_map_notExists then the LineItem Data for that basket item will include a key notExists. The Adyen API will likely return an error response code due to an unrecognised LineItem parameter and the payment will fail.

This allows you to add new line item data in the future as Adyen expands their API without Aurora needing to maintain the list of valid LineItem data points.

Testing

Please see the following documentation from Adyen on testing: https://docs.adyen.com/development-resources/test-cards

• Note that Adyen notifications setup (see below) is required for pending transactions.

Known Limitations

Refunds

When transactions are refunded, Adyen starts this process, but doesn't provide a "complete" status as the refund may not complete instantly - the final status of the refund will not be known until later, after Adyen has finished the refund. In the meantime, Aurora will assign a PENDING status to the transaction. Upon completion of the refund, the transactions status will be updated to OK.

Releases

When an order is placed with a transaction type of DEFERRED, subsequent changes of the orders status, for example to Despatched, can trigger an automatic release. Adyen starts this process, but doesn't provide a "complete" status as the release may not complete instantly - the final status of the release will not be known until later, after Adyen has finished the release. In the meantime, Aurora will assign a PENDING status to the transaction. Upon completion of the release, the transactions status will be updated to OK. The same is true for the manual release action.

Multiple Partial Captures

The Adyen integration does not currently support multiple partial captures. Any partial capture for an amount less that the order total will result in the rest of the value on the order being voided. In Adyen the order will be marked as settled.

Basket Components and Third Party Delivery Store Service Support

Aurora supports a number of third party delivery store services, which integrate with services such as Doddle and DPD.

The Adyen basket payment buttons do not currently work with all services.

The following store delivery options are supported with Adyen basket payment buttons:

• Aurora customer store locations
• Collect+