Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Building a local integration

Learn how to build an integration with local communications.

With an integration that uses local communications, your cash register and terminal communicate with each other over your local network:

  1. Your cash register makes an API request to the terminal, to initiate the payment on the device.
  2. The terminal routes the request to the Adyen payments platform for processing.
  3. Optional: You receive display notifications on your cash register, to inform store staff on the progress of the transaction and the result.
  4. You receive the result of the transaction synchronously.

To build a local integration, you need to:

  1. Configure your network.
  2. Optionally install an API library.
  3. Protect local communications. This is optional for test transactions, but required for live transactions.
  4. Build your payment flow.
  5. Learn how to handle network issues.

Step 1: Configure your network

To enable your cash register system to connect directly to the terminal:

  1. Add Adyen's domains to your firewall's whitelist.
    Configure your firewall to allow outgoing HTTPS traffic from the IP addresses of your cash registers and terminals to:

    • *.adyen.com
    • *.adyenpayments.com

    Whitelisting should be based on the DNS name of these URLs. Your firewall should dynamically check for IP address updates, at least every 60 seconds.

    Do not hard-code Adyen's IP addresses, because these can change over time. We do not share a list of our IP addresses publicly.

  2. Open the ports:
    • tcp/443 to the internet.
    • tcp/8443 on your LAN.

For more information, see Network and connectivity.

Step 2 (optional): Install an API library

On our GitHub, we provide server-side API libraries in several languages. Installing a GitHub library is not required, but can save you development time, because a library:

  • Uses an API version that is up to date.
  • Includes all Terminal API models so you can use these to create requests, and don't have to serialize requests to JSON.
  • Helps to protect local communications.
  • Sends the request to Adyen using its built-in HTTP client, so you don't have to create your own.

The following Adyen GitHub libraries are available for a local Terminal API integration:

These GitHub libraries work with Terminal API and are completely separate from the classic libraries, which are being deprecated.

Select a tab below for the Adyen GitHub library you want to use.

Set up the .NET library

  1. Make sure your project supports the following requirements:

    • .NET Standard 2.0.
    • .NET Core 2.1 or higher, or .NET Framework 4.6.1 or higher.

  2. Install the library in one of the following ways:

Set up the Java library

  1. Make sure your project supports the following requirements:

    • Java 8 or higher.

  2. Install the library in one of the following ways:

    • Use Maven, adding this dependency to your project's POM.

      <dependency>
          <groupId>com.adyen</groupId>
          <artifactId>adyen-java-api-library</artifactId>
          <version>LATEST_VERSION</version>
      </dependency>
    • Or download the release on GitHub.

Set up the Node library

  1. Make sure your project supports the following requirements:

    • Node 10 or higher.

  2. Install the library in one of the following ways:

Step 3: Protect local communications

While you are building a test integration, we don't enforce this step. This allows you to develop the functional and security aspects in parallel. However, you will not be able to process live transactions until you have secured the requests between your cash register and terminal.

If your integration uses local communications, you need to protect your integration against man-in-the-middle attacks, eavesdropping, and tampering. The steps you need to take are:

  1. Install Adyen's root certificate.
  2. Set up a shared key.
  3. Add code to validate the terminal certificate against the root certificate and encrypt communications using the shared key.

Install Adyen's root certificate

The root certificate contains information about Adyen's public key, which is used to sign other certificates such as the certificate on the terminal. To verify the certificate on the terminal against the public key, you have to install Adyen's root certificate in a trust store that is available to your cash register system.

The instructions differ depending on the operating system. Select one of the tabs below.

  1. Download Adyen's public root certificates to your cash register:

    If your system requires another format, such as .crt or .cer, you can use OpenSSL commands to convert the certificates. For example:

    openssl x509 -outform der -in adyen-terminalfleet-test.pem -out adyen-terminalfleet-test.crt
  2. Verify that the SHA-256 fingerprint (also called thumbprint) of the root certificates matches the following:

    • TEST root certificate: 3A 33 C3 34 C3 0F 69 46 E9 75 4B 6B B1 67 2B 54 6F BA A9 66 FB 6A 4B 58 AA 4E 3A BE 80 A7 EC BE
    • LIVE root certificate: 06 D4 86 41 95 4B 95 7D 7A F5 F5 E4 5A 58 D8 61 DB 0D E3 CC ED BB 98 36 60 BB 01 6C E6 14 2D A1

    There are various ways to get the SHA-256 fingerprint:

    • You can use the following OpenSSL command:

      openssl x509 -in adyen-terminalfleet-test.pem -noout -sha256 -fingerprint
    • In a macOS environment, you can select the root certificate in Finder, press the Spacebar, and in the window that opens find the Fingerprints.

  3. Install the Adyen root certificates in your cash register's trust store, following your vendor's instructions.

    You can add root certificates to the user or system trust store. At the user level, it is easier to import a certificate.

