Skip to main content

Cloud device API

Click to copy

With the Cloud device API you can:

  • Send Terminal API requests to a cloud endpoint. You can use this communication method when it is not an option to send Terminal API requests over your local network directly to a payment terminal.
  • Check the cloud connection of a payment terminal or of a device used in a Mobile solution for in-person payments.

Authentication

Each request to the Cloud device API must be signed with an API key that has the Cloud Device API role. Generate your API key in your test Customer Area and then set this key to the X-API-Key header value. For example:

curl
-H 'Content-Type: application/json' 
-H 'X-API-Key: ADYEN_API_KEY' 
...

Usage with Terminal API

When using cloud communications for sending and receiving Terminal API requests, your POS system uses the internet to access the cloud and send your Terminal API request to Adyen. Adyen then forwards the request to the payment device.

The Cloud device API has different endpoints for synchronous or asynchronous cloud communications:

  • If your POS system is designed to keep the connection open to wait for the response, use the endpoints ending in /sync.

    In the test environment the endpoint for synchronous communication is https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync

  • If your POS system is designed to close the connection so that it can initiate a new request, use the endpoints ending in /async. You will then receive the Terminal API response asynchronously in an event notification, which is sent as a webhook to an endpoint set up by you.

    In the test environment the endpoint for asynchronous communication is https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/async

Going live

To access the live endpoints, you must generate a new API key with the Cloud Device API role in your live Customer Area.

You must use the data center and live endpoint that is geographically closest to your location:

  • In your Customer Area, go to Developers > API URLs > Select a data center and select the closest data center.
  • Switch to the live endpoint that is geographically closest to your location. See the base URLs below.

Australia:

https://device-api-live-au.adyen.com

East Asia:

https://device-api-live-apse.adyen.com

Europe:

https://device-api-live.adyen.com

United States:

https://device-api-live-us.adyen.com

Methods

Get a list of connected devices
Send a Terminal API request and receive an asynchronous response
Get the connection status of a device
Send a Terminal API request and receive a synchronous response