Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Request diagnosis

Check the state of a payment terminal and the battery charge level.

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. This enables you to inform your staff that they need to recharge the payment terminal soon.
  • 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":"0403104624",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-346403161"
            },
            "DiagnosisRequest":{
                "HostDiagnosisFlag":false
            }
        }
    }
    {
        "SaleToPOIResponse": {
            "MessageHeader": {
                "ProtocolVersion": "3.0",
                "SaleID": "POSSystemID12345",
                "MessageClass": "Service",
                "MessageCategory": "Diagnosis",
                "ServiceID": "0403104625",
                "POIID": "V400m-346403161",
                "MessageType": "Response"
            },
            "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"
                }
            }
        }
    }
    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);

    When the request is successfully processed (see the JSON response above), note that 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.
      • 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.

  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
            }
        }
    }
    {
        "SaleToPOIResponse": {
            "MessageHeader": {
                "ProtocolVersion": "3.0",
                "SaleID": "POSSystemID12345",
                "MessageClass": "Service",
                "MessageCategory": "Diagnosis",
                "ServiceID": "0403104626",
                "POIID": "V400m-346403161",
                "MessageType": "Response"
            },
            "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"
                    }
                ]
            }
        }
    }
    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 (see the JSON response above) 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
{
    "SaleToPOIResponse": {
        "MessageHeader": {...},
        "DiagnosisResponse": {
            "Response": {
                "Result": "Failure",
                "AdditionalResponse": "message=TX_IN_PROGRESS",
                "ErrorCondition": "Busy"
            }
        }
    }
}

See also