{ "openapi" : "3.1.0", "servers" : [ { "url" : "https://device-api-test.adyen.com/v1", "description" : "Test environment" }, { "url" : "https://device-api-live-au.adyen.com/v1", "description" : "Live environment for Australia" }, { "url" : "https://device-api-live-apse.adyen.com/v1", "description" : "Live environment for East Asia" }, { "url" : "https://device-api-live.adyen.com/v1", "description" : "Live environment for Europe" }, { "url" : "https://device-api-live-us.adyen.com/v1", "description" : "Live environment for United States of America" } ], "info" : { "title" : "Cloud device API", "description" : "With the Cloud device API you can: \n* **Send Terminal API requests to a cloud endpoint**. \n 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.\n* **Check the cloud connection** of a payment terminal or of a device used in a Mobile solution for in-person payments.\n\n## Authentication\nEach request to the Cloud device API must be signed with an API key that has the **Cloud Device API** role. [Generate your API key](https://docs.adyen.com/development-resources/api-credentials#generate-api-key) in your test Customer Area and then set this key to the X-API-Key header value. For example:\n\n```\ncurl\n-H 'Content-Type: application/json' \n-H 'X-API-Key: ADYEN_API_KEY' \n...\n```\n\n## Usage with Terminal API\nWhen using [cloud communications](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) for sending and receiving [Terminal API requests](https://docs.adyen.com/api-explorer/terminal-api/latest/overview), 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. \n\nThe Cloud device API has different endpoints for synchronous or asynchronous cloud communications:\n* If your POS system is designed to keep the connection open to wait for the response, use the endpoints ending in `/sync`.\n\n In the test environment the endpoint for synchronous communication is `https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync` \n\n* If your POS system is designed to close the connection so that it can initiate a new request, use the endpoints ending in `/async`. \n 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.\n\n In the test environment the endpoint for asynchronous communication is `https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/async`\n## Going live\nTo access the live endpoints, you must generate a new API key with the **Cloud Device API** role in your live Customer Area. \n\nYou must use the data center and live endpoint that is geographically closest to your location: \n* In your Customer Area, go to **Developers** > **API URLs** > **Select a data center** and select the closest data center. \n* Switch to the live endpoint that is geographically closest to your location. See the base URLs below.\n### Australia:\nhttps://device-api-live-au.adyen.com\n\n### East Asia:\nhttps://device-api-live-apse.adyen.com\n\n### Europe:\nhttps://device-api-live.adyen.com\n\n### United States:\nhttps://device-api-live-us.adyen.com\n\n## Methods", "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Developer Experience team", "url" : "https://github.com/Adyen/adyen-openapi" }, "version" : "1", "x-timestamp" : "2025-07-08T14:42:14Z" }, "tags" : [ { "name" : "Cloud endpoints and connection" } ], "paths" : { "/merchants/{merchantAccount}/connectedDevices" : { "get" : { "tags" : [ "Cloud endpoints and connection" ], "summary" : "Get a list of connected devices", "description" : "Get a list of payment terminals or SDK installation IDs (in a Mobile solution) belonging to the specified merchant account that have an active cloud connection. The `store` query parameter limits the list of devices to those belonging to a specific store under the specified merchant account. \n\nTo make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n\n\n* **Cloud Device API role**", "operationId" : "get-merchants-merchantAccount-connectedDevices", "parameters" : [ { "name" : "merchantAccount", "in" : "path", "description" : "The unique identifier of the merchant account.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "store", "in" : "query", "description" : "The store ID of the store belonging to the merchant account specified in the path. ", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ConnectedDevicesResponse" }, "examples" : { "connected-devices-for-merchant-200" : { "summary" : "List of connected devices for a merchant", "description" : "The response returned when querying for list of connected devices for the merchant account", "value" : { "uniqueDeviceIds" : [ "S1F2-000158215131748", "S1F2-000158215131749", "S1F2-000158215131750", "M400-401972710", "M400-401972715", "M400-401972720" ] } } } } } }, "401" : { "description" : "Unauthorized", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "connected-devices-for-merchant-401" : { "summary" : "Unauthorized", "description" : "Authentication failed.", "value" : { "type" : "https://docs.adyen.com/errors/unauthorized", "title" : "Unauthorized", "status" : 401, "errorCode" : "00_401" } } } } } }, "403" : { "description" : "Forbidden", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "connected-devices-for-merchant-403" : { "summary" : "Forbidden", "description" : "Most commonly happens when user does not have sufficient roles or doesn't own requested resource.", "value" : { "type" : "https://docs.adyen.com/errors/forbidden", "errorCode" : "00_403", "title" : "Forbidden", "detail" : "User doesn't have access to all token policy resources", "requestId" : "d42c493b5176df89e51516c6060cc34c", "status" : 403 } } } } } } }, "x-group-parameters" : "false", "x-methodName" : "getConnectedDevices", "x-sortIndex" : 4 } }, "/merchants/{merchantAccount}/devices/{deviceId}/async" : { "post" : { "tags" : [ "Cloud endpoints and connection" ], "summary" : "Send a Terminal API request and receive an asynchronous response", "description" : "Sends a Terminal API request and receives the response asynchronously.\n\nThe request body is a JSON object containing a Terminal API request. For the structure, see the various request types under [Terminal API](https://docs.adyen.com/api-explorer/terminal-api/1/overview).\n\nA HTTP status code of **200 OK** is returned when the payment device is online and our backend has sent the request. The actual Terminal API response is returned as an event notification webhook to your event notification endpoint. See [Receiving an asynchronous result](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/#async).\n\nTo make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n\n\n* **Cloud Device API role**", "operationId" : "post-merchants-merchantAccount-devices-deviceId-async", "parameters" : [ { "name" : "merchantAccount", "in" : "path", "description" : "The unique identifier of the merchant account.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "deviceId", "in" : "path", "description" : "The unique identifier of the payment device that you send this request to. Must be the same as the `POIID` in the `MessageHeader` of the Terminal API request. \n\nIn an integration with payment terminals, use the terminal ID in the format _[terminal model]-[serial number]_, for example, **P400‑123456789**. In a Mobile solution, use the installation ID of the SDK.\n ", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "responses" : { "200" : { "description" : "OK - the request has succeeded.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } }, "x-methodName" : "sendAsyncDeviceMessageRequest", "x-sortIndex" : 2 } }, "/merchants/{merchantAccount}/devices/{deviceId}/status" : { "get" : { "tags" : [ "Cloud endpoints and connection" ], "summary" : "Get the connection status of a device", "description" : "Check if the specified payment terminal or SDK installation ID (in an IPP Mobile solution) has an active cloud connection.\n\nTo make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n\n\n* **Cloud Device API role**", "operationId" : "get-merchants-merchantAccount-devices-deviceId-status", "parameters" : [ { "name" : "merchantAccount", "in" : "path", "description" : "The unique identifier of the merchant account.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "deviceId", "in" : "path", "description" : "The unique identifier of the device. \n\nFor a payment terminal, use the terminal ID in the format _[terminal model]-[serial number]_, for example, **P400‑123456789**. \nIn a Mobile solution, use the installation ID of the SDK.\n ", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DeviceStatusResponse" }, "examples" : { "connected-device-status-200" : { "summary" : "Connectivity status of a device", "description" : "The response returned when querying for the connection status of a device", "value" : { "deviceId" : "AMS1-000168242800763", "status" : "ONLINE" } } } } } }, "401" : { "description" : "Unauthorized", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "connected-device-status-401" : { "summary" : "Unauthorized", "description" : "Authentication failed.", "value" : { "type" : "https://docs.adyen.com/errors/unauthorized", "title" : "Unauthorized", "status" : 401, "errorCode" : "00_401" } } } } } }, "403" : { "description" : "Forbidden", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" }, "examples" : { "connected-device-status-403" : { "summary" : "Forbidden", "description" : "Most commonly happens when user does not have sufficient roles or doesn't own requested resource.", "value" : { "type" : "https://docs.adyen.com/errors/forbidden", "errorCode" : "00_403", "title" : "Forbidden", "detail" : "User doesn't have access to all token policy resources", "requestId" : "d42c493b5176df89e51516c6060cc34c", "status" : 403 } } } } } } }, "x-methodName" : "getDeviceStatus", "x-sortIndex" : 3 } }, "/merchants/{merchantAccount}/devices/{deviceId}/sync" : { "post" : { "tags" : [ "Cloud endpoints and connection" ], "summary" : "Send a Terminal API request and receive a synchronous response", "description" : "Sends a Terminal API request and receives the response synchronously.\n\nThe request body is a JSON object containing a Terminal API request. For the structure, see the various request types under [Terminal API](https://docs.adyen.com/api-explorer/terminal-api/1/overview).\n\nThe response returns a Terminal API response. See [Receiving a synchronous result](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/#sync).\n\nTo make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#api-permissions):\n\n\n* **Cloud Device API role**", "operationId" : "post-merchants-merchantAccount-devices-deviceId-sync", "parameters" : [ { "name" : "merchantAccount", "in" : "path", "description" : "The unique identifier of the merchant account.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "deviceId", "in" : "path", "description" : "The unique identifier of the payment device that you send this request to. Must be the same as the `POIID` in the `MessageHeader` of the Terminal API request. \n\nIn an integration with payment terminals, use the terminal ID in the format _[terminal model]-[serial number]_, for example, **P400‑123456789**. In a Mobile solution, use the installation ID of the SDK.\n ", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "type" : "string" } } } }, "responses" : { "200" : { "description" : "OK - the request has succeeded.", "content" : { "application/json" : { "schema" : { "type" : "string" } } } } }, "x-methodName" : "sendSyncDeviceMessageRequest", "x-sortIndex" : 1 } } }, "components" : { "schemas" : { "ConnectedDevicesResponse" : { "type" : "object", "properties" : { "uniqueDeviceIds" : { "type" : "array", "description" : "A list of the unique IDs of the devices that have an active cloud connection. \nThe IDs are payment terminal IDs in the format _[terminal model]-[serial number]_ (for example, P400‑123456789), or SDK installation IDs as used in Mobile solutions. ", "items" : { "type" : "string" } } } }, "DefaultErrorResponseEntity" : { "type" : "object", "properties" : { "detail" : { "type" : "string", "description" : "A human-readable explanation specific to this occurrence of the problem." }, "errorCode" : { "type" : "string", "description" : "Unique business error code." }, "instance" : { "type" : "string", "description" : "A URI that identifies the specific occurrence of the problem if applicable." }, "invalidFields" : { "type" : "array", "description" : "Array of fields with validation errors when applicable.", "items" : { "$ref" : "#/components/schemas/InvalidField" } }, "requestId" : { "type" : "string", "description" : "The unique reference for the request." }, "status" : { "type" : "integer", "description" : "The HTTP status code.", "format" : "int32" }, "title" : { "type" : "string", "description" : "A short, human-readable summary of the problem type." }, "type" : { "type" : "string", "description" : "A URI that identifies the validation error type. It points to human-readable documentation for the problem type." } }, "description" : "Standardized error response following RFC-7807 format", "externalDocs" : { "url" : "https://www.rfc-editor.org/rfc/rfc7807" } }, "InvalidField" : { "required" : [ "message", "name", "value" ], "type" : "object", "properties" : { "name" : { "type" : "string", "description" : "The field that has an invalid value." }, "value" : { "type" : "string", "description" : "The invalid value." }, "message" : { "type" : "string", "description" : "Description of the validation error." } } }, "DeviceStatus" : { "type" : "string", "enum" : [ "ONLINE", "OFFLINE" ] }, "DeviceStatusResponse" : { "type" : "object", "properties" : { "deviceId" : { "type" : "string", "description" : "The unique identification of the device. \nThis can be a payment terminal ID in the format _[terminal model]-[serial number]_ (for example, P400‑123456789), or an SDK installation ID as used in Mobile solutions. " }, "status" : { "description" : "Indicates if the device has an active cloud connection. Possible values: \n* **ONLINE** \n* **OFFLINE** ", "$ref" : "#/components/schemas/DeviceStatus" } } } }, "securitySchemes" : { "ApiKeyAuth" : { "type" : "apiKey", "name" : "X-API-Key", "in" : "header" }, "BasicAuth" : { "type" : "http", "scheme" : "basic" } } }, "jsonSchemaDialect" : "https://spec.openapis.org/oas/3.1/dialect/base" }