Skip to main content

How To Configure Adyen Payment Service Integration

Introduction​

Adyen is a global payment platform that provides in-store payment processing through point-of-sale terminals (PEDs). The Enactor Retail System supports Adyen as a Payment Service provider, allowing POS terminals to process card payments and refunds through Adyen-integrated PEDs via the Payment Device Controller (PDC).

The integration uses the Adyen Terminal API for local communication between the PDC and the PED. Settlement notifications are delivered via Adyen webhooks to an endpoint hosted by the Adyen Integration Services (AIS) component.

The purpose of this guide is to demonstrate the steps required to configure the Adyen payment service integration end-to-end, covering Adyen portal settings, Estate Manager entity configuration, PDC installation, and broadcasting the application update to the POS.

Overview​

The following steps are required to enable the Adyen payment service integration:

  1. Adyen Portal Configuration - Enable the Terminal API, configure webhook URLs for settlement notifications, and set the capture delay
  2. Account Credentials Maintenance - Create account credentials for the Adyen payment service with API key, HMAC key, and PED encryption keys
  3. Tender Maintenance - Create a Payment Service tender
  4. Menu Set Maintenance - Add the PaymentServiceTender event to the POS menu set
  5. Menu Maintenance - Add payment and refund buttons to the POS tender menus
  6. Payment Device Maintenance - Create a payment device record for each Adyen PED
  7. Device Maintenance - Create a device record for the payment service
  8. Payment Device Host Maintenance - Create the payment device host linking the device to the payment devices
  9. POS Terminal Maintenance - Configure the POS terminal peripherals to connect to the PDC
  10. User Role Maintenance - Assign payment service privileges to POS Operator and TMS Login User roles
  11. PDC Configuration - Install and configure the Payment Device Controller
  12. Broadcasting - Deliver the application update to the POS and PDC

Prerequisites​

Before starting, you should have the following resources in place:

  • Enactor POS (configured and operational)
  • Payment Device Host (PDC)
  • Enactor Estate Manager (EM)
  • Payment Device Management Service (PDMS)
  • Adyen Web Configuration Dashboard with login credentials
  • Adyen-integrated PED (e.g. P400Plus)
info

The Payment Device Host and a POS application must share the same host machine. Ensure both are installed on the same PC before proceeding with this guide.

Configuration Steps - Adyen Portal​

The first set of configuration steps are performed in the Adyen Web Configuration Dashboard (Adyen Customer Area), not in the Enactor Estate Manager.

Adyen Integration Services (AIS) for Settlement Notification Support​

In order to support Settlement Notifications sent by Adyen, an endpoint supporting the Adyen webhook format must be accessible to Adyen over the internet.

  1. Log in to the Adyen Customer Area
  2. Register an account for the Adyen Integration Services (AIS)
  3. Configure a key for the PEDs. See the "Set up a shared key" section of the Adyen documentation on protecting local communications for details
note

There are no Enactor restrictions on what to use as a key identifier, version, or passphrase. If the key is configured at the store level, the key must be passed down to the terminal.

  1. Configure device communication settings in the Adyen Customer Area under Point of sale > Terminal settings

Adyen Customer Area Terminal Settings on the Integrations tab. Enable terminal API is set to Enabled. Event URLs and Display URLs are configured with the AdyenIntegration notification endpoint.

The Adyen Terminal Settings Integrations page controls communication between Adyen and the Enactor PDC. Set Enable terminal API to Enabled. Enter the notification endpoint URL in both Event URLs and Display URLs fields.

These settings can be configured at an Account, Terminal, All Terminals, or Store level, with each level inheriting settings from a higher level.

SettingValue
Enable terminal APIEnabled
Event URLshttps://<server>:8843/AdyenIntegration/rest/notifications
Display URLshttps://<server>:8843/AdyenIntegration/rest/notifications
info

Replace <server> with the hostname or IP address of the server hosting the Adyen Integration Services endpoint. The port 8843 is the default HTTPS port for the AIS component.

This completes the Adyen Integration Services configuration.

Setting Delayed Automatic Capture​

By default, payments are captured immediately after authorisation. Setting up a delay between the authorisation and the automatic capture gives you time to cancel the authorisation. This is useful when:

  • A shopper changes their mind soon after purchase
  • Store staff realise they made a mistake after a payment is approved
  • The shopper needs to provide a signature and staff need time to verify it

Without capture delay, you would need to issue a refund in these situations.

To set up a capture delay:

  1. Log in to the Adyen Customer Area
  2. Switch to your merchant account
  3. Navigate to Settings > Account settings
  4. In the General settings, next to POS capture delay, select the edit icon
  5. From the dropdown list, select a capture delay of minutes, hours, or days before point-of-sale payments are automatically captured
  6. Select Save
