Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Make a diagnosis request

Check the state of a payment terminal.

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: The battery charge level (Only included for battery-powered terminals). This enables you to inform your staff that they need to recharge the payment terminal soon. For more information about managing your terminal battery, 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).

An unconfirmedBatchCount greater than 0 (zero) indicates that there may be a problem with your network. Refer to Step 2: Verify that the Adyen host system is reachable.

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:

    • 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.
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Diagnosis",
                "MessageType":"Request",
                "ServiceID":"040",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "DiagnosisRequest":{
                "HostDiagnosisFlag":false
            }
        }
    }
    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);

    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.

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

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

      For your annual PCI assessment, you need to provide 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.
    Diagnosis response for a battery-powered terminal
    {
        "SaleToPOIResponse": {
            "DiagnosisResponse": {
                "POIStatus": {
                    "CommunicationOKFlag": true,
                    "PrinterStatus": "OK",
                    "GlobalStatus": "OK"
                },
                "Response": {
                    "Result": "Success",
                    "AdditionalResponse": "batteryLevel=100%25&firmwareVersion=adyen_v1_69p4&networkProfile=WyB7ICJBZGRyZXNzIjogIjE5Mi4xNjguMi4yIiwgIklmYWNlIjogIndsYW4wIiB9IF0%3d&merchantAccount=YOUR_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's not battery-powered
    {
      "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=YOUR_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"
        }
      }
    }
  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.

For a complete list of fields you can pass and receive, see the DiagnosisRequest API reference and the DiagnosisResponse API reference.

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:

    • DiagnosisRequest.HostDiagnosisFlag: true. A communication test will try to reach the Adyen host system.
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Diagnosis",
                "MessageType":"Request",
                "ServiceID":"0403104624",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "DiagnosisRequest":{
                "HostDiagnosisFlag":true
            }
        }
    }
    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);

    The diagnosis response now also includes:

    • HostStatus: Array of 1 host (Adyen) with an IsReachableFlag to indicate if the host system was reached.
    Diagnosis response when Adyen host is reached
    {
    "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=YOUR_MERCHANT_ACCOUNT&unconfirmedBatchCount=0&terminalId=V400m-346403161&storeId=YOUR_STORE"
            },
            "HostStatus": [
                {
                    "IsReachableFlag": true,
                    "AcquirerID": "0"
                }
            ]
        }
    }
    }
  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
Diagnosis response when terminal is busy
{
    "SaleToPOIResponse": {
        "DiagnosisResponse": {
            "Response": {
                "Result": "Failure",
                "AdditionalResponse": "message=TX_IN_PROGRESS",
                "ErrorCondition": "Busy"
            }
        },
        "MessageHeader": {...}
    }
}

See also