Terminal-2 icon

Make a diagnosis request

Check the state of a payment terminal or mobile device, and any offline transactions.

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:

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

1. Verify the condition of a terminal

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

  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.

For a complete list of fields you can pass and receive, see DiagnosisRequest.

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 check if 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 -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Diagnosis
      MessageType -white_check_mark- Request
      ServiceID -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- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- 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 Adyen 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.

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.

  • 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 or iOS SDK that is used on the mobile device. Transactions will be blocked if mandatory updates are not carried out.

Proceed as follows:

  1. Create a Terminal API DiagnosisRequest with:

    • MessageHeader.POIID: the installation ID of the SDK, for example AC2ABBE8-EDD8-4E2B-AF45-8770FA2347DC.924.
    • DiagnosisRequest.HostDiagnosisFlag: set to true, so that the SDK will try to connect to Adyen for a security scan and to forward any stored offline transactions. If you set this field to false, the SDK will not connect to Ayden.

    The response will be similar to the following example.

  2. In the Response, check the following:

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

    • AdditionalResponse: a string of key-value pairs separated by & that can include:

      • 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 Base64-encoded string with more information about offline transactions.

      • attestationStatus: a Base64-encoded string with information about any security issues.

  3. If present, Base64-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.

  4. Base64-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.

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

See also