Diagnosis

The Diagnosis operation conveys Information related to the target POI for which the diagnosis is requested. It is primarily used at session startup or periodically to ensure the terminal is functioning correctly, verify connectivity, and perform fraud prevention checks.

1. Diagnosis Request

Header

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

Body

The DiagnosisRequest body is minimal, it contains only the POIID field to explicitly specify the target terminal for the status check.

{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "Diagnosis",
    "MessageType": "Request",
    "ServiceID": "823",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "DiagnosisRequest": {
    "POIID": "POI_01"
  }
}

<?xml version="3.1" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="Diagnosis" MessageType="Request" ServiceID="3914" SaleID="ECR001" POIID="456"></MessageHeader>
	<DiagnosisRequest POIID="456"></DiagnosisRequest>
</SaleToPOIRequest>

2. Diagnosis Response

The Login Response confirms that the operational session has been successfully established, providing the POS system with vital status and software information about the Payment Terminal (POI).

Two different results can be expected:

• Success: A response with Response.Result: "Success".

• Failure: If a parsing error occurs, an EventNotification with EventToNotify: "Reject" is returned.

The MessageHeader you receive in the response echoes the values you provided in the request. The only exception is the MessageType, which is Response.

Body

This table details the fields required within the DiagnosisResponse object, which identifies the POI information. You will find an example of response after the table 

{
  "MessageHeader": {
    "MessageCategory": "Diagnosis",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "DiagnosisResponse": {
    "MarketpayPaymentExtensions": {
      "StoreCode": "a0WKG000004nJYQ2A2"
    },
    "PendingTransactionsCount": "0",
    "POISerialNumber": "1851055253",
    "POIStatus": {
      "GlobalStatus": "OK"
    },
    "Response": {
      "Result": "Success"
    }
  }
}

<SaleToPOIResponse>
   <DiagnosisResponse>
      <MarketpayPaymentExtensions StoreCode="a0WKG0000027TX42AM"/>
      <PendingTransactionsCount>0</PendingTransactionsCount>
      <POISerialNumber>1760317010</POISerialNumber>
      <POIStatus GlobalStatus="OK"/>
      <Response Result="Success"/>
   </DiagnosisResponse>
   <MessageHeader MessageCategory="Diagnosis" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3914"/>
</SaleToPOIResponse>

Failed Diagnosis

The POI delivers a final response message containing the definitive outcome field set to Result: "Failure". 

The card was declined by the issuer, a payment host was unreachable, or a host-specific error prevented authorization. The response body contains a diagnostic field ErrorCondition explaining the reason for the failure.

Not activated meaning application has not been activated or initialised

{
  "MessageHeader": {
    "MessageCategory": "Diagnosis",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "DiagnosisResponse": {
    "Response": {
      "Result": "Failure",
      "ErrorCondition": "Not activated"
    }
  }
}

Event Notification

This signals that the POI could not understand the structure of the message sent by the POS. The POI sends an EventNotification message with the EventToNotify field set to Reject. The payment request message was syntactically incorrect, missing a required field, or corrupted during transmission. 

POS needs to inspect the payload sent to the POI, correct the structural error (formatting, required fields...), and then re-attempt the transaction.

{
  "MessageHeader": {
    "MessageCategory": "EventNotification",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "EventNotification": {
    "TimeStamp": "2025-11-28T14:12:59.6+01:00",
    "EventToNotify": "Reject"
  }
}

3. Diagnosis against fraud

The Diagnosis allows the Point of Sale (POS) application to retrieve the hardware's unique Serial Number. The primary interest in using the Serial Number validation is fraud prevention and system integrity.

The POS can perform a quick check during login to retrieve POI's unique serial number. By comparing this number against a stored record, your system can immediately detect if an unauthorized or unknown terminal has been swapped into the setup. This creates a simple, secure, verifiable binding between the POS software and the physical POI device.

You will find below a simple proposition of implementation:

1. First installation: retrieve and store POI's Serial Number through a Diagnosis request. First installation should be trusted as per installation process.

2. Next login: POS runs a new Diagnosis request. If the returned Serial Number does not match the stored value, the POS must alert the user to confirm if POI was legitimately changed or not.

You could also compare the Serial Number with the known Serial Number from your Database. This can be made easier for P2PE compliant customers which have to follow Payment Terminals whole lifecyle.