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. This includes:

   Parameter	Required	Description
   ProtocolVersion		3.0
   MessageClass		Service
   MessageCategory		Diagnosis
   MessageType		Request
   ServiceID		Your unique ID for this request.
   SaleID		Your unique ID for the system where you send this request from.
   POIID		The unique ID of the terminal that you send this request to.

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

   The response contains a DiagnosisResponse object with:

   • 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 can't 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: indicates through the pre-set value ARS_TRIGGERED when Anti-removal switches (ARS) are triggered. Only included on UX300 and UX410 terminals and only if ARS was triggered.

     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.

2. 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. This includes:

   Parameter	Required	Description
   MessageClass		Service
   MessageCategory		Diagnosis

   • 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