tip

Adyen recommends selecting a delay of 2 hours. If you no longer want to use delayed capture, select Immediate.

note

The Merchant Admin role is required to change capture settings. This role is not configured through the Enactor Estate Manager - it is managed in the Adyen Customer Area.

This completes the Adyen portal configuration.

Configuration Steps - Estate Manager​

The following configuration steps are all performed in the Enactor Estate Manager.

Account Credentials Maintenance​

Create new account credentials for the Adyen payment service.

Navigate to Account Credential Maintenance using the Search:

Account Credential Maintenance

  1. Select Create a new Account Credential
  2. Enter an appropriate Account Credential ID
  3. On the General tab, set the following fields:
FieldValue
Account TypeAdyenPaymentService
NameAdyen Payment Service
Is Livetrue
Use System Keytrue
  1. Navigate to the Other Properties tab and add the following properties:
Property NameWrite OnlyTypeValue
APIKeyYesStringEnter the API Key obtained from the Adyen Web Configuration dashboard
CertificateNoFileDownload the Adyen public root certificates and upload the PEM file. See the Adyen documentation on installing root certificates for local architecture.
ConnectionTimeoutMillisNoString(Optional) Connection timeout for the connection between Enactor and Adyen. This would not normally need to be defined.
EnableAutomaticCaptureNoString(Optional) Enter false to disable automatic capture. If enabled, the Enactor Adyen integration does not attempt to send capture requests to Adyen, relying instead on Adyen's systems to perform the capture when authorisation is requested.
EnvironmentNoStringEnter LIVE or TEST depending on whether the integration uses the live or test Adyen environment.
HMACKeyYesStringEnter the HMAC Key generated via the Adyen Web Configuration dashboard.
KeyIdentifierNoStringEnter the Key Identifier of the key created on the Adyen Web Configuration dashboard.
KeyPassphraseYesStringEnter the Key Passphrase of the key created on the Adyen Web Configuration dashboard.
KeyVersionNoStringEnter the Key Version of the key created on the Adyen Web Configuration dashboard.
MerchantAccountNoStringEnter the name of the Merchant Account from the Adyen Web Configuration dashboard.
TransactionTimeoutMillisNoString(Optional) The maximum time allowed for commands sent to Adyen or to the PED to complete before they time out and recovery is allowed.
info

The KeyIdentifier, KeyPassphrase, and KeyVersion values are found in the Adyen portal under In-person payments > Terminals > (select a terminal) > Integrations > Terminal API > Encryption section. The same values must be used in the account credentials.

  1. Select Save

This completes the Account Credentials configuration.

Tender Maintenance​

Create a Payment Service tender for Adyen transactions.

Navigate to Tender Maintenance using the Search:

Tender Maintenance

  1. Select Create a new Tender
  2. Set the following creation fields:
FieldValue
RegionSelect the appropriate region (e.g. Denmark)
Tender TypePayment Service
Tender IDPAYMENT_SERVICE
  1. Select Create
  2. On the General tab:
FieldValue
DescriptionPayment Service (or any appropriate description)
CurrencySelect the appropriate currency (e.g. Danish Kroner)
  1. On the Restrictions 1 tab:
FieldValue
Debits AllowedTrue
Credits AllowedTrue
Prompt With Amount DueTrue

  1. On the Restrictions 2 tab, add a return tender:

    • In the Return Tenders section at the bottom, select Payment Service from the dropdown
    • Select Add

  2. Select Save

  3. Broadcast the Tender using the Data Broadcaster

This completes the Tender configuration.

Add the PaymentServiceTender event to the POS menu set.

Navigate to Menu Set Maintenance using the Search:

Menu Set Maintenance

  1. Edit the menu set with ID POS
  2. Navigate to the Options tab
  3. Select the Tender menu
  4. Add a new Event with name PaymentServiceTender
  5. Select Save

This completes the Menu Set configuration.

Configure POS menu buttons for payment service transactions and refunds.

Add a Payment Service Button (in POS)​

Navigate to Menu Maintenance using the Search:

Menu Maintenance

Set the following filters to locate the TENDER menu:

FilterValue
Menu SetPOS
RoleSelect a role which uses the POS (e.g. Sales Assistant - UK)
Menu GroupSelect the menu group used by the POS terminal (e.g. Standard POS)
Menu IDStarts With TENDER
note

The menu group data can be found in POS Terminal Maintenance under the User Interface section.

Menu Maintenance filter view. Menu Set is POS, Role is Sales Assistant - UK, Menu Group is Standard POS. The TENDER menu is shown in the results.

