Application Update

The Application Update is a crucial administrative operation that allows the Point of Sale (POS) to manually trigger the Payment Terminal (POI) to synchronize with the NTMS (Nexo Terminal Management System) server. This function ensures the terminal fleet remains current and provides diagnostic capabilities.

1. Function and Capabilities

The primary purpose of the Update is to force the terminal to establish a connection with the central management system to perform necessary administrative tasks.

• Trigger Mechanism: The POS sends the request to the POI, and the POI then autonomously connects to the NTMS.

• Core Capabilities:

  • Configuration Update: Downloads and applies the latest terminal settings and parameters.

  • Application Update: Installs new versions of the payment application software.

  • Log Management: Uploads application and OS logs from the terminal for remote diagnostics and troubleshooting.

2. Why POS-Triggered Update is interesting

The Update endpoint is a critical mechanism for proactive terminal management, even though terminals typically manage their updates autonomously.

Terminals are generally configured to connect to the NTMS (Nexo Terminal Management System) server automatically during the night to perform routine maintenance, including downloading configuration updates, installing application patches, and uploading accumulated diagnostic logs.

The Update function becomes essential for immediate operational needs and risk mitigation:

1. Forcing Immediate Synchronization: If a critical configuration change is deployed during the day, the POS can trigger Update to bypass the nightly schedule, ensuring the terminal is running the latest parameters immediately.

2. Instant Incident Response: This operation provides a vital, non-manual way to force the upload of application and OS logs to the NTMS in the event of an issue or incident. This allows support teams to diagnose terminal problems remotely without requiring physical intervention from the cashier or store personnel.

3. Mitigating Nightly Failures: The manual update is critical if the terminal was turned off or lacked an internet connection overnight. In such cases, the terminal would have missed its scheduled maintenance window, making the ability to force a connection from the POS a necessary operation to ensure the terminal remains compliant and up-to-date.

3. Required Payload and Structure

The Update request is a Synchronous (SYNC) operation that uses the generic AdminRequest message structure.

A. Update Request

Header

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

Body

The only field is the Base64-encoded string in AdminRequest.ServiceIdentification. This string contains the actual XML command passed to the terminal's kernel.

• Decoded Content: PFJlcXVlc3Q+CiAgICA8QWN0aW9uPlVwZGF0ZTwvQWN0aW9uPgogICAgPFRpbWVvdXQ+NTAwMDwvVGltZW91dD4KPC9SZXF1ZXN0Pgo= decodes to XML:

  <Request>
     <Action>Update</Action>
     <Timeout>5000</Timeout>
  </Request>

• Purpose: This confirms that the request triggers the Update action with a specified timeout (5000 milliseconds in this example).

{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "Admin",
    "MessageType": "Request",
    "ServiceID": "823",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "AdminRequest": {
    "ServiceIdentification": "PFJlcXVlc3Q+CiAgICA8QWN0aW9uPlVwZGF0ZTwvQWN0aW9uPgogICAgPFRpbWVvdXQ+NTAwMDwvVGltZW91dD4KPC9SZXF1ZXN0Pgo="
  }
}

<?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="Admin" MessageType="Request" ServiceID="3916" SaleID="ECR001" POIID="456"></MessageHeader>
	<AdminRequest>
		<ServiceIdentification>PFJlcXVlc3Q+CiAgICA8QWN0aW9uPlVwZGF0ZTwvQWN0aW9uPgogICAgPFRpbWVvdXQ+NTAwMDwvVGltZW91dD4KPC9SZXF1ZXN0Pgo=</ServiceIdentification>
	</AdminRequest>
</SaleToPOIRequest>

C. Update Response

The Update Response body confirms the successful execution of an Update using the Response object:

• Result: The Success result indicates that the terminal accepted the command and has begun the requested operation.

• AdditionalResponse (Base64 XML): This encoded message confirms the internal action that was started. It decodes to: <Response><Action>Update</Action><Success>true</Success></Response>. This simply means the command to trigger a terminal software/configuration update was successfully launched.

{
  "SaleToPOIResponse": {
    "AdminResponse": {
      "Response": {
        "Result": "Success",
        "AdditionalResponse": "PFJlc3BvbnNlPgogICA8QWN0aW9uPlVwZGF0ZTwvQWN0aW9uPgogICA8U3VjY2Vzcz50cnVlPC9TdWNjZXNzPgo8L1Jlc3BvbnNlPg=="
      }
    },
    "MessageHeader": {
      "MessageCategory": "Admin",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "POI_01",
      "ProtocolVersion": "3.1",
      "SaleID": "POS_01",
      "ServiceID": "3916"
    }
  }
}

<SaleToPOIResponse>
   <AdminResponse>
      <Response Result="Success">
         <AdditionalResponse>PFJlc3BvbnNlPgogICA8QWN0aW9uPlVwZGF0ZTwvQWN0aW9uPgogICA8U3VjY2Vzcz50cnVlPC9TdWNjZXNzPgo8L1Jlc3BvbnNlPg==</AdditionalResponse>
      </Response>
   </AdminResponse>
   <MessageHeader MessageCategory="Admin" MessageClass="Service" MessageType="Response" POIID="POI_01" ProtocolVersion="3.1" SaleID="POS_01" ServiceID="3916"/>
</SaleToPOIResponse>

EventNotification

When a Login Request fails, the Payment Terminal (POI) responds with a specialized EventNotification message, signaling that the message was rejected or could not be processed. This is typically the POI's method of communicating an unrecoverable structural or parsing error immediately to the Point of Sale (POS).

The MessageHeader you receive for an EventNotification echoes the values you provided in the request. The two exceptions are the MessageCategory which is EventNotification and MessageType, which is Response.

{
  "MessageHeader": {
    "MessageCategory": "EventNotification",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_123",
    "ProtocolVersion": "3.1",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "EventNotification": {
    "TimeStamp": "2025-04-02T15:48:47.596+02:00",
    "EventToNotify": "Reject"
  }
}

These occur when the POI cannot be reached or the session parameters are incorrect.

• Invalid Message Format: The LoginRequest is missing required fields (e.g., DateTime, SaleSoftware), or the structure is corrupted.

• POI Unreachable: The terminal is powered off, disconnected from the network, or its IP address is unknown/incorrect.