Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Building a cloud integration

Learn how to build an integration with cloud communications.

Contact our POS Support Team before you start building a cloud integration.

With an integration that uses cloud communications, your cash register and terminal communicate with each other over the internet:

  1. Your cash register makes an API request to the Adyen payments platform.
  2. The Adyen payments platform routes the request to your terminal, to initiate the payment on the device.
  3. The terminal sends the transaction to the Adyen payments platform for processing.
  4. You receive the result of the transaction synchronously or asynchronously, depending on how you build your integration:
    • Synchronously: When your cash register makes an API request, it keeps the connection open until the transaction result is known.
    • Asynchronously: Your cash register makes an API request, then closes the connection. You receive the transaction result including the receipt data in an event notification or by making a transaction status request.

To build a cloud integration, you need to:

  1. Configure your network.
  2. Optionally install an API library.
  3. Build your payment flow.
  4. Learn how to handle network issues.

Step 1: Configure your network

To enable your cash register to connect to Adyen:

  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.
  3. Contact our POS Support Team to enable web sockets for your account.

For more information, see Network and connectivity.

Step 2 (optional): Install a GitHub 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 GitHub library is not required, but can save you development time, because a library:

  • Uses an API version that is up to date.
  • 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.
  • Sends the request to Adyen using its built-in HTTP client, so you don't have to create your own.

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

Step 3: Build your payment flow

When building your payment flow, decide how you want to receive the result of your Terminal API requests:

  • Synchronously, as an API response. The request returns the response with all the details.
  • Asynchronously, from a webhook. The request returns 200 OK. The response with all the details is sent to a webhook server that you set up for event notifications. For payments you can also get the payment response by making a transaction status request.

Receiving a synchronous result

If you want to receive the payment result synchronously, your cash register needs to make HTTPS requests to the endpoint:

This request must use an extended time-out of more than 150 seconds. During this time the connection is kept alive and a synchronous response will follow.

The synchronous Terminal API payment response provides:

  • 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.

Receiving an asynchronous result

If you do not want to use an extended time-out of 150 seconds, you can instead receive the response asynchronously. In this case, your cash register needs to make an HTTPS request to the endpoint:

This will return an HTTP status code of 200 OK, confirming that we received your request.

To asynchronously receive the actual Terminal API response:

  • Set up an HTTPS webhook server for event notifications. We then send the Terminal API responses to your event notifications endpoint. However, you need to filter out the Terminal API responses from the event notifications. For a payment, the response contains:

    • 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 a payment, you can also make a transaction status request to the synchronous endpoint. The transaction status response includes the full payment response.

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 4: 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 payment response from Adyen.

Payment requests time out after 150 seconds. If you do not receive a payment response (or a response indicating a time-out) after 150 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 150 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.


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

Next steps