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 iniate the payment on the device.
  2. The terminal routes the request to the Adyen payments platform for processing.
  3. Optional: Receive display notifications on your cash register, to inform store staff on the progress of the transaction and 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. Secure your requests. This is optional for test payments, but required to process live transactions.
  3. Build your payment flow.
  4. 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, 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: Secure 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.

For more information, refer to our documentation on securing local communications.

This step is optional while you're building a test integration. However, you will not be able to process live transactions until you have secured the requests between your cash register and terminal.

Step 3: Build your payment flow

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.

Handling the synchronous respose

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.

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

Step 4: 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 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.


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

Next steps