Use the Menu Maintenance filters to locate the TENDER menu for the appropriate POS role and menu group. Select Apply Filters to search, then edit the TENDER menu from the results.

Edit the TENDER menu and select Add a new Button:

On the Data tab, configure the following:

FieldValue
TypeEvent
EventPaymentServiceTender
IDPaymentServiceTender
Button LabelPayment Service
PositionSelect an available position based on the menu

On the Data tab, add a new key-value pair:

NameJava TypeValue
enactor.mfc.TenderIdStringPAYMENT_SERVICE

Select Save and broadcast the menu change to the POS.

This completes the Payment Service button configuration.

Add a Refund Payment Service Tender Button (in POS)​

Edit the menu with the ID CREDIT_TENDER (using the same menu group and role as above).

  1. Select Add a new Button
  2. On the General tab:
FieldValue
TypeEvent
EventPaymentServiceRefund
IDPaymentServiceRefund
Button LabelPaymentServiceRefund

Menu Maintenance button editor on the Data tab for the CREDIT_TENDER menu. Event is PaymentServiceRefund, ID is PaymentServiceRefund, Button Label is PaymentServiceRefund.

The button editor for the CREDIT_TENDER menu. Set the Type to Event and the Event to PaymentServiceRefund. The Visibility Expression controls when the button appears based on privilege and tender applicability checks.
  1. On the Data tab, add a new key-value pair:
NameJava TypeValue
enactor.mfc.TenderIdStringPAYMENT_SERVICE

Menu Maintenance button editor on the General tab showing Data section. The key-value pair enactor.mfc.TenderId is set to PAYMENT_SERVICE with Java Type String.

The Data section links the refund button to the correct tender. Set Name to enactor.mfc.TenderId, Java Type to String, and Value to PAYMENT_SERVICE.

The completed CREDIT_TENDER menu tree should show the PaymentServiceRefund button alongside the existing tender buttons:

Menu Maintenance tree view showing CREDIT_TENDER menu structure. The PaymentServiceRefund button is highlighted at position 7, between PayPal and Back.

The CREDIT_TENDER menu tree view confirms the PaymentServiceRefund button has been added. The highlighted entry at position 7 is the new refund button.
  1. Select Save and broadcast the menu change to the POS

This completes the Menu Maintenance configuration.

Payment Device Maintenance​

Create a payment device record for each Adyen PED that will be used with the payment service. This step must be executed for every PED.

Navigate to Payment Device Maintenance using the Search:

Payment Device Maintenance

  1. Select Create a new Payment Device with an appropriate ID
  2. Set the following fields:
FieldValue
NameEnter a descriptive name for the PED
LocationThe store location (must be the same as the payment device host)
Service TypePayment Service
Payment Service TypeAdyen
Payment Service Configuration[Adyen]
POIID=P400Plus-{serial number}
Endpoint=https://{ip address displayed on the PED}
Payment Service Account CredentialsSelect the credential created in the Account Credentials step
info

Replace {serial number} with the actual serial number of the Adyen PED and {ip address displayed on the PED} with the IP address shown on the PED device screen. The POIID format depends on the PED model (e.g. P400Plus-123456789).

  1. Select Save

This completes the Payment Device configuration.

Device Maintenance​

Create a device record for the payment service.

Navigate to Device Maintenance using the Search:

Device Maintenance

  1. Select Create a new Device
  2. Set the following fields:
FieldValue
IDAdyen payment service
NameAdyen payment service
Host Namelocalhost
HTTP Port8080
RMI Port2099
TypePayment Service
LocationThe store location (can be configured in Location Maintenance)
  1. Select Save

This completes the Device configuration.

Payment Device Host Maintenance​

Create a payment device host to link the device to the payment devices.

Navigate to Payment Device Host Maintenance using the Search:

Payment Device Host Maintenance

  1. Select Create a new Payment Device Host
  2. On the General tab:
FieldValue
IDEnter an appropriate Payment Device Host ID
Device KeySelect the device created in the Device Maintenance step
Service TypePayment Service
Proxy Addresstcp:7777
Configuration Poll Interval60
Capture MethodEstate Manager
TMS Command Poll Interval (sec)60

  1. On the Payment Devices tab:

    • Select the payment device ID from the dropdown and add it

  2. Select Save

This completes the Payment Device Host configuration.

POS Terminal Maintenance​

Configure the POS terminal to connect to the PDC for payment processing.

Navigate to POS Terminal Maintenance using the Search:

POS Terminal Maintenance

  1. Edit the relevant POS terminal
  2. Navigate to the Peripherals section
  3. Set the following fields:
