--- title: "Make a diagnosis request" description: "Check the state of a payment terminal or mobile device, and any offline transactions." url: "https://docs.adyen.com/point-of-sale/diagnostics/request-diagnosis" source_url: "https://docs.adyen.com/point-of-sale/diagnostics/request-diagnosis.md" canonical: "https://docs.adyen.com/point-of-sale/diagnostics/request-diagnosis" last_modified: "2026-05-25T12:55:00+02:00" language: "en" --- # Make a diagnosis request Check the state of a payment terminal or mobile device, and any offline transactions. [View source](/point-of-sale/diagnostics/request-diagnosis.md) A Terminal API diagnosis request lets you verify the condition of a payment terminal and its components such as the communication module, the battery, or the built-in printer. If you have a Mobile SDK solution using mobile devices instead of payment terminals, a diagnosis request lets you check the security of a device. In both cases a diagnosis request also gives information about any offline payments that have not been sent to Adyen yet. Depending on your integration, see: * [Diagnose a payment terminal](#diagnosis-request) * [Diagnose a Mobile SDK solution](#diagnosis-request-mobile) ## Requirements Before you begin, take into account the following requirements and limitations. | Requirement | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Supported with:- A Terminal API integration with payment terminals. - Android and iOS Mobile SDK solutions for Tap to Pay or card reader. | | **Limitations** | Not supported with a Mobile Payments app solution. | ## Diagnose a payment terminal The diagnosis request supports you in business critical processes, because the response includes: * `batteryLevel`: This parameter is included for battery-powered terminals, and shows the battery charge level. You can use this information to let your staff know they need to recharge the terminal soon. For guidelines regarding terminal battery usage, see [Manage battery power](/point-of-sale/managing-terminals/battery-management). * `unconfirmedBatchCount`: The number of payments that the terminal has not been able to send to the Adyen host for completion (capture and settlement). An `unconfirmedBatchCount` greater than **0** (zero) indicates there is possibly a problem with your network. Diagnosing a payment terminal is best done in two steps: * First [check the condition of the terminal](#verify-terminal). * Then, if the `unconfirmedBatchCount`is greater than **0** (zero), [check if the Adyen host system is reachable](#test-host-system-reachable). ### 1. Verify the condition of a terminal To check the condition of a payment terminal: 1. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) diagnosis request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Diagnosis**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Diagnosis** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used. | | `SaleID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [DiagnosisRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/diagnosis) body, including: | Parameter | Required | Description | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HostDiagnosisFlag` | | Initially set the value to **false**. You only need to set the value to **true** for [further diagnosis](#test-host-system-reachable) when the initial response includes an `unconfirmedBatchCount` greater than zero. This is explained in [2. Verify that the Adyen host system is reachable](#test-host-system-reachable). | #### JSON ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Diagnosis", "MessageType":"Request", "ServiceID":"040", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" }, "DiagnosisRequest":{ "HostDiagnosisFlag":false } } } ``` #### Java ```java String serviceID = "YOUR_UNIQUE_ATTEMPT_ID"; String saleID = "YOUR_CASH_REGISTER_ID"; String POIID = "YOUR_TERMINAL_ID"; SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest(); MessageHeader messageHeader = new MessageHeader(); messageHeader.setProtocolVersion("3.0"); messageHeader.setMessageClass( MessageClassType.SERVICE ); messageHeader.setMessageCategory( MessageCategoryType.DIAGNOSIS ); messageHeader.setMessageType( MessageType.REQUEST ); messageHeader.setServiceID(serviceID); messageHeader.setSaleID(saleID); messageHeader.setPOIID(POIID); saleToPOIRequest.setMessageHeader(messageHeader); DiagnosisRequest diagnosisRequest = new DiagnosisRequest(); diagnosisRequest.setHostDiagnosisFlag( Boolean.FALSE ); saleToPOIRequest.setDiagnosisRequest(diagnosisRequest); terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest); ``` 2. Use the following parts of the response to check the condition of the terminal: * The `POIStatus` object: | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GlobalStatus` | The condition of the payment terminal. | | `CommunicationOKFlag` | A Boolean that indicates whether the general condition of the communication module is OK. | | `PrinterStatus` | This parameter is included when the payment terminal has a built-in printer, and indicates the condition of the printer module. **NoPaper** indicates the receipt paper roll is missing or the paper is not sticking out. | * The `Response.AdditionalResponse` string of key-value pairs separated by **&**: | Parameter | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batteryLevel` | This parameter is included for battery-powered terminals, and indicates the battery charge level as a percentage of fully charged. | | `unconfirmedBatchCount` | The number of payments that the terminal has not yet sent for completion to our platform, and thus cannot be settled. | | `firmwareVersion` | The software version that the terminal is on. | | `networkProfile` | A Base64 string that you can decode to see the IP address of the terminal and other network data. | | `merchantAccount` | The merchant account that the diagnosed payment terminal is assigned to. | | `terminalId` | The POIID of the diagnosed payment terminal, in the format *\[device model]-\[serial number]*. | | `storeId` | The store that the diagnosed payment terminal is assigned to. | | `tamperStatus` | This parameter only applies to UX300 and UX410 terminals. The value **ARS\_TRIGGERED** indicates that anti-removal switches (ARS) have been triggered. This means you must stop using the terminal immediately. | * If the terminal uses [Point-to-Point Encryption (P2PE)](/development-resources/e2ee-p2pe-comparison#what-is-p2pe) instead of Adyen End-to-End Encryption (E2EE), `Response.AdditionalResponse` also includes the following parameters: The diagnosis response includes P2PE protocol, SRED, vault, and app manager versions as provided by the hardware manufacturer. You need to specify this data in your annual PCI assessment. | Parameter | Description | | --------------------------- | ---------------------------------------------------------------------------- | | `p2peFirmwareVersionNumber` | The version number of the P2PE software managed and used by Adyen. | | `p2peOpenProtocolVersion` | The version of the open protocol application. | | `p2peSREDVersion` | The version of the Secure Reading and Exchange of Data (SRED) functionality. | | `p2peVaultVersion` | The version of the vault. | | `p2peAppManagerVersion` | The version of the app manager. | **Diagnosis response for a battery-powered terminal** ```json { "SaleToPOIResponse": { "DiagnosisResponse": { "POIStatus": { "CommunicationOKFlag": true, "PrinterStatus": "OK", "GlobalStatus": "OK" }, "Response": { "Result": "Success", "AdditionalResponse": "batteryLevel=100%25&firmwareVersion=adyen_v1_69p4&networkProfile=WyB7ICJBZGRyZXNzIjogIjE5Mi4xNjguMi4yIiwgIklmYWNlIjogIndsYW4wIiB9IF0%3d&merchantAccount=ADYEN_MERCHANT_ACCOUNT&unconfirmedBatchCount=0&terminalId=V400m-346403161&storeId=YOUR_STORE" } }, "MessageHeader": { "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Diagnosis", "MessageType":"Response", "ServiceID":"040", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" } } } ``` **Diagnosis response for a P2PE terminal that is not battery-powered** ```json { "SaleToPOIResponse": { "DiagnosisResponse": { "POIStatus": { "CommunicationOKFlag": true, "GlobalStatus": "OK" }, "Response": { "AdditionalResponse": "p2peOpenProtocolVersion=2.0.0&firmwareVersion=adyen_v1_69p4&networkProfile=WyB7ICJBZGRyZXNzIjogIjE3Mi4xNy4xMjUuMzAiLCAiSWZhY2UiOiAiZXRoMCIgfSBd&p2peSREDVersion=11.0.2.110&merchantAccount=ADYEN_MERCHANT_ACCOUNT&p2peVaultVersion=10.0.4.13405&unconfirmedBatchCount=0&p2peAppManagerVersion=14.0.13.13414&p2peFirmwareVersion=1.1.1&terminalId=P400Plus-275426191&storeId=YOUR_STORE", "Result": "Success" } }, "MessageHeader": { "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Diagnosis", "MessageType":"Response", "ServiceID":"040", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" } } } ``` 3. In the `AdditionalResponse` check the value of the `unconfirmedBatchCount`. This should be **0** (zero). If not, there may be a problem with your network.\ If the `unconfirmedBatchCount` is **greater than 0**, proceed to step 2: [Verify that the Adyen host system is reachable](#test-host-system-reachable). ### 2. Verify that the Adyen host system is reachable If the diagnosis response shows an `unconfirmedBatchCount` greater than 0 (zero), there may be a problem with your network. To check if this is the case: 1. Make another diagnosis request as described under [1. Verify the condition of a terminal](#verify-terminal), but this time set\ `DiagnosisRequest.HostDiagnosisFlag` to **true**. A communication test will try to reach the Adyen host system. #### JSON ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Diagnosis", "MessageType":"Request", "ServiceID":"282", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" }, "DiagnosisRequest":{ "HostDiagnosisFlag":true } } } ``` #### Java ```java String serviceID = "YOUR_UNIQUE_ATTEMPT_ID"; String saleID = "YOUR_CASH_REGISTER_ID"; String POIID = "YOUR_TERMINAL_ID"; SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest(); MessageHeader messageHeader = new MessageHeader(); messageHeader.setProtocolVersion("3.0"); messageHeader.setMessageClass( MessageClassType.SERVICE ); messageHeader.setMessageCategory( MessageCategoryType.DIAGNOSIS ); messageHeader.setMessageType( MessageType.REQUEST ); messageHeader.setServiceID(serviceID); messageHeader.setSaleID(saleID); messageHeader.setPOIID(POIID); saleToPOIRequest.setMessageHeader(messageHeader); DiagnosisRequest diagnosisRequest = new DiagnosisRequest(); diagnosisRequest.setHostDiagnosisFlag( Boolean.TRUE ); saleToPOIRequest.setDiagnosisRequest(diagnosisRequest); terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest); ``` 2. In the response, check the `HostStatus` array: | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `IsReachableFlag` | A Boolean that indicates if the Adyen host system was reached. If the Adyen host system could not be reached, you may need to adjust your firewall settings or other network aspects. | **Diagnosis response when Adyen host is reached** ```json { "SaleToPOIResponse": { "MessageHeader": { "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Diagnosis", "MessageType":"Response", "ServiceID":"040", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" }, "DiagnosisResponse": { "POIStatus": { "CommunicationOKFlag": true, "PrinterStatus": "OK", "GlobalStatus": "OK" }, "Response": { "Result": "Success", "AdditionalResponse": "batteryLevel=100%25&firmwareVersion=adyen_v1_49p5&networkProfile=WyB7ICJBZGRyZXNzIjogIjE5Mi4xNjguMi4yIiwgIklmYWNlIjogIndsYW4wIiB9IF0%3d&merchantAccount=ADYEN_MERCHANT_ACCOUNT&unconfirmedBatchCount=0&terminalId=V400m-346403161&storeId=YOUR_STORE" }, "HostStatus": [ { "IsReachableFlag": true, "AcquirerID": "0" } ] } } } ``` ## Diagnose a Mobile SDK solution In a Mobile SDK solution, the Terminal API diagnosis request enables you to do the following: * Check if there are **stored offline payments** that have not been forwarded to Adyen yet. If the request has `hostDiagnosisFlag` set to **true**, the SDK will try to go online and forward these transactions. Diagnosis of offline payments is only included if your Mobile SDK solution [supports Store and Forward offline payments](/point-of-sale/ipp-mobile/#supported-functionality). * Check for **security threats** that would block transactions. If threats are detected that an operator can solve, the response includes information about the cause and solution of the problem. * Check the **expiry date** of the [Android](/point-of-sale/mobile-android/manage/#keep-the-mobile-sdk-up-to-date) or [iOS](/point-of-sale/mobile-ios/manage/#keep-the-mobile-sdk-up-to-date) SDK that is used on the mobile device. Transactions will be blocked if mandatory updates are not carried out. * For an iOS Mobile SDK solution, check if there are **failed captures** that need to be retried. Proceed as follows: 1. Make a Terminal API diagnosis request with: * [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header): The standard `MessageHeader` object, with the following parameters. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Diagnosis** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used. | | `SaleID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The installation ID of the SDK, for example **AC2ABBE8-EDD8-4E2B-AF45-8770FA2347DC.924**. | * The [DiagnosisRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/diagnosis) object with: | Parameter | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HostDiagnosisFlag` | Set the value to **true** so that the SDK will try to connect to Adyen for a security scan, to forward any stored offline transactions, and to retry sending any transactions that previously failed to capture (iOS mobile solution only). If you set this field to **false**, in a mobile solution, the SDK will not connect to Adyen. | **Diagnosis request for a Mobile solution** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Diagnosis", "MessageType":"Request", "ServiceID": "YOUR_UNIQUE_REQUEST_ID", "SaleID":"YOUR_POS_SYSTEM_ID", "POIID":"SDK_INSTALLATION_ID" }, "DiagnosisRequest":{ "HostDiagnosisFlag":true } } } ``` 2. In the response, check the following: * The `HostStatus` array: | Parameter | Description | | ----------------- | -------------------------------------------------------------- | | `IsReachableFlag` | A Boolean that indicates if the Adyen host system was reached. | * The `Response.AdditionalResponse` string of key-value pairs separated by **&**: | Parameter | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sdkExpiry` | The date and time in UTC format when the installed Mobile SDK version expires. | | `terminalId` | The installation ID of the Mobile SDK. | | `unconfirmedBatchCount` | The number of stored transactions that have not been forwarded to the Adyen payments platform yet. | | `storeAndForwardStatus` | A Base64URL-encoded string that you can decode to get a JSON structure with information about offline transactions. | | `asyncCaptureStatus` | Only present in mobile iOS solution: The result of retried transactions that previously failed to capture. Possible values are: **Success**, **Connectivity Failure**, **Other Failure**. | | `attestationStatus` | A Base64URL-encoded string that you can decode to get a JSON structure with information about any security issues. | For iOS, there is a 3-minute wait before completed transactions are included in the capture retry. If `unconfirmedBatchCount` shows remaining transactions, wait before making another diagnosis request. **Diagnosis response for a mobile solution** ```json { "SaleToPOIResponse" : { "DiagnosisResponse" : { "Response" : { "Result" : "Success", "AdditionalResponse" : "storeAndForwardStatus=eyJhY3RpdmUiOmZhbHNlLCJhdmFpbGFibGUiOnRydWUsImV4cGlyZXNBdCI6IjIwMjUtMDQtMDlUMTI6NTc6MDIuMDAwWiJ9&sdkExpiry=2025-09-03T00:00:00.000Z&attestationStatus=eyJzdGF0dXMiOiJ2YWxpZCJ9&asyncCaptureStatus=Success&terminalId=AC2ABBE8-EDD8-4E2B-AF45-8770FA2347DC.924&unconfirmedBatchCount=0" }, "HostStatus" : [ { "AcquirerID" : "0", "IsReachableFlag" : true } ], "POIStatus" : { "GlobalStatus" : "OK", "CommunicationOKFlag" : true } }, "MessageHeader" : { "SaleID" : "YOUR_POS_SYSTEM_ID", "ServiceID" : "YOUR_UNIQUE_REQUEST_ID", "MessageClass" : "Service", "ProtocolVersion" : "3.0", "MessageCategory" : "Diagnosis", "POIID" : "SDK_INSTALLATION_ID", "MessageType" : "Response" } } } ``` 3. If present, Base64URL-decode the `storeAndForwardStatus` value. The resulting JSON object can include: | Parameter | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | Boolean | Indicates if transactions are accepted offline when the internet connectivity drops. | | `active` | Boolean | Indicates if the mobile device is currently offline. | | `expiresAt` | string | The date and time in UTC format when offline payments are no longer possible if the mobile device cannot go online to let the Adyen payments platform attest the security of the device. | | `forwardAttemptStatus` | string | Shows what happened when the SDK tried to forward stored offline transactions. Possible values: **Success**, **Connectivity failure**, **Other failure**. | **Decoded storeAndForwardStatus** ```json { "active": false, "available": true, "expiresAt": "2025-04-09T12:57:02.000Z" } ``` 4. Base64URL-decode the `attestationStatus` value. The resulting JSON object can include: | Parameter | Type | Description | | ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `status` | string | The overall result of checking the security of the mobile device. Possible values:- **Valid**: the mobile device is secure. - **Rejected**: a threat was detected. - **Failed**: could not attest the security of the device. This can be caused by a loss of internet connectivity. - **Expired**: an attestation token has expired. Retry the diagnosis request with `HostDiagnosisFlag` set to **true** when the internet connectivity is restored. | | `selfResolvableIssues` | Boolean | If **true**, one or more of the detected issues can be solved by the end user, and a `resolvableIssues` array is included with the details. | | `resolvableIssues` | array, string | A list of detected problems. Each array item consists of:- `name`: a short description of the problem. - `message`: a more detailed description of the problem and what the user could do to solve the problem. | **Decoded attestationStatus** ```json { "status": "valid" } ``` ## Failed diagnosis request When the payment terminal or mobile SDK is already processing another request, the diagnosis request fails. You receive a `DiagnosisResponse` object with: * `Response.Result`: **Failure** * `Response.ErrorCondition`: **Busy** **Diagnosis response when busy with other request** ```json { "SaleToPOIResponse": { "DiagnosisResponse": { "Response": { "Result": "Failure", "AdditionalResponse": "message=TX_IN_PROGRESS", "ErrorCondition": "Busy" } }, "MessageHeader": {...} } } ``` ## See also * [Run connection tests](/point-of-sale/pos-troubleshooting/connection-tests) * [Network and connectivity](/point-of-sale/design-your-integration/network-and-connectivity) * [Run hardware tests](/point-of-sale/pos-troubleshooting/hardware-tests) * [Mobile solutions](/point-of-sale/ipp-mobile)