Cloud device API
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…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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
Endpoints 4
Cloud endpoints and connection
- GETGet a list of connected devices
/merchants/:merchantAccount/connectedDevices?store=stringGet a list of payment terminals or SDK installation IDs (in a Mobile solution) belonging to the specified merchant account that have an active cloud… - POSTSend a Terminal API request and receive an asynchronous response
/merchants/:merchantAccount/devices/:deviceId/asyncSends a Terminal API request and receives the response asynchronously. The request body is a JSON object containing a Terminal API request. For the structure,… - GETGet the connection status of a device
/merchants/:merchantAccount/devices/:deviceId/statusCheck if the specified payment terminal or SDK installation ID (in an IPP Mobile solution) has an active cloud connection. To make this request, your API… - POSTSend a Terminal API request and receive a synchronous response
/merchants/:merchantAccount/devices/:deviceId/syncSends a Terminal API request and receives the response synchronously. The request body is a JSON object containing a Terminal API request. For the structure,…
API details
- Base URL
https://device-api-test.adyen.com/v1https://device-api-live-au.adyen.com/v1https://device-api-live-apse.adyen.com/v1https://device-api-live.adyen.com/v1https://device-api-live-us.adyen.com/v1- Authentication
- An API key in the X-API-Key header
HTTP Basic authentication (username and password) - Operations
- 4 operations on 4 pathsGET 2POST 2
- Main resources
- Cloud endpoints and connection 4
- Response formats
application/json- Description format
- OpenAPI 3.1.0, API version
1 - Links
- OpenAPI document · Terms of service · Support
- Listed from
- Adyen's published OpenAPI description (Adyen/adyen-openapi) (MIT)
How to test the Cloud device API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Cloud device API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-API-Key header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get a list of connected devices” (GET /merchants/:merchantAccount/connectedDevices?store=string), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Cloud device API?
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… It is listed under Payments and has 4 endpoints.
Who publishes the Cloud device API?
It is listed from Adyen's public API description (an OpenAPI document), not published by Adyen on Swastik Codes. Anyone who controls adyen.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Cloud device API?
Its description lists 5 base URLs: https://device-api-test.adyen.com/v1, https://device-api-live-au.adyen.com/v1, https://device-api-live-apse.adyen.com/v1, https://device-api-live.adyen.com/v1, https://device-api-live-us.adyen.com/v1. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Cloud device API?
It accepts 2 methods: an API key in the X-API-Key header; HTTP Basic authentication (username and password).
How many endpoints does the Cloud device API have?
4 operations on 4 paths (2 GET, 2 POST). The largest groups are Cloud endpoints and connection.
Is forking the Cloud device API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.