Retail:Adyen Payment Provider
Contents |
Introduction
This document describes the installation and configuration of the Openbravo payment integration with Adyen. Adyen is a global payment company that allows business to accept e-commerce, mobile and point-of-sale payments.
This integration takes advantage of the payment methods grouping by provider functionality that allows to use one single payment button in Web POS and POS2 and select a different payment method depending on the type of card used in the payment transaction: VISA, AMEX,...
This integration supports:
- Payments, contactless payments, refunds
- Cloud and Local architectures
- DCC Support (Dynamic currency conversion)
- Wallet payments (QR)
- Verify the status of the last transactions
- Payment terminal diagnostics
- Payment receipts handled by the POS
Desktop integration
The Web POS or POS2 applications communicates with the Adyen backend through the Hardware Manager, and it is the Adyen backend who manages the communication with the payment device.
The communication with the Adyen backend is based in HTTP and REST, and uses the Adyen's point-of-sale solution.
This is an overview of the architecture.
Installation
Payment terminal
This integration has been developed and tested with the Verifone V400M model. But it will work with any other supported device by Adyen.
First you need to configure your merchant account and board the device provided by Adyen. This is done in the Adyen customer area in the section Point of sale > Devices. Follow the Adyen Board the terminal documentation to configure your account and board the device.
Openbravo application
As System administrator you need first to install the module Adyen Payment Provider. This module implements the integration. After the module is installed, you can rebuild the application and start the configuration. Follow the Modules_Management documentation for the details to install a new module.
In the case one or more payment terminals need to be configured using the Local Adyen architecture, the Adyen hardware manager plugin and certificates must be installed. Live and test certificates can be downloaded from the Adyen site: Protect local communications.
Certificates must be copied to the root folder of the hardware manager and must be named adyen-terminalfleet-live.pem for Local and adyen-terminalfleet-test.pem for Local (Test certificate).
Also the Hardware Manager configuration file openbravohw.properties must include the following entry:
process.adyen = adyen
For more information about the Adyen architectures read the following document: Choose an integration architecture
Configuration
To configure Openbravo log in Openbravo as Company administrator and follow these steps.
In the window Payment Provider create a new record and select in the field Provider the value Adyen. In Name The label to display in the payment button.
In order to test the Openbravo configuration and simulate payments, refunds, void transactions and card adquisitions without having a payment device or a merchant account you can use the provider Adyen Mock. This provider will simulate a connection error if the amount is 100.01, a user cancellation if the amount is 100.02, a success of a partial amount of 50.00 if the amount is 100.03 and success for the full amount in any other case.
![]() | The Adyen Mock provider does not perform real transactions, just simulate them and must not be used in production environments under any circumstances. |
Here you have an example of a 'Payment Provider configuration using Adyen.
In the Organization window, select the store to configure, go to the Adyen Payment Provider and fill in the API Key field. This is the value provided by Adyen to you as a merchant. This can be obtained in the Adyen customer area in the section Account > Users. Follow the Adyen How to get the API key documentation for more detail.
Then complete the payment methods configuration in the windows Channel - Touchpoint and Channel - Touchpoint Type linking in this last window the corresponding payment methods with the Payment Provider created in the previous step and the Payment Method Type assigned to each payment method. For more information about how to configure payment methods using this Payment Provider go to the guide
Payment Methods grouping by Provider.
Payment terminals must be registered in Openbravo in the window Adyen Terminal. Create one record for each device with the following fields:
- Terminal ID. The Adyen unique ID of the terminal, in the format [device model]-[serial number]. For example, P400-123456789.
- Name. A descriptive identifier for the terminal used to display.
- Network. Select Cloud, Local, Cloud (Testing mode) or Local (Testing certificate).
- Has Adyen Printer. It indicates that the payment terminal includes a printer that prints all the payment receipts. In case this field is not checked, it indicates that the payment terminal does not have a printer and the payment receipts will be printed by the main receipt printer configured in the POS.
- In Person Payment Mode. Select Initiate from terminal, Initiate from barcode scanner.
If Initiate from terminal is selected, a normal transaction will occur, asking the client to show his credit card in the Adyen device. Otherwise, if Initiate from barcode scanner is selected, the POS will ask the user to scan a barcode that will kick off a transaction. To use this flow, the POS must include a barcode scanner that can read a QR code, this can be infrared scanner or a camera, and it also must translate this QR code into a numerical value to be in introduced in the field.
If Local is selected the following fields must be filled in too:
- Local URL. The host name or IP of the local network the payment terminal is connected.
- Key Identifier, Key Version and Key Passphrase. The identifiers for Local architecture as configured in the Adyen Customer Area. For the details to configure and obtain these values, read the following document: Set up a shared key
![]() | Under Cloud and Cloud (Testing Mode) a connection error may occur with the following message: Failed+to+send+message+to+POI.+There+may+be+a+network+issue+or+it+may+not+have+the+websocket+connected. To solve this, the payment device needs to have websockets activated. This could be activated through the payment device admin window or opening a support ticket with ADYEN Support Portal |
![]() | Local values Key Identifier, Key Version and Key Passphrase could be found under Adyen Admin Panel. Navigate to menu option "Point of sale" -> Terminal Settings -> Encryption key section |
Here you have an example of a Adyen Terminal record.
Finally in the Channel - Touchpoint window, select the Adyen terminal to be used with each Openbravo POS terminal. Here you must be sure to fill in the Hardware URL field and select in Adyen Terminal one of the terminals registered in the previous step. The field Hardware URL is required. If the cloud architecture is configured, the Adyen integration requires the Hardware Manager running as a proxy for the communications between the POS terminal and the Adyen API. But there is no need to do any configuration in the Hardware Manager. But in case of local architecture, the Hardware Manager is required with the Openbravo Adyen plugin and the correct Adyen certificates as explained in the installation section of the Hardware Manager.
Here you have an example of a POS terminal configured with one Adyen terminal.
To process refunds without requiring card presence in the terminal use Verified Redunds. To enable this, set "Allowed PMs for refund" to "Only Those Defined" and define the payment method in the "Payment Method" window. Note: Adyen validates the transactions, not Openbravo.
Operation
Once everything is configured, the operation of the POS terminal is as usual. In the moment to process a payment transaction select the button with the Payment Provider name configured and add the payment. In this case, a dialog will appear waiting for the Adyen terminal to process the payment. And after the payment is completed. The terminal will print a customer and merchant copy, the dialog will disappear and the payment line will appear in the Web POS application.
When closing the receipt, the receipt will be printed.
If the payment terminal has been configured in Openbravo with the Has Printer field checked. The POS will expect the payment terminal to print the payment receipt, otherwise the POS will print the payment receipt using the main receipt printer configured for the POS touchpoint.
Last transaction
If a new copy of the payment receipt is needed you can go to the POS menu and select the option Adyen Last transaction.
In React POS the configuration and access to this menu option can be done in the tab User Action Access of the window Role. The user action name is Adyen Last Transaction.
Diagnostics
To check the status of the payment terminal select the POS menu option Adyen Diagnostics. A receipt will be printed with a detailed status of the payment terminal.
In React POS the configuration and access to this menu option can be done in the tab User Action Access of the window Role. The user action name is Adyen Diagnostics.
Card acquisition
This integration also allows in Web POS tokenizing the customer's card for customer identification and payments without the customer's card present. The acquisition of a customer card must be done in a payment process. This means first must be configured the customer to request the card acquisition and in the next payment of this customer using a card, the card will be acquired by Adyen and the token generated stored in Openbravo.
To configure this functionality, the customer information has a new field named Request Card Acquisition, and when this field is selected it must be filled in also the field named Recurring Contract, that has three possible values: Recurring, One click, and One click, Recurring. This last field indicates the type of recurring contract to be used:
- One click: The customer opts to store their card details for future use. The customer is present for the subsequent transaction, for cards the security code (CVC/CVV) is required.
- Recurring: Payment details are stored for future use. For cards, the security code (CVC/CVV) is not required for subsequent payments. This is used for a customer not present transactions.
- One click, Recurring: Payment details are stored for future use. This allows the use of the stored payment details regardless of whether the shopper is on your site or not.
![]() | The POS terminal only integrates the process of acquiring the card. It does not integrate the use of the token of the acquired card for future uses. |
The customer fields for card acquisition can be edited in the backend:
Or in the POS terminal:
Once the token of the card acquired has been stored in Openbravo, the field Stored Card will be displayed as checked in the backend and in the POS terminal. With the card stored it is possible to request the card again, just mark the field Request Card Acquisition, and the card will be acquired in the next payment of the customer.
In case you want to delete the stored card token there is a button in the backend, in the window Business Partner, named Remove token, that deletes the token of the stored card of the customer.
Self-checkout
Openbravo supports the Adyen Payment Method for Self-checkout. To enable this, just configure the Adyen payment method and the Self-checkout in the Touchpoint Type window. Then you will be able to do payments with Adyen from de Self-checkout mode.
The transaction interface will look like the one as shown below:
If the In Person Payment Mode is set as Initiate from barcode scanner, once the Adyen payment is selected it will initiate a flow to ask the user to automatically introduce (by scanning) the QR. It will also allow to introduce the code manually displaying a keyboard in the display: