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.

To initiate a payment:

  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.

Before you can begin making transactions with a local integration, you will need to:

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

Step 1: Configure your network

So that your cash register can connect directly to the terminal, you will need to:

  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 on configuring your network, and our recommendations, see our Network configuration documentation.

Step 2 (optional): Install an API library

On our GitHub, we provide server-side API libraries in several languages. Because the libraries are connected to managed package systems (Gradle, Maven, NPM, NuGet) they are easy to include in your project.
Installing a library is not required, but can save you development time, because a library:

  • Uses the latest API version.
  • Constructs the correct TEST and LIVE endpoints.
  • Includes all Terminal API models so you can use these to create requests, and don't have to serialize requests to JSON.
  • Takes care of securing your requests.
  • Sends the request to Adyen using its built-in HTTP client, so you don't have to create your own.

To use a library, follow the instructions for one of these libraries:

Step 3: Secure your requests

To secure and authenticate requests between your cash register and terminal, your integration must:

  • Encrypt transaction requests: This prevents intruders from reading messages transmitted between your cash register and terminal.
  • Validate terminal certificates: This confirms that your cash register is communicating directly with an Adyen terminal, and not an impostor.

There are two way to get this done:

While you're 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.

Step 4: Build your payment flow

Adyen terminals listen for POST requests to /nexo on port 8443. For example, if your terminal has the IP address 192.168.1.123 you would make API requests to: https://192.168.1.123: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 an extended 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, you should also consider:

  • How you want to handle the synchronous response, including how you provide a receipt to the shopper.
  • Whether you want to display 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 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 synchronous API response, see our Terminal API fundamentals.

While a transaction is being processed we can send webhooks to your server. You can use these to display notifications on your cash register.

Displaying notifications on your cash register

While a transaction is being processed you may wish to display notifications on your cash register. These keep your store staff informed on the progress of the transaction, for example whether the shopper has selected Dynamic Currency Conversion, or finished entering their PIN.

For more information on setting up display notifications, see our Display notifications documentation.

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 timeout after 120 seconds. If you do not receive a payment response (or you receive a response indicating a timeout) after 120 seconds, your integration should automatically make a transaction status request.

Displaying the result of the transaction status request on your cash register reduces the risk that your store staff will unnecessarily attempt 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 to manually request the status of a payment at any time from the cash register.

Next steps

Now that you're familiar with how to build your integration, you can learn about the basics of our Terminal API.