FieldValue
Payment Service TypeEnactor
Payment Service Addresstcp:{host address of PDC}:7777
Payment Service Timeout (Min)30
info

Replace {host address of PDC} with the hostname or IP address of the machine where the PDC is installed. The port 7777 must match the Proxy Address configured in Payment Device Host Maintenance.

  1. Select Save
  2. Broadcast the change to the POS

This completes the POS Terminal configuration.

User Role Maintenance​

Assign the required privileges for payment service operations.

Navigate to User Roles Maintenance using the Search:

User Roles Maintenance

Select a user role by user ID and add the following authorised functions.

POS Operator​

The following privileges are needed for POS operators to perform transactions using a payment service:

PackageFunction ID
Enactor POSenactor.pos.PaymentServiceTenderAllowed
Enactor POSenactor.pos.PaymentServiceRefundAllowed
Enactor POSenactor.pos.AuthorisesPaymentServiceTender
Enactor POSenactor.pos.AuthorisesPaymentServiceRefund

Broadcast these changes to the POS.

TMS Login User​

Add these privileges to the TMS Login User to access the Payment Device Maintenance application:

PackageFunction IDDescription
Enactor Web Maintenanceenactor.paymentDeviceMaintenance.EditEdit
Enactor Web Maintenanceenactor.paymentDeviceMaintenance.ListList
Enactor Web Maintenanceenactor.paymentDeviceMaintenance.NewNew
Enactor Web Maintenanceenactor.paymentDeviceMaintenance.RemoveRemove
Enactor Web Maintenanceenactor.paymentDeviceMaintenance.RunRun
Enactor Web Maintenanceenactor.paymentDeviceMaintenance.ViewView

Add these privileges to the TMS Login User to access the Payment Device Host Maintenance application:

PackageFunction IDDescription
Enactor Web Maintenanceenactor.paymentDeviceHostMaintenance.EditEdit
Enactor Web Maintenanceenactor.paymentDeviceHostMaintenance.ListList
Enactor Web Maintenanceenactor.paymentDeviceHostMaintenance.NewNew
Enactor Web Maintenanceenactor.paymentDeviceHostMaintenance.RemoveRemove
Enactor Web Maintenanceenactor.paymentDeviceHostMaintenance.RunRun
Enactor Web Maintenanceenactor.paymentDeviceHostMaintenance.ViewView

This completes the User Role configuration.

Configuration Steps - PDC Configuration​

Install and configure the Payment Device Controller on the host machine.

  1. Copy the provided EnactorPDC-2.7.747.RC2.x.x.msi and the installer.ini file into a separate folder
  2. Open the installer.ini file and populate the fields:
FieldValue
PDC_IDReplace PDC_ID_HERE with the Payment Device Host ID configured in the previous step. Record this value for reference.
JDK_LOCATIONReplace PATH_TO_JDK_BIN_FOLDER with the folder path to the JDK. The path should not include the bin folder.
PDC_PRIMARY_TMS_URLReplace SERVER_IP with the IP address of the server where PDMS and EM are hosted. Port should be 39833.
PDC_SECONDARY_TMS_URLReplace SERVER_IP with the IP address of the server where PDMS and EM are hosted. Port should be 39833.
ENACTOR_HOMEIt is best practice to install the PDC and POS applications to C:\Enactor.
PDC_DATABASE_LOCATIONThis should be a directory inside the PDC install folder, e.g. C:\Enactor\pdc\DataBase\.
  1. Install the PDC into C:\Enactor using the MSI installer
note

A POS or PDP server needs to be installed on this PC as well in order to receive the application update.

  1. Replace the pdc-payment-controller.jar in pdc/lib with the provided pdc-payment-controller.jar file

This completes the PDC configuration.

Configuration Steps - Broadcasting the Application Update​

Broadcast the Adyen application update to the target POS device.

Navigate to Application Update Maintenance using the Search:

Application Update Maintenance

  1. Select Create a new Application Update
  2. Select the storage type as File Repository
  3. Select Upload
  4. Browse and select the adyen-x.x.x-update.zip file
  5. Select Upload
  6. Select Extract Content
  7. Select Save

Navigate to the Application Update Broadcaster:

Administration > Data Management > Broadcasts > Application Update Broadcaster

  1. Select the Application Update from the dropdown list
  2. Select the POS device that is hosted on the same PC as the payment device host that needs to integrate Adyen
  3. Select Submit
info

The app update will be received by the target devices. When the app update is received on the host machine, it will trigger a restart. The PDC will copy the jar files to PDC/custom-libs once it has started.

This completes the Broadcasting configuration.