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 parameter 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 Terminal API request, specifying:

    • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Diagnosis.

      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:

    • The POIStatus object:

      Parameter Description
      GlobalStatus The condition of the payment terminal.
      CommunicationOKFlag A Boolean that indicates whether the general condition of the communication module is OK.
      PrinterStatus This parameter is included when the payment terminal has a built-in printer, and indicates the condition of the printer module. NoPaper indicates the receipt paper roll is missing or the paper is not sticking out.

    • The Response.AdditionalResponse string of key-value pairs separated by &:

      Parameter Description
      batteryLevel This parameter is included for battery-powered terminals, and indicates the battery charge level as a percentage of fully charged.
      unconfirmedBatchCount The number of payments that the terminal has not yet sent for completion to our platform, and thus cannot be settled.
      firmwareVersion The 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 The merchant account that the diagnosed payment terminal is assigned to.
      terminalId The POIID of the diagnosed payment terminal, in the format [device model]-[serial number].
      storeId The store that the diagnosed payment terminal is assigned to.
      tamperStatus This parameter only applies to UX300 and UX410 terminals. The value ARS_TRIGGERED indicates that anti-removal switches (ARS) have been triggered. This means you must stop using the terminal immediately.

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

      The diagnosis response includes P2PE protocol, SRED, vault, and app manager versions as provided by the hardware manufacturer. You need to specify this data in your annual PCI assessment.

      Parameter Description
      p2peFirmwareVersionNumber The version number of the P2PE software managed and used by Adyen.
      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.

2. Verify that the Adyen host system is reachable

If the diagnosis response shows an unconfirmedBatchCount greater than 0 (zero), there may be a problem with your network. To check if this is the case:

  1. Make another diagnosis request as described under 1. Verify the condition of a terminal, but this time set
    DiagnosisRequest.HostDiagnosisFlag to true. A communication test will try to reach the Adyen host system.

  2. In the response, check the HostStatus array:

    Parameter Description
    IsReachableFlag A Boolean that indicates if the Adyen host system was reached. 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. Make a Terminal API diagnosis request with:

    • SaleToPOIRequest.MessageHeader : The standard MessageHeader object, with the following parameters.

      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 installation ID of the SDK, for example AC2ABBE8-EDD8-4E2B-AF45-8770FA2347DC.924.

    • DiagnosisRequest: The request body. This must include:

      Parameter Description
      HostDiagnosisFlag Set the value 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 Adyen.

  2. In the response, check the following:

    • The HostStatus array:

      Parameter Description
      IsReachableFlag A Boolean that indicates if the Adyen host system was reached.

    • The Response.AdditionalResponse string of key-value pairs separated by &:

      Parameter Description
      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