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.

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

To initiate a payment:

  1. Your cash register makes an API request to Adyen payments platform.
  2. 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. You can build an integration that either receives this:
    • 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. Once the transaction has been processed, the transaction result is received in a notification.

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

  1. Configure your network.
  2. Build your payment flow.
  3. Learn how to handle network issues.

Step 1: Configure your network

So that your cash register can connect to Adyen, 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, as 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: Build your payment flow

When you build your integration, you can choose whether you want to receive the result of payments:

Receiving a synchronous result

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

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

In addition to the result of the payment, the synchronous API response provides:

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

When building your payment flow, you should also consider whether you want to display notifications on your cash register. This is optional if you're receiving a response synchronously, but keep your store staff up to date with the progress of the transaction.

To set up notifications, you will need an HTTPS webhook server. For more information on setting up display notifications, see our Display notifications documentation.

Receiving an asynchronous result

If you do not want to use an extended time-out of 120 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 a 200 HTTP OK response, confirming that we received your request.

To receive an asynchronous response you will need to set up an HTTPS webhook server so that you can receive display notifications on your cash register. These keep your store staff informed on the progress of the transaction, including the result.

In addition to the result of the payment, asynchronous display notifications provide:

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

Step 3: Handle network issues

To make your integation 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 timeout after 120 seconds. If you do not receive a payment response (or 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.


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

Next steps