Building a cloud integration

With an integration that uses cloud communications, your POS app and the payment terminal communicate with each other over the internet. You send Terminal API requests to the Cloud device API endpoints.

1. Your POS app makes an API request to the Adyen payments platform.
2. The Adyen payments platform routes the request to your payment terminal, to start 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 POS app makes an API request, it keeps the connection open until the transaction result is known.
   • Asynchronously: your POS app 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. Get your API key
4. Build your payment flow.
5. Learn how to handle network issues.
6. Use the live endpoints when you go live.

1. Configure your network

To enable your POS app to connect to Adyen:

1. Add Adyen's domains to your firewall's allowlist.
   Configure your firewall to allow outgoing HTTPS traffic from the IP addresses of your POS apps and terminals to:

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

   Allowlisting 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 Support Team to enable web sockets for your account.

2. (Optional) Install a GitHub API library

On our GitHub, we provide 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 includes all Terminal API models so you can use these to create requests. Most libraries also send requests to Adyen using a built-in HTTP client and construct the correct TEST and LIVE endpoints.

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

• .NET - adyen-dotnet-api-library
• Java - adyen-java-api-library
• Go - adyen-go-api-library
• Node - adyen-node-api-library
• PHP - adyen-php-api-library
• Ruby - adyen-ruby-api-library
• iOS/macOS - adyen-terminal-api-ios. This package is intended for following scenarios:
  • when integrating the POS Mobile SDK
  • when integrating server-side with Adyen payment terminals using cloud communications

3. Get your API key

You need to include an Adyen API key that has the Cloud device API user role in the request header for:

• Terminal API requests when using cloud communications.
• Requests to other Adyen APIs. For example, for manual capture, authorization adjustment, and automating terminal management.

To get an API key for your test environment:

1. Log in to your Customer Area.

2. Go to Developers > API credentials and select the Payments tab.

3. If you do not have an Adyen API key yet, or if you want to create a new API key without affecting an existing Adyen API key that you already have, first create a "credential":

   1. Select Create new credential.
   2. In the dialog, on the Payments tab, select Web service user and enter a description for the API key.
   3. Save the generated Username, for example ws_123456@Company.[YourCompanyAccount]. You will need this later if you need to manage API keys.
   4. Select Create credential.

   The Configure API credentials page appears.

4. Alternatively, if you want to replace your existing Adyen API key with a new one, select the API credential username for your integration, for example ws_123456@Company.[YourCompanyAccount].

   The Configure API credentials page appears.

5. On the Configure API credentials page, under Server settings > Authentication select the API key tab.

6. Select Generate API key.

7. Select the copy icon and save your API key securely in your system.

   You cannot copy the API key again after you leave the page.

8. Under Permissions > Roles > POS, select Cloud Device API.

9. Select Save changes.

When you switch to your live environment, follow the same steps in your live Customer Area.

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

To receive the payment result synchronously:

• Your POS app needs to make HTTPS requests to the synchronous endpoint:
  https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync

  The path parameters merchantAccount and deviceId identify the payment terminal or mobile device that you want to send the request to. The 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.

• Optionally show display notifications in your POS app.
  During a transaction or tender, the payment terminal generates display notifications. You can show these in your POS app to keep your staff up-to-date on the progress of the tender. For example, whether the customer has selected Dynamic Currency Conversion, or finished entering their PIN.

• As a fallback in case the synchronous response is not received due to network or WebSocket connection issues, consider also setting up platform-generated standard webhooks.

The synchronous Terminal API payment response provides:

• The result of the payment.
• Adyen's PSP reference that uniquely identifies the transaction.
• Your unique transaction reference.
• Data that you can use to generate a receipt. You can generate a printed receipt, show it on the terminal display, or email it to the customer.

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 POS app needs to make an HTTPS request to the asynchronous endpoint:
  https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/async

  The path parameters merchantAccount and deviceId identify the payment terminal or mobile device that you want to send the request to. The request returns an HTTP status code of 200 OK when the terminal receives the request. The time between making the request and receiving the HTTP status code depends on the quality of the terminal's internet connection.

• To asynchronously receive the actual Terminal API response, you need to set up event notifications. The terminal will send the Terminal API response over the WebSocket connection to your event notifications endpoint. However, you need to filter out the Terminal API responses from the event notifications.

• You need to accept the event notification with the Terminal API response when you receive it, by responding with a successful HTTP response status code.

• We retry sending asynchronous Terminal API responses up to three times, but only if the HTTP response code you send is 5xx. Any other response code is treated as a success.

• As a fallback in case event notifications are not sent due to an issue with the WebSocket connection, consider also setting up platform-generated standard webhooks.

• To synchronously receive data to generate a receipt, your POS app needs to make a transaction status request to the synchronous endpoint https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync.
  The transaction status response contains the full payment response, including receipt data.

• Optionally show display notifications in your POS app.
  During a transaction or tender, the payment terminal generates display notifications. You can show these in your POS app to keep your staff up-to-date on the progress of the tender. For example, whether the customer has selected Dynamic Currency Conversion, or finished entering their PIN.

Both the event notification with the Terminal API payment response and the transaction status response provide:

• The result of the payment.
• Adyen's PSP reference that uniquely identifies the transaction.
• Your unique transaction reference.
• Data that you can use to generate a receipt. You can generate a printed receipt, show it on the terminal display, or email it to the customer.

Guarantee payment response delivery

By default, we stop trying to send a payment response to your event notifications endpoint after three attempts. To make sure you do not miss a Terminal API response, you can enable the guarantee payment response delivery feature. It keeps sending the Terminal API response until your server acknowledges the webhook with a successful HTTP response status code, for example 200.

To enable the feature, contact the Support Team.

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 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 in your POS app reduces the risk that your store staff will unnecessarily attempt to cancel or refund the transaction, or make a duplicate transaction.

6. Going live

When you are ready to go live, you need to switch to a live transaction endpoint, including the merchantAccount and deviceId path parameters to identify the payment device that you want to send the request to. The deviceId must be the same as the POIID in the MessageHeader of the Terminal API request.

For the best performance, use an endpoint that is geographically closest to the location of your store.

If you previously built an integration and are now repeating that in a new region, make sure to change the live endpoint to the one for the new region.

While the regional endpoints impact the communication between your POS app and the payment terminal, the communication between your payment terminal and our back-end also depends on the data center used.

To ensure that the communication between your payment terminal and our back-end is optimal, make sure to select the data center closest to your geographical location in your live Customer Area under Developers > API URLs > Select a data center, for example AU for Australia.

Find regional data centers

Find the country of your terminal's location in the table below to identify which regional data center endpoint to use.

Migrate to latest endpoints

If you currently use terminal-api endpoints, we strongly recommend migrating to the Cloud device API endpoints, for the following reasons:

• When using Cloud device API, the API logs in the Customer Area include the Terminal API requests and responses.
• Cloud device API endpoints offer technical advantages such as versioning and better routing.
• Future enhancements and features will be based on Cloud device API.

There will be no future development on the old endpoints, but we continue to support them.

The device is identified by the POIID in the MessageHeader of the Terminal API request. You must authenticate your request with an API key.

Select the relevant tab below to see the old terminal-api test and live endpoints:

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