In a Windows environment, install the root certificate as follows.

  1. Download Adyen's public root certificate to your cash register:

  2. In the Microsoft Management Console (MMC), add the Certificates snap-in:

    1. In the Run window, enter mmc.
    2. Select File > Add/Remove Snap-in and add the Certificates snap-in to your user or computer trust store (referred to as account).

  3. Go to Certificates > Trusted Root Certification Authorities > Certificates.

  4. Import the Adyen root certificate into the Trusted Root Certification Authorities trust store:
    Select Action > All tasks > Import, select the Adyen root certificate, and complete the wizard steps.

  5. Double-click the imported root certificate and on the Details tab verify that the Thumbprint matches the following SHA-1 fingerprint:

    • TEST root certificate: D5 02 7F A8 B3 93 96 DB 2A 4F B1 86 EF 61 E4 A4 40 A7 30 51
    • LIVE root certificate: 62 61 0D 88 27 8E 95 B7 F8 57 9A 9B 5E 07 85 D7 72 87 66 42

  6. To verify that the root certificate is installed, in the Run window open certmgr.msc for a user trust store or certlm.msc for a system trust store and check that the Adyen root certificate is listed under Trusted Root Certification Authorities -> Certificates.

Apart from using the MMC Certificates snap-in as described above, you could also use PowerShell to import the root certificates.

Set up a shared key

To prevent others from being able to read messages sent between your cash register and the payment terminal, you need to encrypt the communications. For that, you first need to create a key passphrase and share it with Adyen. Both your code (or the Adyen GitHub library you're using) and the terminal will apply a key derivation function to the passphrase, and use the resulting key material to encrypt communications.

To create a shared key:

  1. Log in to your Customer Area.
  2. Go to Point-of-sale > Terminals.
  3. Click the row of the terminal you want to configure. The settings page for that terminal appears.
  4. Select View decrypted properties.
  5. Select Integrations.
  6. Under Encryption key complete the fields:

    • Key identifier: A description to recognize the key by.
    • Key passphrase: A string of random characters.
    • Key version: The version number of the key. For example, 1.

    If this section is not visible or if you can't edit the fields, ask our POS Support Team to set the required permission for your user.

  7. Select Save.
  8. Securely store the key identifier, passphrase, and version in your system.

Add code to protect local communications

Your integration must:

  • Validate the terminal certificate: This confirms that your cash register is communicating directly with an Adyen-supplied payment terminal, and not an impostor.
  • Encrypt communications: This prevents intruders from reading the messages transmitted between your cash register and terminal.

There are two ways to get this done: Use one of our GitHub libraries, or write your own code. For instructions, select one of the options below.

Step 4: Build your payment flow

Adyen-supplied payment terminals listen for Terminal API POST requests to /nexo on port 8443. For example, if your terminal has the IP address 198.51.100.1 you make API requests to: https://198.51.100.1:8443/nexo.

When you make a payment, the result is provided through a synchronous API response. To receive the synchronous response, your cash register needs to make HTTPS requests to the terminal using a time-out of more than 120 seconds. During this time the connection is kept alive and a synchronous response will follow.

When building your payment flow, also consider:

  • How you want to handle the synchronous response, including how you provide a receipt to the shopper.
  • Whether you want to show messages on your cash register, to keep store staff up to date with the progress of the transaction.
  • Optionally installing a server-side API library.

Handling the synchronous response

The synchronous Terminal API response includes:

  • The result of the payment.
  • Adyen's unique transaction reference.
  • Your unique transaction reference.
  • Data that you can use to generate a receipt. You can either generate a printed receipt, display it on-screen, or email it to the shopper.

For more information on the Terminal API response, see our Terminal API fundamentals.

Showing display notifications on your cash register

During a transaction or tender, the payment terminal generates display notifications. You can present these on your cash register to keep your store staff up-to-date on the progress of the tender. For example, whether the shopper has selected Dynamic Currency Conversion, or finished entering their PIN.

To set this up, see Display notifications.

Step 5: Handle network issues

To make your integration more resilient in case of connection issues, your integration should automatically make a transaction status request when it does not receive a synchronous payment response from Adyen.

Payment requests time out after 120 seconds. If you do not receive a payment response (or you receive a response indicating a time-out) after 150 seconds, your integration should automatically make a transaction status request.

Showing the result of the transaction status request on your cash register reduces the risk that your store staff will unnecessarily try to cancel or refund the transaction, or make a duplicate transaction.

You can optionally request the status of a transaction before 120 seconds. For example, you may also want to let store staff manually request the status of a payment at any time from the cash register.

See also