Make a diagnosis request

A DiagnosisRequest lets you verify the condition of a payment terminal and its components such as the communication module and the built-in printer, if the terminal has one.

The diagnosis request also supports you in business critical processes, because the response includes:

• batteryLevel: This field is included for battery-powered terminals, and shows the battery charge level. This enables you to inform your staff they need to recharge the payment terminal soon. For guidelines regarding terminal battery usage, see Manage battery power.
• unconfirmedBatchCount: The number of payments that the terminal hasn't been able to send to the Adyen host for completion (capture and settlement).

Step 1: Make a diagnosis request

To verify the condition of a payment terminal:

1. Make a POST request to a Terminal API endpoint, specifying:

   • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		Diagnosis
     MessageType		Request
     ServiceID		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		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • DiagnosisRequest.HostDiagnosisFlag: initially set this to false.
     You only need to set this to true for further diagnosis when the initial response includes an unconfirmedBatchCount greater than zero. This is explained in the next step.

2. Use the following parts of the response to check the condition of the terminal:

   • POIStatus:

     • GlobalStatus: the condition of the payment terminal.
     • CommunicationOKFlag: Boolean that indicates whether the general condition of the communication module is OK.

     • PrinterStatus (only included when the payment terminal has a built-in printer): the condition of the
       printer module. NoPaper indicates the receipt paper roll is missing or the paper is not sticking out.

   • Response.AdditionalResponse: a string of key-value pairs separated by & that includes:

     • batteryLevel: the battery charge level as a percentage of fully charged (only included for
       battery-powered terminals).
     • unconfirmedBatchCount: number of payments that the terminal hasn't yet sent for completion to our platform, and thus cannot be settled.
     • firmwareVersion: software version that the terminal is on.
     • networkProfile: a Base64 string. Decode this to see the IP address of the terminal and other network data.
     • merchantAccount: merchant account that the diagnosed payment terminal is assigned to.
     • terminalId: POIID of the diagnosed payment terminal, in the format [device model]-[serial number].
     • storeId: store that the diagnosed payment terminal is assigned to.
     • tamperStatus: the value ARS_TRIGGERED indicates that anti-removal switches (ARS) have been
       triggered. This means you must stop using the terminal immediately. Only applies to UX300 and UX410
       terminals.

     If the terminal uses Point-to-Point Encryption (P2PE) instead of Adyen End-to-End Encryption (E2EE), Response.AdditionalResponse also contains the following fields:

     • p2peFirmwareVersionNumber: the version number of the P2PE software managed and used by Adyen.

     For your annual PCI assessment, you need to specify the following four fields that are all provided by the hardware manufacturer.

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

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.

Step 2: Verify that the Adyen host system is reachable

If the diagnosis response shows an unconfirmedBatchCount greater than 0, there may be a problem with your network. To verify whether this is the case, make another diagnosis request:

1. Make a POST request to a Terminal API endpoint, specifying:

   • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		Diagnosis
     MessageType		Request
     ServiceID		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		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • DiagnosisRequest.HostDiagnosisFlag: true. A communication test will try to reach the Adyen host system.

   The diagnosis response now also includes:

   • HostStatus: array of 1 host (Adyen) with an IsReachableFlag to indicate if the host system was reached.

2. In the response, check the HostStatus. If the Adyen host system could not be reached, you may need to adjust your firewall settings or other network aspects.

Failed diagnosis request

When the payment terminal is already processing another request, the diagnosis request fails. You receive a DiagnosisResponse object with:

• Response.Result: Failure
• Response.ErrorCondition: Busy

See also