Extensions for Financial Services (XFS)

XFS4IoT Specification

Release 2021-1 Release Candidate

This CEN Workshop Agreement has been drafted and approved by a Workshop of representatives of interested parties, the constitution of which is indicated in the foreword of this Workshop Agreement.

The formal process followed by the Workshop in the development of this Workshop Agreement has been endorsed by the National Members of CEN but neither the National Members of CEN nor the CEN-CENELEC Management Centre can be held accountable for the technical content of this CEN Workshop Agreement or possible conflicts with standards or legislation.

This CEN Workshop Agreement can in no way be held as being an official standard developed by CEN and its Members.

This CEN Workshop Agreement is publicly available as a reference document from the CEN Members National Standard Bodies.

CEN members are the national standards bodies of Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Republic of North Macedonia, Romania, Serbia, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey and United Kingdom.

Warning

This document is not a CEN Workshop Agreement. It is distributed for review and comment. It is subject to change without notice and may not be referred to as a CEN Workshop Agreement.

Recipients should notify the committee of any relevant patent rights of which they are aware and to provide supporting documentation.

EUROPEAN COMMITTEE FOR STANDARDIZATION
COMITÉ EUROPÉEN DE NORMALISATION
EUROPÄISCHES KOMITEE FÜR NORMUNG

Management Centre: rue de Stassart, 36 B-1050 Brussels

© 2021 CEN All rights of exploitation in any form and by any means reserved worldwide for CEN national Members.

Table of Contents

1 - Foreword

XFS4IoT has been identified as a successor to XFS 3.x to meet the following requirements:

  1. Replace the XFS and J/XFS standards in the marketplace.
  2. Target industries – Retail Banking.
  3. Operating System Agnostic and Technology and Language Adaptable.
  4. Multi-Vendor – Able to run common core high level functionality on multiple vendors hardware, while providing access to finer level device API granularity.
  5. Flexibility – enabling new hardware topologies, device types and functionality to be rapidly adapted.
  6. Support end to end application level security.
  7. Should not prevent the use of a low resource computing environment.
  8. Provide a good developer experience by providing a well-documented API that is easy to learn, is quick to market and reduces risk by exposing an unambiguous interface.
  9. Leverage existing standards.

Within the overall requirements specified in the Charter, the opportunity has been taken to solve some of the issues with the 3.x interface while retaining all the same functionality:

  1. Binary data structures makes adding new functionality difficult due to compatibility issues, leading to multiple redundant versions of the same command appearing in many of the existing device classes. To resolve this, a flexible text based approach has been adopted including the wide use of default parameters.
  2. Compound devices have been difficult for applications to implement, particularly cash recycling. Addition of other shared functionality such as end to end security would make the use of compound devices more prevalent. Compound devices are removed in XFS4IoT, a single Service can support as many interfaces as required to support its requirements.

Migration from and to 3.x is a major consideration to support adoption of XFS4IoT. While a lot of duplication has been removed (for example the Card Reader interface has fewer commands and events defined than the equivalent 3.x IDC specification), all the same IDC commands and events can be implemented. In some cases, this is achieved by having shared common commands such as Common.Status which replaces all the 3.x WFS_INF_XXX_STATUS commands.

2 - API

This chapter defines the API functionality and messages. It defines the XFS4IoT API including but not limited to:

  • System Architecture
  • Message Definition
  • End to End Security

XFS4IoT defines a system consisting of Services provided by one or more vendors. Each Service can support one or more interfaces as required to meet the requirements of the device or function it supports, so for example a Cash Recycling device will need the following interfaces to supply all the device's functionality:

  • Common, which defines functionality common to all devices
  • CashManagement, which defines functionality common to all cash handling devices
  • CashAcceptor, which defines functionality common to all cash accepting devices
  • CashDispenser, which defines functionality common to all cash dispensing devices
  • Storage, which defines functionality common to devices which store items

Additional interfaces can be added as required for example KeyManagement to support encryption key management.

The following sections describe how clients and services create connections and send messages to each other.

2.1 - References

ID Description
api-1 JSON (https://www.json.org/)
api-2 XFS Interface Specification, End to End (E2E) for XFS/XFS4IoT Programmer's Reference
api-3 WebSockets - IETF RFC 6455

2.2 - WebSockets Connections

Multiple services can be supplied by multiple vendors. This standard doesn't require coordination between these different vendors, or between the service publishers and the service client. It is possible to operate a system with components from multiple hardware vendors, and with third party applications, without the prior knowledge of any party.

This specification covers an environment using WebSockets (ref. api-3) to communicate between services and applications, either on a single machine or across a network.

This section covers both the process for publishing a service such that it can be discovered, and the discovery process used by the service client.

There is also a clear definition of responsibility for each component in the system, including when there are dependencies between components. There are no shared components required to coordinate the system.

The underlying network can use any protocol that supports WebSockets such as IPv4 or IPv6. Nothing in this document requires any particular underlying protocol.

2.2.1 - Overview

In this standard there are two types of "endpoint"; publisher and service. Each endpoint, of either type, is published by a single software/hardware vendor. A publisher endpoint is used for service discovery, to discover service endpoints. A single service endpoint can expose multiple "services", where each service typically represents a single piece of hardware. A single machine (or a single IP address) may expose multiple publisher and service endpoints from different vendors. A "client" application may consume multiple services from multiple service endpoints on the same machine, or across multiple machines.

On startup of the machine, any software services attempt to claim access to individual network ports using the underlying operating system mechanism. Ports are claimed sequentially from a known sequence. Each port becomes an endpoint that can publish multiple services from a single vendor.

A client application will attempt to connect to each port on a machine in the known sequence to get a list of all active publisher endpoints. For each publisher endpoint it then exchanges JSON messages across WebSockets with URIs using a known format to recover a list of services published by that endpoint. Once it has a full list of services it can use WebSocket connections to communicate with each service to perform whichever actions are required.

2.2.2 - Uniform Resource Identifier (URI)

This section describes the Uniform Resource Identifiers used in XFS4IoT.

2.2.2.1 - URI Format

Communication with service publishers and services will be through distinct URIs which will use the following format:

wss://machinename:portnumber/xfs4iot/v1.0/servicename

This URI consists of the following components:

URI Component Description
wss:// or ws:// The protocol id for secure WebSockets. See Network Protocol.
machinename The identification of the machine publishing endpoints. See Machine Identification.
portnumber The port number discovered through the initial service discovery process - see Port Sequence.
xfs4iot A literal string. The inclusion of this part identifies standard XFS4IoT services published on this URI. It allows the possibility of a single vendor publishing standard and non-standard proprietary services on the same port. Any standard service URI will start with this string. Any non-standard service's URI must not start with this string.
v1.0 The version of the protocol being used by this service. This may be updated to support services with different protocol versions in future versions of the specification and allows support for multiple versions of the specification on the same machine and endpoint.

Note that most future changes to the XFS4IoT specification will be done in a non-breaking, backwards and forwards compatible way. For example, optional fields will be added to JSON messages when required and will have no impact on the protocol. This means that changes to the version field of the URI will be very rare. It will only be changed if there is a breaking, incompatible change or a fundamental change to the API. Because of this there won't be any need for complex version negotiation between the client and the service. The client will simply attempt to open the version of the API that it supports.
servicename This will be included in the URI to allow different services to be identified on the same port. Services will normally match individual devices. The exact service name is discovered during service discovery and is vendor dependent. The format of the service name shouldn't be assumed. The only URI that doesn't include a service name is the service discovery URI.

For example, a service discovery URI might be:

  • wss://terminal321.atmnetwork.corporatenet:443/xfs4iot/v1.0
  • wss://192.168.21.43:5848/xfs4iot/v1.0

Service URI might be:

  • wss://terminal321.atmnetwork.corporatenet:443/xfs4iot/v1.0/maincashdispenser
  • wss://192.168.21.43:5848/xfs4iot/v1.0/cardreader1

The URI will be case sensitive and lower case.

2.2.2.2 - Network Protocol

The WebSocket protocol defines two URI schemes, wss and ws that are used for encrypted and unencrypted connections. All connections in XFS4IoT should use the wss scheme using TLS encryption to secure network connections. The only exception will be when the network connection between the client and service can be physically secured, for example inside an ATM enclosure. In that case it will be possible to use clear communication without TLS encryption and it is the responsibility of the hardware vendor to ensure that this is sufficient.

  • Encrypted connections are identified by the wss:// protocol specifier.
  • Unencrypted connections are identified by the ws:// protocol specifier.

Where TLS is used, the service will be protected by a mutually trusted server side certificate as part of the TLS protocol. This complete certificate chain must be mutually trusted by the client and service.

Establishing and managing the certificates between the service and the client is outside of the scope of this specification but trust must be in place. This might be achieved using a public third party certificate authority that issues TLS certificates. Alternatively it might be achieved using a bank's own internal CA. It shouldn't depend on a private Certificate Authority or certificates issued by a vendor, which might limit access to the service.

A wss connection with invalid certificates will be invalid and will be rejected by both the client and the service.

2.2.2.3 - Machine Identification

Machines publishing services are identified by URIs. Machines exposing endpoints can be identified by an IP address or by a DNS name.

Either the IP address or DNS name for a machine must be known by the client for the client to connect. This would probably be a configuration setting for the application and would need to be known by the organization setting up the application, but this configuration is outside the scope of this document.

2.2.2.4 - Port Sequence

Services will be published on a sequence of IP ports consisting of port 80 or 443 followed by the ports 5846 to 5856 inclusive. Hence the full sequence of ports will be 12 ports as,

80 or 443, 5846, 5847, 5848, ... 5855, 5856

Port 80 will only be used with HTTP/WS. Port 443 will only be used with HTTPS/WSS. All other ports may be used with either or both HTTP/WS and HTTPS/WSS.

Port 80 and 443 are the standard ports for HTTP and HTTPS and have the advantage that they are likely to be open on firewalls. The correct port will be used to match the protocol - 80 for HTTP/WS and 443 for HTTPS/WSS. Other ports are flexible and can be used for either protocol by the Service Publisher.

The port range 5846-5856 is semi-randomly selected in the 'user' range of the port space as defined by ICANN/IANA. This range is currently unassigned by IANA.

2.2.3 - Service Publishing

Service publishers will negotiate access to resources and publish services using the following process.

2.2.3.1 - Free Endpoint Port Discovery

On startup each service publisher must attempt to connect to the first port in the port sequence. It will use the underlying OS and network stack to attempt to bind to this port.

All network access must go through the normal underlying OS mechanism. One service publisher must not block another publisher from accessing the network.

If the underlying OS reports that the port is already in use the service publisher will repeat the same process with the next port in the port sequence. This will be repeated until a port is successfully bound to, or all ports in the sequence have been tried.

If no available port can be found the service publisher will have failed to start. How this failure is handled by the service publisher is undefined.

It's important that a single hardware vendor doesn't use up multiple ports, since this could lead to all the ports being blocked so that other publishers can't get a free port. Therefore any single hardware vendor must publish all services on a single port, determined dynamically as above.

Note: A service publisher will only fail to find a free port if more than 12 different hardware vendors are attempting to publish services from the same machine. This should be unusual.

2.2.3.2 - Handling Incoming Connections

Once a service publisher has successfully bound to a port it must handle connection attempts. It will accept all connections from any clients without filtering attempts. Security around connections will be handled after a connection has been established.

Note: This document does not cover restrictions on connections to services or managing permissions for connections, such as limiting connections to certain machines or sub-nets. This would normally be under the control of the machine deployer and can be controlled through normal firewall settings and network configuration.

Incoming connection attempts will specify a specific URI using the normal WebSocket process. The service publisher will allow connections to valid URIs as defined in this spec and track which URI each connection was made to.

The initial connection will be to the URI wss://machinename:port/xfs4iot/v1.0. This connection will then be used to list/discover individual services using the process outlined in Service Endpoint Discovery.

2.2.4 - Service Discovery

A client application must be able to discover and open a connection to each service that it will use. It does this in two steps; firstly, through publisher endpoint discovery, then through service discovery for each service endpoint. It will do this through the following process.

2.2.4.1 - Publisher Endpoint Discovery

The client will enumerate endpoints by attempting to open a WebSocket connection to the following URL on each port in the Port sequence.

wss://machinename:portnumber/xfs4iot/v1.0

The client will continue to enumerate publisher endpoints by repeating for each port number in the port sequence until all ports have been tried.

The client will also start service endpoint discovery on the open connection. There is no requirement for the order of opening ports and discovering services. All ports connections may be created first followed by service discovery, or port enumeration and service discovery may continue in parallel.

If the connection attempt to any port fails then the application will attempt error handling for network issues, machine powered off, etc. The details of error handling are left up to the client.

2.2.4.2 - Service Endpoint Discovery

Once a connection has been established between the client and each publisher endpoint, the client will discover the services published by sending a service discovery command and receiving messages in the usual way as described in Message Types.

GeneratedDiagram

The only command sent to the publisher endpoint will be ServicePublisher.GetServices.

The publisher will acknowledge the command.

The command will be followed by zero or more ServicePublisher.ServiceDetailEvent messages, then complete with a completion message. Each event and the completion message will contain the following payload:

{
  "payload": {
    "vendorName": "<Name of hardware/software vendor>",
    "services": [
      {
        "serviceURI": "wss://machinename:port/xfs4iot/v1.0/<servicename1>"
      },
      {
        "serviceURI": "wss://machinename:port/xfs4iot/v1.0/<servicename2>"
      }
    ]
  }
}

The service endpoint URI will be returned as a serviceURI property.

A publisher service may be designed to send one URI per message, or it may group URI together into a smaller number of messages. The publisher should try and send messages to report on each URI as soon as each URI is known. It's possible a publisher will know the complete set of URI when they're requested and can send them all at once in one or more messages. Alternatively, the URI may not be known straight away, for example if an IP address or port is being dynamically allocated. In that case the publisher service would delay sending events for unknown URI until the full URI is known.

Having each URI reported only once means that a client can connect to each URI reported in events without having to track which URI have already been connected to. This simplifies the client. Alternatively, a client may wait for the completion event and a full set of URI before attempting to connect. This would be simpler to implement but might be slower to start up.

The completion message will contain every URI that the publisher service is aware of.

The publisher service will follow the above process to publish all URI that it's aware of. It will not suppress URI based on device status or service status.

For example, a device might be powered off, in the process of powering on, or powered on but have a hardware fault that makes it impossible to use. In all cases the publisher service will publish the URI anyway. The client can't assume anything about the device based on the URI. It will always need to query the service at the URI for its status to know more.

Events should be sent as soon as a URI is known by the publisher - the event doesn't mean or imply that the URI is currently available or can be connected to - that error handling must be performed by the client.

Note: Even if the publisher service could know that a URI was valid at the time that it sends the event, the client can't know that the URI is still valid when it attempts to use the URI. It could have failed between querying and connecting. So the client has to handle errors, timeouts and retrying when connecting to the URI.

The client may then attempt to open a WebSocket connection to each of the returned URI. The client will handle connection failures and timeouts by repeating the attempts to connect such that the service has a reasonable amount of time to start up.

Each service will endeavor to accept connections as quickly as possible during startup and restarts. Some devices are physically slow to start up, but software should be able to start relatively quickly. So, for example, a cash recycler device might be able to accept a connection within a few seconds of power being applied, but the physical hardware can take several minutes to reset. Once a connection has been accepted a service may continue to report device as starting until the device is physically started and ready. While starting, any command on the connection other than Common.Status will fail with sequenceError.

Each connection will be used to communicate with a single service. The service will then be queried for details about that service, such as the type of service or device that it represents and the messages and interfaces that it supports.

The connection to the service will be kept open for as long as the service is in use. Details of the service lifetime are covered elsewhere.

The returned URI is a full URI including the machine name and port. It is possible that these values will be different to the service discovery URI - each service may be on a different machine, a different IP address, and a different port. The port is also independent of the discovery port range. It can be any port number.

The service URI values will have the same version number as the service discovery URI version number. Different versions of the API will not be mixed.

If a client wants to open multiple different API version numbers then it should perform service discovery against each of the possible version URI strings.

The client may close the publisher connection once it has completed service discovery, or it may keep the connection open. This will have no effect on the behavior of services.

2.3 - Messages

XFS4IoT Services are accessed using messages passed over a WebSocket Interface. The messages are JSON formatted data Ref. api-1.

2.3.1 - API Definition

All messages follow the same JSON structure consisting of two mandatory properties:

  • header : containing properties that are common across all messages to allow the payload to be identified
  • payload : containing properties that are specific to the message. It should be noted that not all messages require payload properties, so the payload may be empty.

These are the only two properties defined at the top level of the JSON structure as illustrated in the example below.

{
    "header": {
    },
    "payload": {
    }
}

2.3.2 - Header Definition

Headers are consistent across all XFS4IoT messages. All of the following properties are required.

Property Property Type Description
type string The message type. See Message Types.
name string The message name, for example Common.Status.
requestId integer Unique request identifier supplied by the client used to correlate the command with acknowledge, event and completion messages. For unsolicited messages the value will be 0. For all other message types this will be non-zero. The client will supply values that are positive, incremental and greater than 1, so that unsolicited events can be distinguished. The service will check that the requestId does not conflict with a currently executing or queued command request from the same client and reject if it does.

The following example illustrates the header for a Common.Status command message.

{
    "header": {
        "type": "command",
        "name": "Common.Status",
        "requestId": 12345
    },
    "payload": {
    }
}

2.3.3 - Payload Definition

The XFS4IoT interface specifications detail the payload content for the command, event, completion and unsolicited messages.

2.3.4 - Additional Properties

It is possible to include additional properties not defined by the specification. This can be useful in some cases and is allowed as long as those additional properties do not impact the proper functioning of the service or client.

For example, it may be useful to include properties with extra debugging information such as human readable error messages or hardware specific error codes.

When non-standard properties are used there's a risk that the same name could be used by different implementations, causing unexpected behaviors. Implementors should reduce the risk of this by using a company name or code as a prefix for the property. For example, a company called "Acme" might add properties for a hardware error code and a log message. Good names for these would be "AcmeHardwareError" and "AcmeLogMessage", reducing the risk of the same name being used by a different implementation.

Requirements

  • Any additional property not defined by this specification and not recognized by the Service or the Client will be ignored.
  • Ignoring an unknown property will have no effect on the standard behavior of the service or client. There will be no requirement to use undefined additional properties.
  • The service or client may use undefined additional properties for whatever purpose they require. Dependance on undefined additional properties will mean the client or service is non-standard and may impact interoperability.
  • Implementers should pick undefined additional property names to avoid name clashes.

2.4 - Message Types

XFS4IoT supports the following message types.

type Direction Description
command client to Service Message sent to the Service to perform a command.
acknowledge Service to client Message from the Service indicating if the command is valid and queued.
event Service to client Intermediate message from the Service indicating progress of the command.
completion Service to client Message from the Service indicating the command is complete.
unsolicited Service to client Message from the Service unrelated to a command.

2.4.1 - Command Messages

The start of a command will be initiated by the client with a command message, requesting the service performs the specified action. The message uses the standard header properties with type set to command.

The requestId is given by the client and allows the client to link messages sent in response to the command back to the original command. For example, the completion message for this command will contain the same requestId.

The requestId must be greater than or equal to 1 and incremented between each command, 0 is reserved for unsolicited events. The client is responsible for ensuring that each requestId is unique for a single connection. They do not have to be unique across connections. The request is identified by a combination of the requestId and the connection.

The Service will remember the last requestId and reject any requestId for a new command which is lower or equal to the previous requestId. Other than that the service will not track the requestId.

Examples of commands with payloads are shown in the example sequence.

2.4.2 - Acknowledge Messages

As soon as the service has received and decoded the command message it will send an acknowledge message to indicate that the command message has been received and queued. This will normally include the requestId so that the client can identify which command it relates to (unless an error occurs which prevents the requestId being included). The message uses the standard header properties with type set to acknowledge.

Sending the acknowledge message immediately allows the client to handle network errors and lost messages more quickly. It can set a short timeout and expect to receive the acknowledge within that timeout, and continue with error handling if it does not.

Receiving the acknowledge message does not give any guarantees about what the service will do with the command, or even that it can be executed. Any errors will be reported in the completion message for the command, not in the acknowledge.

The only exception is when it would be impossible for the service to send a useful completion message, such as if there's no requestId to include in the completion message. In this small number of cases an error code will be included in the acknowledge message.

The acknowledge message contains the following standard payload properties.

Property Property Type Description
status string One of the status codes listed below. The status codes are intentionally defined to be very simple and not cover all cases. Extra information about exactly what caused a failure can be included in errorDescription non-standard debugging properties in the acknowledge message.
errorDescription string If status is not ok this will give a human readable description of what caused the error. This may include details which help diagnose the cause. The format of this string should not be relied on.

status codes:

  • ok - The command has been accepted for execution and will complete with a completion message.
  • invalidMessage - Message cannot be decoded
  • invalidRequestID - requestId is not greater than 0, or not greater than the previous requestId.
  • tooManyRequests - There are currently too many requests queued by the service and the service cannot queue any more.

Examples of acknowledge messages are shown in the example sequence.

2.4.3 - Event Messages

During the processing of the command the service can send multiple solicited events, as defined in the interface chapters. This is used to inform the client when something significant happens that it may need to react to, like a card being inserted or a key being pressed.

Each solicited event will contain the original requestId in the header, and will only be sent on the connection that the original command was received on, so that individual solicited events can be linked to the original command by the client.

For compatibility with future specification changes, and to permit custom extensions by service implementors, the client should ignore any events that it does not recognize.

Examples of event messages are shown in the example sequence.

2.4.4 - Completion Messages

If a command is accepted, there will be one completion message. If an acknowledge message with an error code is returned to the command message then the command will not be executed, and no completion message will be sent.

The message uses the standard header properties with type set to completion. The completion message will contain the requestId from the original command message, so that the client can link the message back to the command. After the completion message for a command has been sent with a particular requestId, no more messages will be sent with that requestId.

Each completion message will contain as much information as possible to avoid requiring extra events. For example, when a command is used to fetch information from the Service then the information will be included in the completion message. When a command results in particular information, like reading a card, then that information is included in the completion message. The exact information included in each completion message is defined in the interface document that defines that completion message.

Examples of completion messages are shown in the example sequence.

After a command message has been received and associated acknowledge sent, the completion code, either success or an error code, will be included in the completion message for that command. The interface chapter may define command specific error codes that are valid for each completion message. No other error codes will be returned by the service for the completion message.

The completion message payload completionCode property contains one of the values defined in Completion Codes.

When an error occurs, optional vendor specific information may be included in the errorDescription property.

2.4.4.1 - Completion Codes

After a command message has been received and associated acknowledge message sent, the completion code, either success or an error code, will be included in the completion message for that command. The interface specification will define command specific error codes that are valid for each completion message. No other error codes will be returned by the Service for the completion message.

The completion message payload completionCode property contains one of the following values:

  • success - success.
  • commandErrorCode - Check the errorCode property for the command specific error code.
  • canceled - Canceled using the Common.Cancel command.
  • timeOut - Timed out after the client specified timeout.
  • deviceNotReady - The device is not ready or timed out.
  • hardwareError - An error occurred on the device.
  • internalError - An internal inconsistency or other unexpected error occurred.
  • invalidCommand - The command is not supported by the service.
  • invalidRequestID - The requestId is invalid.
  • unsupportedCommand - The command is valid for the interface, but is not supported by the service or device.
  • invalidData - The command message contains invalid data.
  • userError - The user is preventing proper operation of the device.
  • unsupportedData - The command message contains data that is valid for the interface command, but is not supported by the service or device.
  • fraudAttempt - The user is attempting a fraudulent act on the device.
  • sequenceError - The command request is not valid at this time or in the device's current state.
  • authorizationRequired - The command request cannot be performed because it requires authorization.
  • noCommandNonce - The value of the nonce stored in the hardware was cleared, for example by a power failure.
  • invalidToken - The security token is invalid.
  • invalidTokenNonce - The value of the nonce in the security token does not match the stored value.
  • invalidTokenHMAC - The value of the HMAC in the security token is incorrect.
  • invalidTokenFormat - The token format version value is not recognized, or the token format is somehow invalid.
  • invalidTokenKeyNoValue - The key used for the HMAC for a token has not been loaded and the token cannot be validated.

When an error occurs, optional vendor specific information may be included in the errorDescription property.

2.4.5 - Unsolicited Event Messages

The Service will also send unsolicited events to the client to signal events that can happen at any time, independent of command handling. These can happen before, during, or after any command handling. The message uses the standard header properties with type set to unsolicited.

To allow clients to react to events quickly, unsolicited messages should be sent as soon as possible. For example, it should avoid queuing events until after the current command has been processed if it does not have to.

Since unsolicited events are not linked to command handling, they do not have a matching requestId. The event header will contain a requestId of 0. Unsolicited events are also broadcast to all clients, on all open connections.

Each interface chapter defines the unsolicited events relevant to the interface.

For compatibility with future specification changes, and to permit custom extensions by service implementors, the client should ignore any events that it does not recognize.

Examples of unsolicited messages are shown in the example sequence.

2.5 - Command Processing

Once a service has been discovered (see Service Endpoint Discovery) and a connection created the client can send command messages to the service. Commands may cause the service to perform actions that are entirely software based, such as returning the current status, or they may cause actions to be performed by hardware, such as opening a shutter.

The sequence of messages passed between the service and the client is the same for all commands, independent of the command or interface being used.

Services may also send unsolicited events directly to the client. This can happen at any time that the service connection is open. This could be during the processing of a command, or between commands.

The following sections provide information on various topics related to command processing:

  • Standard command processing flow
  • Command queuing
  • Commands cancellation
  • Example flow

2.5.1 - Standard Sequence

The normal command message sequence will be as follows, note this example has multiple solicited and unsolicited events:

GeneratedDiagram

All parts will be passed as standard messages as defined in the Messages section.

2.5.2 - Command Queuing

Some commands can be executed in parallel. For example, a status command that returns the current status can always be executed immediately even if another long running command is being executed. Other commands may be blocked from parallel execution by mechanical or other restraints. For example, it's probably impossible to accept a card and capture a card at the same time on most card readers.

As far as possible, services will attempt to execute commands in parallel. In particular, all commands that simply return information should be executed immediately even if other commands are in progress. It is up to the client to synchronize status information with ongoing actions.

When it's not possible to execute a command immediately then commands will be queued and executed as soon as possible.

The acknowledge message is always sent before the command is queued.

GeneratedDiagram

Queued commands will normally be dequeued and executed in the order received. It is valid to execute queued commands in a different order to that received.

If the condition that caused a command to be queued clears, the command nearest the front of the queue that is blocked by that condition will be dequeued and executed ahead of any other commands nearer the front of the queue.

For example, if while idle, an Encrypting Pin Pad service receives the following command requests in the order listed:

  1. Keyboard.DataEntry
  2. Crypto.CryptoData
  3. Keyboard.PinEntry
  4. Crypto.Digest

The Service executes in parallel the Keyboard.DataEntry and Crypto.CryptoData commands as one uses the Pin Pad and the other uses the encryptor. The Keyboard.PinEntry and Crypto.Digest commands are added to the queue in that order. If the Crypto.CryptoData command completes before the Keyboard.DataEntry command, the service will execute the Crypto.Digest command as the encryptor is available while keeping the Keyboard.PinEntry command on the queue as the Pin Pad is still in use by the Keyboard.DataEntry command.

The order of execution would therefore be:

  1. Keyboard.DataEntry
  2. Crypto.CryptoData
  3. Crypto.Digest
  4. Keyboard.PinEntry

2.5.3 - Cancelation

A client can use the Common.Cancel command to attempt cancelation of one, multiple or all queued or executing commands at any time.

The Common.Cancel command adheres to the standard command message flow. That is, the Client must assign it a unique requestId when sending the command message, and the service will send both acknowledge and completion messages using that requestId. The Service will not send any event messages related to the Common.Cancel command requestId.

The Common.Cancel command can only be used to cancel requests associated with the client connection on which the command is sent. That is, one client cannot cancel another client's requests.

The Common.Cancel command itself cannot be canceled. Similarly, a requestId that does not match a queued or executing command requestId will have no effect.

The Common.Cancel will complete immediately. It will not wait until the completion messages of the specified request(s) have been sent.

Completion of the Common.Cancel command does not imply when the commands requested to cancel will complete. Nor does it imply those commands will be canceled and complete with completionCode of canceled.

Clients should expect that, at some future point, commands may complete with a completionCode other than canceled. For example, device state prevents the command canceling forcing it to complete as if no cancel request had been received.

The Service will always cancel queued commands which have not started executing.

The Service must send completion messages, for any command requests being canceled, after the completion message for the Common.Cancel command has been sent.

The Client should not attempt to cancel any one requestId more than once as it is the responsibility of the Service to maintain the cancel requested state of a command until the command completes. Sending multiple requests to cancel the same command will have no effect.

2.5.4 - Example Command Request Message Sequence

GeneratedDiagram

2.6 - Message Versions

All messages types are assigned version numbers to enable evolution of individual messages. The major version number of a completion message will always be the same as the major version number of the command message it is associated with, however, the minor version numbers can be different.

If a new version of a command message has a property which has an associated capability property, the service must implement, at a minimum, the version of the Common.Capabilities command that includes the associated capability property. This will allow the client to decide whether to use the command message property and the value it should be set to.

Each release of the specification defines the message version numbers of the command, acknowledge, event, completion and unsolicited messages included in that release of the specification. The specification number is different from the message version numbers. If a message definition does not change from one release of the specification to the next, the message version number will remain the same.

2.6.1 - Version Numbers

Message version numbers have the form X.Y where X and Y are non-negative integers, and do not contain leading zeroes. X is the major version and Y is the minor version. The major and minor version numbers are incremented according to the scope of change described in the following sections.

The major version must be greater than 0. If a minor change is made, the minor version is incremented and the major version remains the same. If a major change is made, the major version is incremented and the minor version is reset to 0. For example, 1.1 -> 1.2 -> ... -> 1.10 -> 2.0.

2.6.1.1 - Major Version Numbers

Major version X (X.y) numbers will be incremented in the specification if any backwards incompatible changes are introduced to the command, event, unsolicited or completion messages. It may also include minor level changes.

Major version increments represent a new command, event or unsolicited message. While there will likely be similarities with the previous major version, this is not guaranteed. It is anticipated that given the flexibility of JSON, major version increments will rarely be required.

Major version increments allow:

  • Removal of command message properties.
  • Change of definition of command message properties.
  • Change of definition of completion message properties.
  • Change of definition of event message properties.
  • New event messages which cannot be ignored by the client.

2.6.1.2 - Minor Version Numbers

Minor version Y (x.Y) numbers will be incremented in the specification if new, backwards compatible functionality is introduced to the command, event, completion or unsolicited message. It will also be incremented if any message property is marked as deprecated. It may be incremented if substantial new functionality or improvements are introduced where backwards compatibility is maintained.

Minor version increments allow:

  • Additional command message properties.
  • Additional completion, event and unsolicited message properties.
  • New event messages which can be ignored by the client.

Additional command message properties must be optional. If omitted, the command behavior must be as defined in minor version 0 of the major version of the command message. If included, additional properties may change the behavior of the command. Clients that included additional command message properties that change behavior should therefore handle these behavioral changes.

For additional completion, event and unsolicited message properties, clients should expect that new properties may be added and if not required, ignored. That is, clients should not break because they do not recognize additional properties.

2.6.2 - Version Number Selection

Version number selection occurs after a client connection has been established with the service. By default, the service will for each client connection, use the lowest available major version of each message it supports.

The client is responsible for determining version compatibility. If compatible, the client must inform the service of its version requirements. If incompatible, the client must handle the incompatibilities, possibly by not using incompatible commands. If the client cannot handle the incompatibilities then it should close the connection and not use the service.

The following sequence demonstrates use of the Common.Capabilities command to identify the command and event (both event and unsolicited) versions supported by the service, and the client use of the Common.SetVersions command to inform the service of the versions that should be used for the connection on which the command is sent.

GeneratedDiagram

2.6.3 - Version Evolution Example

The following table depicts an example evolution of a command, an event and an unsolicited event.

Evolution command event completion unsolicited
Initial 1.0
propA
1.0
propA
1.0
propA
1.0
propA
Minor update
- command property added
- completion unchanged
1.1
propA
propB
1.0
propA
1.0
propA
1.0
propA
Minor update
- event property added
1.1
propA
propB
1.1
propA
propB
1.0
propA
1.0
propA
Major update
- completion property removed
- command unchanged
- unsolicited property removed
- unsolicited property added
2.0
propA
propB
1.1
propA
propB
2.0
propB
2.0
propB

2.6.4 - Extending Enumeration Values

Extending an enumeration value is a breaking change as existing clients will not be coded to handle the new enumeration value. A breaking change to a message requires the message major version number be incremented.

Where possible the specification will avoid breaking changes. To support this, if the additional enumeration value is related to an existing enumeration value:

  • An additional property with name originalNameX will be added to the message definition, where originalName is the original name of the property and X is the next available index. Indices will be non-negative integers and start at 2.

  • The message minor version number will be incremented. This indicates the change is backwards compatible.

  • The original property definition will be set as deprecated indicating it may be removed in a subsequent major revision of the message.

  • Service implementations which implement the message version that defines the additional property will, if the original property is required, always include both originalName and originalNameX properties.

Existing clients will be unaffected by the additional property as the original property will still be included in the message. New or updated clients can be written to use any of the previous related properties. If a client does not have a use for a new enumeration value, it can continue to use one of the previously defined related properties.

For example, if version 1.0 of a message defines a device property with enumeration values:

  • online, offline, hardwareError, userError

And a new enumeration value:

  • fraudAttempt

Is added which relates to the existing, less specific, userError value, the new enumeration value could be added to the device2 property in minor increment version 1.1 of the message. In this case when reporting the new enumeration value, version 1.1 of the message will include both:

{
  "device": "userError",
  "device2": "fraudAttempt"
}

2.7 - End to End Security

A key priority for XFS4IoT is to improve security of the entire environment where XFS is used. This means securing not only the interface between the service and the device, or the interface between the client and the service, but providing security all the way from one end of an operation to the other.

For example, during a cash dispense operation, the transaction will first be authorized by an authorizing host which represents the owner of the cash in the device. That host will communicate through various other systems to the client application, the client application will communicate with the XFS4IoT service and the service will finally communicate with the device. Any part of that process is vulnerable to an attack which could lead to the wrong amount of cash being dispensed. XFS4IoT has been designed to block attacks at any point between the authorizing host and the dispenser hardware.

Details of end-to-end (E2E) security are covered in the generic E2E security specification [Ref. api-2] shared between XFS3.x and XFS4IoT. Generic and specific E2E tokens are defined in that specification. The tokens are passed to commands and returned in events which are documented in this specification, such as with CashDispenser.Dispense

There are specific commands to support E2E security which are covered by this specification, including Common.GetCommandNonce and Common.ClearCommandNonce

3 - Service Publisher Interface

This chapter defines the Service Publisher interface functionality and messages.

3.1 - Command Messages

3.1.1 - ServicePublisher.GetServices

Command sent to the service discovery port to identify services exposed by this publisher.

This command can be used while in Vendor Mode.

Command Message

Payload (version 1.0) Type Required
{
"timeout": 5000integer
}
Properties

timeout

Timeout in milliseconds for the command to complete. If set to 0, the command will not timeout but can be canceled.

default: 0

Completion Message

Payload (version 1.0) Type Required
{
"completionCode": "success",string
"errorDescription": "Device not available",string
"vendorName": "ACME ATM Hardware GmbH",string
"services": [{array (object)
"serviceURI": "wss://ATM1:123/xfs4iot/v1.0/CardReader"string
}]
}
Properties

completionCode

The completion code.

errorDescription

If included, this contains additional vendor dependent information to assist with problem resolution.

vendorName

Freeform string naming the hardware vendor.

services

Array of one or more services exposed by the publisher.

services/serviceURI

The URI which can be used to contact this individual service.

Property value constraints:

format: URI

Event Messages

3.2 - Event Messages

3.2.1 - ServicePublisher.ServiceDetailEvent

Details of one or more services published by this endpoint.

Event Message

Payload (version 1.0) Type Required
{
"vendorName": "ACME ATM Hardware GmbH",string
"services": [{array (object)
"serviceURI": "wss://ATM1:123/xfs4iot/v1.0/CardReader"string
}]
}
Properties

vendorName

Freeform string naming the hardware vendor.

services

Array of one or more services exposed by the publisher.

services/serviceURI

The URI which can be used to contact this individual service.

Property value constraints:

format: URI

4 - Common Interface

This chapter defines the Common interface functionality and messages.

4.1 - Command Messages

4.1.1 - Common.Status

This command is used to obtain the overall status of the Service. The status includes common status information and can include zero or more interface specific status objects, depending on the interfaces the Service supports. It may also return vendor-specific status information.

This command can be used while in Vendor Mode.

Command Message

Payload (version 1.0) Type Required
{
"timeout": 5000integer
}
Properties

timeout

Timeout in milliseconds for the command to complete. If set to 0, the command will not timeout but can be canceled.

default: 0

Completion Message

Payload (version 1.0) Type Required
{
"completionCode": "success",string
"errorDescription": "Device not available",string
"common": {object
"device": "online",string
"devicePosition": "inPosition",string
"powerSaveRecoveryTime": 0,integer
"antiFraudModule": "ok",string
"exchange": "notSupported",string
"endToEndSecurity": "enforced"string
},
"cardReader": {object
"media": "notSupported",string
"security": "notSupported",string
"chipPower": "notSupported",string
"chipModule": "ok",string
"magWriteModule": "ok",string
"frontImageModule": "ok",string
"backImageModule": "ok"string
},
"cashAcceptor": {object
"intermediateStacker": "empty",string
"stackerItems": "customerAccess",string
"banknoteReader": "ok",string
"dropBox": false,boolean
"positions": [{array (object)
"position": "inLeft",string
"shutter": "closed",string
"positionStatus": "empty",string
"transport": "ok",string
"transportStatus": "empty"string
}]
},
"cashDispenser": {object
"intermediateStacker": "empty",string
"positions": [{array (object)
"position": "outDefault",string
"shutter": "closed",string
"positionStatus": "empty",string
"transport": "ok",string
"transportStatus": "empty"string
}]
},
"cashManagement": {object
"safeDoor": "doorNotSupported",string
"dispenser": "ok",string
"acceptor": "ok"string
},
"keyManagement": {object
"encryptionState": "ready",string
"certificateState": "unknown"string
},
"keyboard": {object
"autoBeepMode": {object
"activeAvailable": false,boolean
"inactiveAvailable": falseboolean
}
},
"textTerminal": {object
"keyboard": "on",string
"keyLock": "on",string
"displaySizeX": 0,integer
"displaySizeY": 0integer
},
"printer": {object
"media": "notSupported",string
"paper": {object
"upper": "notSupported",string
"lower": "notSupported",string
"external": "notSupported",string
"aux": "notSupported",string
"aux2": "notSupported",string
"park": "notSupported",string
"vendorSpecificPaperSupply": "notSupported"string
},
"toner": "notSupported",string
"ink": "notSupported",string
"lamp": "notSupported",string
"retractBins": [{array (object)
"state": "unknown",string
"count": 0integer
}],
"mediaOnStacker": 0,integer
"paperType": {object
"upper": "unknown",string
"lower": "unknown",string
"external": "unknown",string
"aux": "unknown",string
"aux2": "unknown",string
"park": "unknown",string
"exampleProperty1": "unknown",string
"exampleProperty2": "unknown"string
},
"blackMarkMode": "notSupported"string
},
"barcodeReader": {object
"scanner": "on"string
},
"biometric": {object
"subject": "present",string
"capture": false,boolean
"dataPersistence": "persist",string
"remainingStorage": 0integer
},
"camera": {object
"media": {object
"room": "ok",string
"person": "ok",string
"exitSlot": "ok",string
"exampleProperty1": "ok",string
"exampleProperty2": "ok"string
},
"cameras": {object
"room": "notSupported",string
"person": "notSupported",string
"exitSlot": "notSupported",string
"exampleProperty1": "notSupported",string
"exampleProperty2": "notSupported"string
},
"pictures": {object
"room": 0,integer
"person": 0,integer
"exitSlot": 0,integer
"exampleProperty1": 0,integer
"exampleProperty2": 0integer
}
},
"lights": {object
"cardReader": {object
"position": "left",string
"flashRate": "off",string
"color": "red",string
"direction": "entry"string
},
"pinPad": {object
See cardReader properties.
},
"notesDispenser": {object
See cardReader properties.
},
"coinDispenser": {object
See cardReader properties.
},
"receiptPrinter": {object
See cardReader properties.
},
"passbookPrinter": {object
See cardReader properties.
},
"envelopeDepository": {object
See cardReader properties.
},
"billAcceptor": {object
See cardReader properties.
},
"envelopeDispenser": {object
See cardReader properties.
},
"documentPrinter": {object
See cardReader properties.
},
"coinAcceptor": {object
See cardReader properties.
},
"scanner": {object
See cardReader properties.
},
"contactless": {object
See cardReader properties.
},
"cardReader2": {object
See cardReader properties.
},
"notesDispenser2": {object
See cardReader properties.
},
"billAcceptor2": {object
See cardReader properties.
},
"statusGood": {object
See cardReader properties.
},
"statusWarning": {object
See cardReader properties.
},
"statusBad": {object
See cardReader properties.
},
"statusSupervisor": {object
See cardReader properties.
},
"statusInService": {object
See cardReader properties.
},
"fasciaLight": {object
See cardReader properties.
},
"vendorSpecificLight": {object
See cardReader properties.
}
},
"auxiliaries": {object
"operatorSwitch": "notAvailable",string
"tamperSensor": "notAvailable",string
"internalTamperSensor": "notAvailable",string
"seismicSensor": "notAvailable",string
"heatSensor": "notAvailable",string
"proximitySensor": "notAvailable",string
"ambientLightSensor": "notAvailable",string
"enhancedAudioSensor": "notAvailable",string
"bootSwitchSensor": "notAvailable",string
"displaySensor": "notAvailable",string
"operatorCallButtonSensor": "notAvailable",string
"handsetSensor": "notAvailable",string
"headsetMicrophoneSensor": "notAvailable",string
"fasciaMicrophoneSensor": "notAvailable",string
"safeDoor": "notAvailable",string
"vandalShield": "notAvailable",string
"cabinetFrontDoor": "notAvailable",string
"cabinetRearDoor": "notAvailable",string
"cabinetLeftDoor": "notAvailable",string
"cabinetRightDoor": "notAvailable",string
"openClosedIndicator": "notAvailable",string
"audio": {object
"rate": "on",string
"signal": "keypress"string
},
"heating": "notAvailable",string
"consumerDisplayBacklight": "notAvailable",string
"signageDisplay": "notAvailable",string
"volume": {object
"volumeLevel": 1integer
},
"UPS": {object
"low": false,boolean
"engaged": false,boolean
"powering": false,boolean
"recovered": falseboolean
},
"audibleAlarm": "notAvailable",string
"enhancedAudioControl": "notAvailable",string
"enhancedMicrophoneControl": "notAvailable",string
"microphoneVolume": {object
"available": false,boolean
"volumeLevel": 1integer
}
},
"vendorMode": {object
"device": "online",string
"service": "enterPending"string
},
"vendorApplication": {object
"accessLevel": "notActive"string
}
}
Properties

completionCode

The completion code.

errorDescription

If included, this contains additional vendor dependent information to assist with problem resolution.

common

Status information common to all XFS4IoT services.

common/device

Specifies the state of the device. Following values are possible:

  • online - The device is online. This is returned when the device is present and operational.
  • offline - The device is offline (e.g., the operator has taken the device offline by turning a switch or breaking an interlock).
  • powerOff - The device is powered off or physically not connected.
  • noDevice - The device is not intended to be there, e.g. this type of self service machine does not contain such a device or it is internally not configured.
  • hardwareError - The device is inoperable due to a hardware error.
  • userError - The device is present but a person is preventing proper device operation.
  • deviceBusy - The device is busy and unable to process a command at this time.
  • fraudAttempt - The device is present but is inoperable because it has detected a fraud attempt.
  • potentialFraud - The device has detected a potential fraud attempt and is capable of remaining in service. In this case the application should make the decision as to whether to take the device offline.
  • starting - The device is starting and performing whatever initialization is necessary. This can be reported after the connection is made but before the device is ready to accept commands. This must only be a temporary state, the Service must report a different state as soon as possible. If an error causes initialization to fail then the state should change to hardwareError.

common/devicePosition

Position of the device. Following values are possible:

  • inPosition - The device is in its normal operating position, or is fixed in place and cannot be moved.
  • notInPosition - The device has been removed from its normal operating position.
  • unknown - Due to a hardware error or other condition, the position of the device cannot be determined.

common/powerSaveRecoveryTime

Specifies the actual number of seconds required by the device to resume its normal operational state from the current power saving mode. This value is 0 if either the power saving mode has not been activated or no power save control is supported.

common/antiFraudModule

Specifies the state of the anti-fraud module if available. Following values are possible:

  • ok - Anti-fraud module is in a good state and no foreign device is detected.
  • inoperable - Anti-fraud module is inoperable.
  • deviceDetected - Anti-fraud module detected the presence of a foreign device.
  • unknown - The state of the anti-fraud module cannot be determined.

common/exchange

Specifies the exchange state of the service. Exchange can used to perform a manual replenishment of a device and is entered by Storage.StartExchange and completed by Storage.EndExchange. When the state changes a Common.StatusChangedEvent is posted. Following values are possible:

  • notSupported - Exchange is not supported on this service.
  • active - Exchange is active on this service. Commands which interact with the device may be rejected with an error code as appropriate.
  • inactive - Exchange is not active on this service.

default: "notSupported"

common/endToEndSecurity

Specifies the status of end to end security support on this device.

Also see Common.CapabilityProperties.endToEndSecurity.

  • notSupported - E2E security is not supported by this hardware. Any command can be called without a token.
  • notEnforced - E2E security is supported by this hardware but it is not currently enforced, for example because required keys aren't loaded. It's currently possible to perform E2E commands without a token.
  • notConfigured - E2E security is supported but not correctly configured, for example because required keys aren't loaded. Any attempt to perform any command protected by E2E security will fail.
  • enforced - E2E security is supported and correctly configured. E2E security will be enforced. Calling E2E protected commands will only be possible if a valid token is given.

default: "notSupported"

cardReader

Status information for XFS4IoT services implementing the CardReader interface. This will be omitted if the CardReader interface is not supported.

cardReader/media

Specifies the transport/exit position media state as one of the following values:

  • notSupported - Capability to report media position is not supported by the device (e.g. a typical swipe reader or contactless chip card reader).
  • unknown - The media state cannot be determined with the device in its current state (e.g. the value of device is noDevice, powerOff, offline or hardwareError.
  • present - Media is present in the device, not in the entering position and not jammed. On the latched dip device, this indicates that the card is present in the device and the card is unlatched.
  • notPresent - Media is not present in the device and not at the entering position.
  • jammed - Media is jammed in the device; operator intervention is required.
  • entering - Media is at the entry/exit slot of a motorized device.
  • latched - Media is present and latched in a latched dip card unit. This means the card can be used for chip card dialog.

cardReader/security

Specifies the state of the security module as one of the following:

  • notSupported - No security module is available.
  • notReady - The security module is not ready to process cards or is inoperable.
  • open - The security module is open and ready to process cards.

cardReader/chipPower

Specifies the state of the chip controlled by this service. Depending on the value of capabilities response, this can either be the chip on the currently inserted user card or the chip on a permanently connected chip card. The state of the chip is one of the following:

  • notSupported - Capability to report the state of the chip is not supported by the ID card unit device. This value is returned for contactless chip card readers.
  • unknown - The state of the chip cannot be determined with the device in its current state.
  • online - The chip is present, powered on and online (i.e. operational, not busy processing a request and not in an error state).
  • busy - The chip is present, powered on, and busy (unable to process a command at this time).
  • poweredOff - The chip is present, but powered off (i.e. not contacted).
  • noDevice - A card is currently present in the device, but has no chip.
  • hardwareError - The chip is present, but inoperable due to a hardware error that prevents it from being used (e.g. MUTE, if there is an unresponsive card in the reader).
  • noCard - There is no card in the device.

cardReader/chipModule

Specifies the state of the chip card module reader as one of the following:

  • ok - The chip card module is in a good state.
  • inoperable - The chip card module is inoperable.
  • unknown - The state of the chip card module cannot be determined.
  • notSupported - Reporting the chip card module status is not supported.

cardReader/magWriteModule

Specifies the state of the magnetic card writer as one of the following:

  • ok - The magnetic card writing module is in a good state.
  • inoperable - The magnetic card writing module is inoperable.
  • unknown - The state of the magnetic card writing module cannot be determined.
  • notSupported - Reporting the magnetic card writing module status is not supported.

cardReader/frontImageModule

Specifies the state of the front image reader as one of the following:

  • ok - The front image reading module is in a good state.
  • inoperable - The front image reading module is inoperable.
  • unknown - The state of the front image reading module cannot be determined.
  • notSupported - Reporting the front image reading module status is not supported.

cardReader/backImageModule

Specifies the state of the back image reader as one of the following:

  • ok - The back image reading module is in a good state.
  • inoperable - The back image reading module is inoperable.
  • unknown - The state of the back image reading module cannot be determined.
  • notSupported - Reporting the back image reading module status is not supported.

cashAcceptor

Status information for XFS4IoT services implementing the CashAcceptor interface. This will be omitted if the CashAcceptor interface is not supported.

cashAcceptor/intermediateStacker

Supplies the state of the intermediate stacker. The following values are possible:

  • empty - The intermediate stacker is empty.
  • notEmpty - The intermediate stacker is not empty.
  • full - The intermediate stacker is full. This may also be reported during a cash-in transaction where a limit specified by CashAcceptor.CashInStart has been reached.
  • unknown - Due to a hardware error or other condition, the state of the intermediate stacker cannot be determined.
  • notSupported - The physical device has no intermediate stacker.

cashAcceptor/stackerItems

This field informs the application whether items on the intermediate stacker have been in customer access. The following values are possible:

  • customerAccess - Items on the intermediate stacker have been in customer access. If the device is a cash recycler then the items on the intermediate stacker may be there as a result of a previous cash-out operation.
  • noCustomerAccess - Items on the intermediate stacker have not been in customer access.
  • accessUnknown - It is not known if the items on the intermediate stacker have been in customer access.
  • noItems - There are no items on the intermediate stacker or the physical device has no intermediate stacker.

cashAcceptor/banknoteReader

Supplies the state of the banknote reader. The following values are possible:

  • ok - The banknote reader is in a good state.
  • inoperable - The banknote reader is inoperable.
  • unknown - Due to a hardware error or other condition, the state of the banknote reader cannot be determined.
  • notSupported - The physical device has no banknote reader.

cashAcceptor/dropBox

The drop box is an area within the Cash Acceptor where items which have caused a problem during an operation are stored. This field specifies the status of the drop box. If true, some items are stored in the drop box due to a cash-in transaction which caused a problem. If false, the drop box is empty or there is no drop box.

cashAcceptor/positions

Array of structures reporting status for each position from which items can be accepted.

cashAcceptor/positions/position

Supplies the input or output position as one of the following values. If not specified, the default position applies. Supported positions are reported in Common.Capabilities.

  • inDefault - Default input position.
  • inLeft - Left input position.
  • inRight - Right input position.
  • inCenter - Center input position.
  • inTop - Top input position.
  • inBottom - Bottom input position.
  • inFront - Front input position.
  • inRear - Rear input position.
  • outDefault - Default output position.
  • outLeft - Left output position.
  • outRight - Right output position.
  • outCenter - Center output position.
  • outTop - Top output position.
  • outBottom - Bottom output position.
  • outFront - Front output position.
  • outRear - Rear output position.

cashAcceptor/positions/shutter

Supplies the state of the shutter. The following values are possible:

  • closed - The shutter is operational and is fully closed.
  • open - The shutter is operational and is open.
  • jammedOpen - The shutter is jammed, but fully open. It is not operational.
  • jammedPartiallyOpen - The shutter is jammed, but partially open. It is not operational.
  • jammedClosed - The shutter is jammed, but fully closed. It is not operational.
  • jammedUnknown - The shutter is jammed, but its position is unknown. It is not operational.
  • unknown - Due to a hardware error or other condition, the state of the shutter cannot be determined.
  • notSupported - The physical device has no shutter or shutter state reporting is not supported.

cashAcceptor/positions/positionStatus

The status of the input or output position. The following values are possible:

  • empty - The position is empty.
  • notEmpty - The position is not empty.
  • unknown - Due to a hardware error or other condition, the state of the position cannot be determined.
  • notSupported - The device is not capable of reporting whether items are at the position.

cashAcceptor/positions/transport

Supplies the state of the transport mechanism. The transport is defined as any area leading to or from the position. The following values are possible:

  • ok - The transport is in a good state.
  • inoperative - The transport is inoperative due to a hardware failure or media jam.
  • unknown - Due to a hardware error or other condition the state of the transport cannot be determined.
  • notSupported - The physical device has no transport or transport state reporting is not supported.

cashAcceptor/positions/transportStatus

Returns information regarding items which may be on the transport. If the device is a recycler device it is possible that the transport will not be empty due to a previous dispense operation. The following values are possible:

  • empty - The transport is empty.
  • notEmpty - The transport is not empty.
  • notEmptyCustomer - Items which a customer has had access to are on the transport.
  • unknown - Due to a hardware error or other condition it is not known whether there are items on the transport.
  • notSupported - The device is not capable of reporting whether items are on the transport.

cashDispenser

Status information for XFS4IoT services implementing the CashDispenser interface. This will be omitted if the CashDispenser interface is not supported.

cashDispenser/intermediateStacker

Supplies the state of the intermediate stacker. These bills are typically present on the intermediate stacker as a result of a retract operation or because a dispense has been performed without a subsequent present. Following values are possible:

  • empty - The intermediate stacker is empty.
  • notEmpty - The intermediate stacker is not empty. The items have not been in customer access.
  • notEmptyCustomer - The intermediate stacker is not empty. The items have been in customer access. If the device is a recycler then the items on the intermediate stacker may be there as a result of a previous cash-in operation.
  • notEmptyUnknown - The intermediate stacker is not empty. It is not known if the items have been in customer access.
  • unknown - Due to a hardware error or other condition, the state of the intermediate stacker cannot be determined.
  • notSupported - The physical device has no intermediate stacker.

cashDispenser/positions

Array of structures for each position to which items can be dispensed or presented.

cashDispenser/positions/position

Supplies the output position as one of the following values. Supported positions are reported in Common.Capabilities.

  • outDefault - Default output position.
  • outLeft - Left output position.
  • outRight - Right output position.
  • outCenter - Center output position.
  • outTop - Top output position.
  • outBottom - Bottom output position.
  • outFront - Front output position.
  • outRear - Rear output position.

default: "outDefault"

cashDispenser/positions/shutter

Supplies the state of the shutter. Following values are possible:

  • closed - The shutter is operational and is closed.
  • open - The shutter is operational and is open.
  • jammedOpen - The shutter is jammed, but fully open. It is not operational.
  • jammedPartiallyOpen - The shutter is jammed, but partially open. It is not operational.
  • jammedClosed - The shutter is jammed, but fully closed. It is not operational.
  • jammedUnknown - The shutter is jammed, but its position is unknown. It is not operational.
  • unknown - Due to a hardware error or other condition, the state of the shutter cannot be determined.
  • notSupported - The physical device has no shutter or shutter state reporting is not supported.

cashDispenser/positions/positionStatus

Returns information regarding items which may be at the output position. If the device is a recycler it is possible that the output position will not be empty due to a previous cash-in operation. Following values are possible:

  • empty - The position is empty.
  • notEmpty - The position is not empty.
  • unknown - Due to a hardware error or other condition, the state of the position cannot be determined.
  • notSupported - The device is not capable of reporting whether items are at the position.

cashDispenser/positions/transport

Supplies the state of the transport mechanism. The transport is defined as any area leading to or from the position. Following values are possible:

  • ok - The transport is in a good state.
  • inoperative - The transport is inoperative due to a hardware failure or media jam.
  • unknown - Due to a hardware error or other condition the state of the transport cannot be determined.
  • notSupported - The physical device has no transport or transport state reporting is not supported.

cashDispenser/positions/transportStatus

Returns information regarding items which may be on the transport. If the device is a recycler device it is possible that the transport will not be empty due to a previous cash-in operation. Following values are possible:

  • empty - The transport is empty.
  • notEmpty - The transport is not empty.
  • notEmptyCustomer - Items which a customer has had access to are on the transport.
  • unknown - Due to a hardware error or other condition it is not known whether there are items on the transport.
  • notSupported - The device is not capable of reporting whether items are on the transport.

cashManagement

Status information for XFS4IoT services implementing the CashManagement interface. This will be omitted if the CashManagement interface is not supported.

cashManagement/safeDoor

Supplies the state of the safe door. Following values are possible:

  • doorNotSupported - Physical device has no safe door or safe door state reporting is not supported.
  • doorOpen - Safe door is open.
  • doorClosed - Safe door is closed.
  • doorUnknown - Due to a hardware error or other condition, the state of the safe door cannot be determined.

cashManagement/dispenser

Supplies the state of the storage units for dispensing cash. Following values are possible:

  • ok - All storage units present are in a good state.
  • attention - One or more of the storage units is in a low, empty, inoperative or manipulated condition. Items can still be dispensed from at least one of the storage units.
  • stop - Due to a storage unit failure dispensing is impossible. No items can be dispensed because all of the storage units are empty, missing, inoperative or in a manipulated condition. This state may also occur when a reject/retract storage unit is full or no reject/retract storage unit is present, or when an application lock is set on every storage unit which can be locked.
  • unknown - Due to a hardware error or other condition, the state of the storage units cannot be determined.

cashManagement/acceptor

Supplies the state of the storage units for accepting cash. Following values are possible:

  • ok - All storage units present are in a good state.
  • attention - One or more of the storage units is in a high, full, inoperative or manipulated condition. Items can still be accepted into at least one of the storage units.
  • stop - Due to a storage unit failure accepting is impossible. No items can be accepted because all of the storage units are in a full, inoperative or manipulated condition. This state may also occur when a retract storage unit is full or no retract storage unit is present, or when an application lock is set on every storage unit, or when counterfeit or suspect items are to be automatically retained within storage units, but all of the designated storage units for storing them are full or inoperative.
  • unknown - Due to a hardware error or other condition, the state of the storage units cannot be determined.

keyManagement

Status information for XFS4IoT services implementing the KeyManagement interface. This will be omitted if the KeyManagement interface is not supported.

keyManagement/encryptionState

Specifies the state of the encryption module.

keyManagement/certificateState

Specifies the state of the public verification or encryption key in the PIN certificate modules.

keyboard

Status information for XFS4IoT services implementing the Keyboard interface. This will be omitted if the Keyboard interface is not supported.

keyboard/autoBeepMode

Specifies whether automatic beep tone on key press is active or not. Active and inactive key beeping is reported independently.

keyboard/autoBeepMode/activeAvailable

Specifies whether an automatic tone will be generated for all active keys.

default: false

keyboard/autoBeepMode/inactiveAvailable

Specifies whether an automatic tone will be generated for all inactive keys.

default: false

textTerminal

Status information for XFS4IoT services implementing the TextTerminal interface. This will be omitted if the TextTerminal interface is not supported.

textTerminal/keyboard

Specifies the state of the keyboard in the text terminal unit as one of the following values:

  • on - The keyboard is activated.
  • off - The keyboard is not activated.
  • notAvailable - The keyboard is not available.

textTerminal/keyLock

Specifies the state of the keyboard lock of the text terminal unit as one of the following values:

  • on - The keyboard lock switch is activated.
  • off - The keyboard lock switch is not activated.
  • notAvailable - The keyboard lock switch is not available.

textTerminal/displaySizeX

Specifies the horizontal size of the display of the text terminal unit (the number of columns that can be displayed).

Property value constraints:

minimum: 0

textTerminal/displaySizeY

Specifies the vertical size of the display of the text terminal unit (the number of rows that can be displayed).

Property value constraints:

minimum: 0

printer

Status information for XFS4IoT services implementing the Printer interface. This will be omitted if the Printer interface is not supported.

printer/media

Specifies the state of the print media (i.e. receipt, statement, passbook, etc.) as one of the following values. This field does not apply to journal printers:

  • notSupported - The capability to report the state of the print media is not supported by the device.
  • unknown - The state of the print media cannot be determined with the device in its current state.
  • present - Media is in the print position, on the stacker or on the transport (i.e. a passbook in the parking station is not considered to be present). On devices with continuous paper supplies, this value is set when paper is under the print head. On devices with no supply or individual sheet supplies, this value is set when paper/media is successfully inserted/loaded.
  • notPresent - Media is not in the print position or on the stacker.
  • jammed - Media is jammed in the device.
  • entering - Media is at the entry/exit slot of the device.
  • retracted - Media was retracted during the last command which controlled media.

printer/paper

Specifies the state of paper supplies as one of the following values. Omitted if not applicable:

  • unknown - Status cannot be determined with device in its current state.
  • full - The paper supply is full.
  • low - The paper supply is low.
  • out - The paper supply is empty.
  • jammed - The paper supply is jammed.

printer/paper/upper

The state of the upper paper supply.

printer/paper/lower

The state of the lower paper supply.

printer/paper/external

The state of the external paper supply.

printer/paper/aux

The state of the auxiliary paper supply.

printer/paper/aux2

The state of the second auxiliary paper supply.

printer/paper/park

The state of the parking station paper supply.

printer/paper/vendorSpecificPaperSupply (example name)

printer/toner

Specifies the state of the toner or ink supply or the state of the ribbon as one of the following:

  • notSupported - Capability not supported by device.
  • unknown - Status of toner or ink supply or the ribbon cannot be determined with device in its current state.
  • full - The toner or ink supply is full or the ribbon is OK.
  • low - The toner or ink supply is low or the print contrast with a ribbon is weak.
  • out - The toner or ink supply is empty or the print contrast with a ribbon is not sufficient any more.

printer/ink

Specifies the status of the stamping ink in the printer as one of the following values:

  • notSupported - Capability not supported by device.
  • unknown - Status of the stamping ink supply cannot be determined with device in its current state.
  • full - Ink supply in device is full.
  • low - Ink supply in device is low.
  • out - Ink supply in device is empty.

printer/lamp

Specifies the status of the printer imaging lamp as one of the following values:

  • notSupported - Capability not supported by device.
  • unknown - Status of the imaging lamp cannot be determined with device in its current state.
  • ok - The lamp is OK.
  • fading - The lamp should be changed.
  • inop - The lamp is inoperative.

printer/retractBins

An array of bin state objects. If no retain bins are supported, the array will be empty.

printer/retractBins/state

Specifies the state of the printer retract bin as one of the following:

  • ok - The retract bin of the printer is in a healthy state.
  • full - The retract bin of the printer is full.
  • unknown - Status cannot be determined with device in its current state.
  • high - The retract bin of the printer is nearly full.
  • missing - The retract bin is missing.

printer/retractBins/count

The number of media retracted to this bin. This value is persistent; it may be reset to 0 by the Printer.ResetCount command.

Property value constraints:

minimum: 0

printer/mediaOnStacker

The number of media on stacker; applicable only to printers with stacking capability.

printer/paperType

Specifies the type of paper loaded as one of the following:

  • unknown - No paper is loaded, reporting of this paper type is not supported or the paper type cannot be determined.
  • single - The paper can be printed on only one side.
  • dual - The paper can be printed on both sides.

printer/paperType/upper

The upper paper supply paper type.

printer/paperType/lower

The lower paper supply paper type.

printer/paperType/external

The external paper supply paper type.

printer/paperType/aux

The auxililliary paper supply paper type.

printer/paperType/aux2

The second auxililliary paper supply paper type.

printer/paperType/park

The parking station paper supply paper type.

printer/paperType/exampleProperty1 (example name)

printer/blackMarkMode

Specifies the status of the black mark detection and associated functionality:

  • notSupported - Black mark detection is not supported.
  • unknown - The status of the black mark detection cannot be determined.
  • on - Black mark detection and associated functionality is switched on.
  • off - Black mark detection and associated functionality is switched off.

barcodeReader

Status information for XFS4IoT services implementing the Barcode Reader interface. This will be omitted if the Barcode Reader interface is not supported.

barcodeReader/scanner

Specifies the scanner status (laser, camera or other technology) as one of the following:

  • on - Scanner is enabled for reading.
  • off - Scanner is disabled.
  • inoperative - Scanner is inoperative due to a hardware error.
  • unknown - Scanner status cannot be determined.

biometric

Status information for XFS4IoT services implementing the Biometrics interface. This will be omitted if the Biometrics interface is not supported.

biometric/subject

Specifies the state of the subject to be scanned (e.g. finger, palm, retina, etc) as one of the following values:

  • present - The subject to be scanned is on the scanning position.
  • notPresent - The subject to be scanned is not on the scanning position.
  • unknown - The subject to be scanned cannot be determined with the device in its current state (e.g. the value of device is noDevice, powerOff, offline, or hwError).
  • notSupported - The physical device does not support the ability to report whether a subject is on the scanning position.

biometric/capture

Indicates whether or not scanned biometric data has been captured using the Biometric.Read and is currently stored and ready for comparison. true if data has been captured and is stored, false if no scanned data is present. This will be set to false when scanned data is cleared using the Biometric.Clear.

biometric/dataPersistence

Specifies the current data persistence mode. The data persistence mode controls how biometric data that has been captured using the Biometric.Read will be handled. The following values are possible:

  • persist - Biometric data captured using the Biometric.Read can persist until all sessions are closed, the device is power failed or rebooted, or the Biometric.Read is requested again. This captured biometric data can also be explicitly cleared using the Biometric.Clear or Biometric.Reset.
  • clear - Captured biometric data will not persist. Once the data has been either returned in the Biometric.Read or used by the Biometric.Match, then the data is cleared from the device.

biometric/remainingStorage

Specifies how much of the reserved storage specified by the templateStorage capability is remaining for the storage of templates in bytes. if omitted, this property is not supported.

Property value constraints:

minimum: 0

camera

Status information for XFS4IoT services implementing the Camera interface. This will be omitted if the Camera interface is not supported.

camera/media

Specifies the state of the recording media of the cameras as one of the following. For a device which stores pictures on a hard disk drive or other general-purpose storage, this will be notSupported.

  • ok - The media is in a good state.
  • high - The media is almost full (threshold).
  • full - The media is full.
  • notSupported - The device does not support sensing the media level.
  • unknown - Due to a hardware error or other condition, the state of the media cannot be determined.

camera/media/room

Specifies the state of the recording media of the camera that monitors the whole self-service area.

camera/media/person

Specifies the state of the recording media of the camera that monitors the person standing in front of the self-service machine.

camera/media/exitSlot

Specifies the state of the recording media of the camera that monitors the exit slot(s) of the self-service machine.

camera/media/exampleProperty1 (example name)

camera/cameras

Specifies the state of the cameras as one of the following.

  • notSupported - The camera is not supported.
  • ok - The camera is in a good state.
  • inoperative - The camera is inoperative.
  • unknown - Due to a hardware error or other condition, the state of the camera cannot be determined.

camera/cameras/room

Specifies the state of the camera that monitors the whole self-service area.

camera/cameras/person

Specifies the state of the camera that monitors the person standing in front of the self-service machine.

camera/cameras/exitSlot

Specifies the state of the camera that monitors the exit slot(s) of the self-service machine.

camera/cameras/exampleProperty1 (example name)

camera/pictures

Specifies the number of pictures stored on the recording media of the cameras. For a device which stores pictures on a hard disk drive or other general-purpose storage, the value of the property should be 0.

camera/pictures/room

Specifies the number of pictures stored on the recording media of the room camera.

Property value constraints:

minimum: 0

camera/pictures/person

Specifies the number of pictures stored on the recording media of the person camera.

Property value constraints:

minimum: 0

camera/pictures/exitSlot

Specifies the number of pictures stored on the recording media of the exit slot camera.

Property value constraints:

minimum: 0

camera/pictures/exampleProperty1 (example name)

Property value constraints:

minimum: 0

lights

Status information for XFS4IoT services implementing the Lights interface. This will be omitted if the Lights interface is not supported.

lights/cardReader

Card Reader Light.

lights/cardReader/position

The light position. Can be used for devices which have multiple input and output positions, omitted if not required. One of the following values:

  • left - The left position.
  • right - The right position.
  • center - The center position.
  • top - The top position.
  • bottom - The bottom position.
  • front - The front position.
  • rear - The rear position.

lights/cardReader/flashRate

The light flash rate as one of the following values:

  • off - The light is turned off.
  • slow - The light is flashing slowly.
  • medium - The light is flashing medium frequency.
  • quick - The light is flashing quickly.
  • continuous - The light is continuous (steady).

lights/cardReader/color

The light color as one of the following values:

  • red - The light is red.
  • green - The light is green.
  • yellow - The light is yellow.
  • blue - The light is blue.
  • cyan - The light is cyan.
  • magenta - The light is magenta.
  • white - The light is white.

lights/cardReader/direction

The light direction as one of the following values:

  • entry - The light is indicating entry.
  • exit - The light is indicating exit.

lights/pinPad

Pin Pad Light.

lights/notesDispenser

Notes Dispenser Light.

lights/coinDispenser

Coin Dispenser Light.

lights/receiptPrinter

Receipt Printer Light.

lights/passbookPrinter

Passbook Printer Light.

lights/envelopeDepository

Envelope Depository Light.

lights/billAcceptor

Bill Acceptor Light.

lights/envelopeDispenser

Envelope Dispenser Light.

lights/documentPrinter

Document Printer Light.

lights/coinAcceptor

Coin Acceptor Light.

lights/scanner

Scanner Light.

lights/contactless

Contactless Reader Light.

lights/cardReader2

Card Reader 2 Light.

lights/notesDispenser2

Notes Dispenser 2 Light.

lights/billAcceptor2

Bill Acceptor 2 Light.

lights/statusGood

Status Indicator light - Good.

lights/statusWarning

Status Indicator light - Warning.

lights/statusBad

Status Indicator light - Bad.

lights/statusSupervisor

Status Indicator light - Supervisor.

lights/statusInService

Status Indicator light - In Service.

lights/fasciaLight

Fascia Light.

lights/vendorSpecificLight (example name)

Additional vendor specific lights

auxiliaries

Status information for XFS4IoT services implementing the Auxiliaries interface. This will be omitted if the Auxiliaries interface is not supported.

auxiliaries/operatorSwitch

Specifies the state of the Operator switch.

  • notAvailable - The status is not available.
  • run - The switch is in run mode.
  • maintenance - The switch is in maintenance mode.
  • supervisor - The switch is in supervisor mode.

auxiliaries/tamperSensor

Specifies the state of the Tamper sensor.

  • notAvailable - The status is not available.
  • off - There is no indication of a tampering attempt.
  • on - There has been a tampering attempt.

auxiliaries/internalTamperSensor

Specifies the state of the Internal Tamper Sensor for the internal alarm. This sensor indicates whether the internal alarm has been tampered with (such as a burglar attempt). Specified as one of the following:

  • notAvailable - The status is not available.
  • off - There is no indication of a tampering attempt.
  • on - There has been a tampering attempt.

auxiliaries/seismicSensor

Specifies the state of the Seismic Sensor. This sensor indicates whether the terminal has been shaken (e.g. burglar attempt or seismic activity). Specified as one of the following:

  • notAvailable - The status is not available.
  • off - The seismic activity has not been high enough to trigger the sensor.
  • on - The seismic or other activity has triggered the sensor.

auxiliaries/heatSensor

Specifies the state of the Heat Sensor. This sensor is triggered by excessive heat (fire) near the terminal. Specified as one of the following:

  • notAvailable - The status is not available.
  • off - The heat has not been high enough to trigger the sensor.
  • on - The heat has been high enough to trigger the sensor.

auxiliaries/proximitySensor

Specifies the state of the Proximity Sensor. This sensor is triggered by movements around the terminal. Specified as one of the following:

  • notAvailable - The status is not available.
  • present - The sensor is showing that there is someone present at the terminal.
  • notPresent - The sensor can not sense any people around the terminal.

auxiliaries/ambientLightSensor

Specifies the state of the Ambient Light Sensor. This sensor indicates the level of ambient light around the terminal. Interpretation of this value is vendor-specific and therefore it is not guaranteed to report a consistent actual ambient light level across different vendor hardware. Specified as one of the following:

  • notAvailable - The status is not available.
  • veryDark - The level of light is very dark.
  • dark - The level of light is dark.
  • mediumLight - The level of light is medium light.
  • light - The level of light is light.
  • veryLight - The level of light is very light.

auxiliaries/enhancedAudioSensor

Specifies the presence or absence of a consumer’s headphone connected to the Audio Jack. Specified as one of the following:

  • notAvailable - The status is not available.
  • present - There is a headset connected.
  • notPresent - There is no headset connected.

auxiliaries/bootSwitchSensor

Specifies the state of the Boot Switch Sensor. This sensor is triggered whenever the terminal is about to be rebooted or shutdown due to a delayed effect switch. Specified as one of the following:

  • notAvailable - The status is not available.
  • off - The sensor has not been triggered.
  • on - The terminal is about to be rebooted or shutdown.

auxiliaries/displaySensor

Specifies the state of the Consumer Display. Specified as one of the following:

  • notAvailable - The status is not available.
  • off - The Consumer Display is switched off.
  • on - The Consumer Display is in a good state and is turned on.
  • displayError - The Consumer Display is in an error state.

auxiliaries/operatorCallButtonSensor

Specifies the state of the Operator Call Button as one of the following:

  • notAvailable - The status is not available.
  • off - The Operator Call Button is released (not pressed).
  • on - The Operator Call Button is being pressed.

auxiliaries/handsetSensor

Specifies the state of the Handset, which is a device similar to a telephone receiver. Specified as one of the following:

  • notAvailable - The status is not available.
  • onTheHook - The Handset is on the hook.
  • offTheHook - The Handset is off the hook.

auxiliaries/headsetMicrophoneSensor

Specifies the presence or absence of a consumer’s headset microphone connected to the Microphone Jack. Specified as one of the following:

  • notAvailable - The status is not available.
  • present - There is a headset microphone connected.
  • notPresent - There is no headset microphone connected.

auxiliaries/fasciaMicrophoneSensor

Specifies the state of the fascia microphone as one of the following:

  • notAvailable - The status is not available.
  • off - The Fascia Microphone is turned off.
  • on - The Fascia Microphone is turned on.

auxiliaries/safeDoor

Specifies the state of the Safe Doors. Safe Doors are doors that open up for secure hardware, such as the note dispenser, the security device, etc. Specified as one of the following:

  • notAvailable - The status is not available.
  • closed - The Safe Doors are closed.
  • open - At least one of the Safe Doors is open.
  • locked - All Safe Doors are closed and locked.
  • bolted - All Safe Doors are closed, locked and bolted.
  • tampered - At least one of the Safe Doors has potentially been tampered with.

auxiliaries/vandalShield

Specifies the state of the Vandal Shield. The Vandal Shield is a door that opens up for consumer access to the terminal. Specified as one of the following:

  • notAvailable - The status is not available.
  • closed - The Vandal Shield is closed.
  • open - The Vandal Shield is fully open.
  • locked - The Vandal Shield is closed and locked.
  • service - The Vandal Shield is in service position.
  • keyboard - The Vandal Shield position permits access to the keyboard.
  • partiallyOpen - The Vandal Shield is partially open.
  • jammed - The Vandal Shield is jammed.
  • tampered - The Vandal Shield has potentially been tampered with.

auxiliaries/cabinetFrontDoor

Specifies the overall state of the Front Cabinet Doors. The front is defined as the side facing the customer/consumer. Cabinet Doors are doors that open up for consumables, and hardware that does not have to be in a secure place. Specified as one of the following:

  • notAvailable - The status is not available.
  • closed - All front Cabinet Doors are closed.
  • open - At least one of the front Cabinet Doors is open.
  • locked - All front Cabinet Doors are closed and locked.
  • bolted - All front Cabinet Doors are closed, locked and bolted.
  • tampered - At least one of the front Cabinet Doors has potentially been tampered with.

auxiliaries/cabinetRearDoor

Specifies the overall state of the Rear Cabinet Doors. The rear is defined as the side opposite the side facing the customer/consumer. Cabinet Doors are doors that open up for consumables, and hardware that does not have to be in a secure place. Specified as one of the following:

  • notAvailable - The status is not available.
  • closed - All rear Cabinet Doors are closed.
  • open - At least one of the rear Cabinet Doors is open.
  • locked - All rear Cabinet Doors are closed and locked.
  • bolted - All rear Cabinet Doors are closed, locked and bolted.
  • tampered - At least one of the rear Cabinet Doors has potentially been tampered with.

auxiliaries/cabinetLeftDoor

Specifies the overall state of the Left Cabinet Doors. The left is defined as the side to the left as seen by the customer/consumer. Cabinet Doors are doors that open up for consumables, and hardware that does not have to be in a secure place. Specified as one of the following:

  • notAvailable - The status is not available.
  • closed - All left Cabinet Doors are closed.
  • open - At least one of the left Cabinet Doors is open.
  • locked - All left Cabinet Doors are closed and locked.
  • bolted - All left Cabinet Doors are closed, locked and bolted.
  • tampered - At least one of the left Cabinet Doors has potentially been tampered with.

auxiliaries/cabinetRightDoor

Specifies the overall state of the Right Cabinet Doors. The right is defined as the side to the right as seen by the customer/consumer. Cabinet Doors are doors that open up for consumables, and hardware that does not have to be in a secure place. Specified as one of the following:

  • notAvailable - The status is not available.
  • closed - All right Cabinet Doors are closed.
  • open - At least one of the right Cabinet Doors is open.
  • locked - All right Cabinet Doors are closed and locked.
  • bolted - All right Cabinet Doors are closed, locked and bolted.
  • tampered - At least one of the right Cabinet Doors has potentially been tampered with.

auxiliaries/openClosedIndicator

Specifies the state of the Open/Closed Indicator as one of the following:

  • notAvailable - The status is not available.
  • closed - The terminal is closed for a consumer.
  • open - The terminal is open to be used by a consumer.

auxiliaries/audio

Specifies the state of the Audio Indicator.

auxiliaries/audio/rate

Specifies the state of the Audio Indicator as one of the following values:

  • on - Turn on the Audio Indicator.
  • off - Turn off the Audio Indicator.
  • continuous - Turn the Audio Indicator to continuous.

auxiliaries/audio/signal

Specifies the Audio sound as one of the following values:

  • keypress - Sound a key click signal.
  • exclamation - Sound an exclamation signal.
  • warning - Sound a warning signal.
  • error - Sound an error signal.
  • critical - Sound a critical error signal.

auxiliaries/heating

Specifies the state of the internal heating as one of the following:

  • notAvailable - The status is not available.
  • off - The internal heating is turned off.
  • on - The internal heating is turned on.

auxiliaries/consumerDisplayBacklight

Specifies the Consumer Display Backlight as one of the following:

  • notAvailable - The status is not available.
  • off - The Consumer Display Backlight is turned off.
  • on - Consumer Display Backlight is turned on.

auxiliaries/signageDisplay

Specifies the state of the Signage Display. The Signage Display is a lighted banner or marquee that can be used to display information or an advertisement. Any dynamic data displayed must be loaded by a means external to the Service. Specified as one of the following:

  • notAvailable - The status is not available.
  • off - The Signage Display is turned off.
  • on - The Signage Display is turned on.

auxiliaries/volume

Specifies the state of the volume control. Omitted if not available.

auxiliaries/volume/volumeLevel

Specifies the value of the Volume Control, if available. The value of Volume Control is defined in an interval from 1 to 1000 where 1 is the lowest volume level and 1000 is the highest volume level. The interval is defined in logarithmic steps, e.g. a volume control on a radio. Note: The Volume Control property is vendor-specific and therefore it is not possible to guarantee a consistent actual volume level across different vendor hardware.

Property value constraints:

minimum: 1
maximum: 1000

auxiliaries/UPS

Specifies the state of the Uninterruptible Power Supply. Omitted if the status is not available.

  • low - The charge level of the UPS is low.
  • engaged - The UPS is engaged.
  • powering - The UPS is powering the system.
  • recovered - The UPS was engaged when the main power went off.

auxiliaries/UPS/low

default: false

auxiliaries/UPS/engaged

default: false

auxiliaries/UPS/powering

default: false

auxiliaries/UPS/recovered

default: false

auxiliaries/audibleAlarm

Species the state of the Audible Alarm device as one of the following:

  • notAvailable - The status is not available.
  • off - The Alarm is turned off.
  • on - The Alarm is turned on.

auxiliaries/enhancedAudioControl

Specifies the state of the Enhanced Audio Controller. The Enhanced Audio Controller controls how private and public audio are broadcast when the headset is inserted into/removed from the audio jack and when the handset is off-hook/on-hook. In the following, Privacy Device is used to refer to either the headset or handset. The Enhanced Audio Controller state is specified as one of the following:

  • notAvailable - The status is not available.
  • publicAudioManual - The Enhanced Audio Controller is in manual mode and is in the public state (i.e. audio will be played through speakers). Activating a Privacy Device (headset connected/handset off-hook) will have no impact, i.e. Output will remain through the speakers & no audio will be directed to the Privacy Device.
  • publicAudioAuto - The Enhanced Audio Controller is in auto mode and is in the public state (i.e. audio will be played through speakers). When a Privacy Device is activated, the device will go to the private state.
  • publicAudioSemiAuto - The Enhanced Audio Controller is in semi-auto mode and is in the public state (i.e. audio will be played through speakers). When a Privacy Device is activated, the device will go to the private state.
  • privateAudioManual - The Enhanced Audio Controller is in manual mode and is in the private state (i.e. audio will be played only through a connected Privacy Device). In private mode, no audio is transmitted through the speakers.
  • privateAudioAuto - The Enhanced Audio Controller is in auto mode and is in the private state (i.e. audio will be played only through a connected Privacy Device). In private mode, no audio is transmitted through the speakers. When a Privacy Device is deactivated (headset disconnected/handset on-hook), the device will go to the public state. Where there is more than one Privacy Device, the device will go to the public state only when all Privacy Devices have been deactivated.
  • privateAudioSemiAuto - The Enhanced Audio Controller is in semi-auto mode and is in the private state (i.e. audio will be played only through a connected Privacy Device). In private mode, no audio is transmitted through the speakers. When a Privacy Device is deactivated, the device will remain in the private state.

auxiliaries/enhancedMicrophoneControl

Specifies the state of the Enhanced Microphone Controller. The Enhanced Microphone Controller controls how private and public audio input are transmitted when the headset is inserted into/removed from the audio jack and when the handset is off-hook/on-hook. In the following, Privacy Device is used to refer to either the headset or handset. The Enhanced Microphone Controller state is specified as one of the followings:

  • notAvailable - The status is not available.
  • publicAudioManual - The Enhanced Microphone Controller is in manual mode and is in the public state (i.e. the microphone in the fascia is active). Activating a Privacy Device (headset connected/handset off-hook) will have no impact, i.e. input will remain through the fascia microphone and any microphone associated with the Privacy Device will not be active.
  • publicAudioAuto - The Enhanced Microphone Controller is in auto mode and is in the public state (i.e. the microphone in the fascia is active). When a Privacy Device with a microphone is activated, the device will go to the private state.
  • publicAudioSemiAuto - The Enhanced Microphone Controller is in semi-auto mode and is in the public state (i.e. the microphone in the fascia is active). When a Privacy Device with a microphone is activated, the device will go to the private state.
  • privateAudioManual - The Enhanced Microphone Controller is in manual mode and is in the private state (i.e. audio input will be via a microphone in the Privacy Device). In private mode, no audio input is transmitted through the fascia microphone.
  • privateAudioAuto - The Enhanced Microphone Controller is in auto mode and is in the private state (i.e. audio input will be via a microphone in the Privacy Device). In private mode, no audio input is transmitted through the fascia microphone. When a Privacy Device with a microphone is deactivated (headset disconnected/handset on-hook), the device will go to the public state. Where there is more than one Privacy Device with a microphone, the device will go to the public state only when all such Privacy Devices have been deactivated.
  • privateAudioSemiAuto - The Enhanced Microphone Controller is in semi-auto mode and is in the private state (i.e. audio input will be via a microphone in the Privacy Device). In private mode, no audio is transmitted through the fascia microphone. When a Privacy Device with a microphone is deactivated, the device will remain in the private state.

auxiliaries/microphoneVolume/available

Specifies whether the Microphone Volume Control is available.

default: false

auxiliaries/microphoneVolume/volumeLevel

Specifies the value of the Microphone Volume Control, if available. The value of Volume Control is defined in an interval from 1 to 1000 where 1 is the lowest volume level and 1000 is the highest volume level. The interval is defined in logarithmic steps, e.g. a volume control on a radio. Note: The Microphone Volume Control property is vendor-specific and therefore it is not possible to guarantee a consistent actual volume level across different vendor hardware.

Property value constraints:

minimum: 1
maximum: 1000

vendorMode

Status information for XFS4IoT services implementing the VendorMode interface. This will be omitted if the VendorMode interface is not supported.

vendorMode/device

Specifies the status of the Vendor Mode Service. Status will be one of the following values:

  • online - The Vendor Mode service is available.
  • offline - The Vendor Mode service is not available.

vendorMode/service

Specifies the service state as one of the following values:

  • enterPending - Vendor Mode enter request pending.
  • active - Vendor Mode active.
  • exitPending - Vendor Mode exit request pending.
  • inactive - Vendor Mode inactive.

vendorApplication

Status information for XFS4IoT services implementing the Vendor Application interface. This will be omitted if the Vendor Mode interface is not supported.

vendorApplication/accessLevel

Reports the current access level as one of the following values:

  • notActive - The application is not active.
  • basic - The application is active for the basic access level.
  • intermediate - The application is active for the intermediate access level.
  • full - The application is active for the full access level.

Event Messages

None

4.1.2 - Common.Capabilities

This command retrieves the capabilities of the service. It may also return vendor specific capability information.

This command can be used while in Vendor Mode.

Command Message

Payload (version 1.0) Type Required
{
"timeout": 5000integer
}
Properties

timeout

Timeout in milliseconds for the command to complete. If set to 0, the command will not timeout but can be canceled.

default: 0

Completion Message

Payload (version 1.0) Type Required
{
"completionCode": "success",string
"errorDescription": "Device not available",string
"interfaces": [{array (object)
"name": "Common",string
"commands": {object
"CardReader.ReadRawData": {object
"versions": ["1.3", "2.1", "3.0"]array (string)
},
"CardReader.Move": {object
See CardReader.ReadRawData properties.
}
},
"events": {object
"CardReader.MediaInsertedEvent": {object
"versions": ["1.3", "2.1", "3.0"]array (string)
},
"CardReader.MediaRemovedEvent": {object
See CardReader.MediaInsertedEvent properties.
}
},
"maximumRequests": 0integer
}],
"common": {object
"serviceVersion": "1.3.42",string
"deviceInformation": [{array (object)
"modelName": "AcmeModel42",string
"serialNumber": "1.0.12.05",string
"revisionNumber": "1.2.3",string
"modelDescription": "Acme Dispenser Model 3",string
"firmware": [{array (object)
"firmwareName": "Acme Firmware",string
"firmwareVersion": "1.0.1.2",string
"hardwareRevision": "4.3.0.5"string
}],
"software": [{array (object)
"softwareName": "Acme Software Name",string
"softwareVersion": "1.3.0.2"string
}]
}],
"powerSaveControl": false,boolean
"antiFraudModule": false,boolean
"endToEndSecurity": {object
"required": "always",string
"hardwareSecurityElement": true,boolean
"responseSecurityEnabled": "always",string
"commands": ["CashDispenser.Dispense"],array (string)
"commandNonceTimeout": 3600integer
}
},
"cardReader": {object
"type": "motor",string
"readTracks": {object
"track1": false,boolean
"track2": false,boolean
"track3": false,boolean
"watermark": false,boolean
"frontTrack1": false,boolean
"frontImage": false,boolean
"backImage": false,boolean
"track1JIS": false,boolean
"track3JIS": false,boolean
"ddi": falseboolean
},
"writeTracks": {object
"track1": false,boolean
"track2": false,boolean
"track3": false,boolean
"frontTrack1": false,boolean
"track1JIS": false,boolean
"track3JIS": falseboolean
},
"chipProtocols": {object
"chipT0": false,boolean
"chipT1": false,boolean
"chipProtocolNotRequired": false,boolean
"chipTypeAPart3": false,boolean
"chipTypeAPart4": false,boolean
"chipTypeB": false,boolean
"chipTypeNFC": falseboolean
},
"securityType": "notSupported",string
"powerOnOption": "notSupported",string
"powerOffOption": "notSupported",string
"fluxSensorProgrammable": false,boolean
"readWriteAccessFromExit": false,boolean
"writeMode": {object
"loco": false,boolean
"hico": false,boolean
"auto": falseboolean
},
"chipPower": {object
"cold": false,boolean
"warm": false,boolean
"off": falseboolean
},
"memoryChipProtocols": {object
"siemens4442": false,boolean
"gpm896": falseboolean
},
"positions": {object
"exit": false,boolean
"transport": falseboolean
},
"cardTakenSensor": falseboolean
},
"cashAcceptor": {object
"type": "tellerBill",string
"maxCashInItems": 1,integer
"shutter": false,boolean
"shutterControl": false,boolean
"intermediateStacker": 0,integer
"itemsTakenSensor": false,boolean
"itemsInsertedSensor": false,boolean
"positions": {object
"inLeft": false,boolean
"inRight": false,boolean
"inCenter": false,boolean
"inTop": false,boolean
"inBottom": false,boolean
"inFront": false,boolean
"inRear": false,boolean
"outLeft": false,boolean
"outRight": false,boolean
"outCenter": false,boolean
"outTop": false,boolean
"outBottom": false,boolean
"outFront": false,boolean
"outRear": falseboolean
},
"retractAreas": {object
"retract": false,boolean
"transport": false,boolean
"stacker": false,boolean
"reject": false,boolean
"billCassette": false,boolean
"cashIn": falseboolean
},
"retractTransportActions": {object
"present": false,boolean
"retract": false,boolean
"reject": false,boolean
"billCassette": false,boolean
"cashIn": falseboolean
},
"retractStackerActions": {object
"present": false,boolean
"retract": false,boolean
"reject": false,boolean
"billCassette": false,boolean
"cashIn": falseboolean
},
"cashInLimit": {object
"byTotalItems": false,boolean
"byAmount": falseboolean
},
"countActions": {object
"individual": false,boolean
"all": falseboolean
},
"counterfeitAction": "none"string
},
"cashDispenser": {object
"type": "tellerBill",string
"maxDispenseItems": 1,integer
"shutterControl": false,boolean
"retractAreas": {object
"retract": false,boolean
"transport": false,boolean
"stacker": false,boolean
"reject": false,boolean
"itemCassette": false,boolean
"cashIn": falseboolean
},
"retractTransportActions": {object
"present": false,boolean
"retract": false,boolean
"reject": false,boolean
"itemCassette": false,boolean
"cashIn": falseboolean
},
"retractStackerActions": {object
"present": false,boolean
"retract": false,boolean
"reject": false,boolean
"itemCassette": false,boolean
"cashIn": falseboolean
},
"intermediateStacker": false,boolean
"itemsTakenSensor": false,boolean
"positions": {object
"left": false,boolean
"right": false,boolean
"center": false,boolean
"top": false,boolean
"bottom": false,boolean
"front": false,boolean
"rear": falseboolean
},
"moveItems": {object
"fromCashUnit": false,boolean
"toCashUnit": false,boolean
"toTransport": false,boolean
"toStacker": falseboolean
}
},
"cashManagement": {object
"cashBox": false,boolean
"exchangeType": {object
"byHand": falseboolean
},
"itemInfoTypes": {object
"serialNumber": false,boolean
"signature": false,boolean
"image": falseboolean
},
"classificationList": falseboolean
},
"pinPad": {object
"pinFormats": {object
"ibm3624": false,boolean
"ansi": false,boolean
"iso0": false,boolean
"iso1": false,boolean
"eci2": false,boolean
"eci3": false,boolean
"visa": false,boolean
"diebold": false,boolean
"dieboldCo": false,boolean
"visa3": false,boolean
"banksys": false,boolean
"emv": false,boolean
"iso3": false,boolean
"ap": false,boolean
"iso4": falseboolean
},
"presentationAlgorithms": {object
"presentClear": falseboolean
},
"display": {object
"none": false,boolean
"ledThrough": false,boolean
"display": falseboolean
},
"idcConnect": false,boolean
"validationAlgorithms": {object
"des": false,boolean
"visa": falseboolean
},
"pinCanPersistAfterUse": false,boolean
"typeCombined": false,boolean
"setPinblockDataRequired": false,boolean
"pinBlockAttributes": {object
"P0": {object
"T": {object
"E": {object
"cryptoMethod": {object
"ecb": false,boolean
"cbc": false,boolean
"cfb": false,boolean
"ofb": false,boolean
"ctr": false,boolean
"xts": false,boolean
"rsaesPkcs1V15": false,boolean
"rsaesOaep": falseboolean
}
}
},
"R": {object
See T properties.
}
}
}
},
"crypto": {object
"emvHashAlgorithm": {object
"sha1Digest": false,boolean
"sha256Digest": falseboolean
},
"cryptoAttributes": {object
"D0": {object
"D": {object
"D": {object
"cryptoMethod": {object
"ecb": false,boolean
"cbc": false,boolean
"cfb": false,boolean
"ofb": false,boolean
"ctr": false,boolean
"xts": false,boolean
"rsaesPkcs1V15": false,boolean
"rsaesOaep": falseboolean
}
},
"E": {object
See D properties.
}
},
"T": {object
See D properties.
}
},
"D1": {object
See D0 properties.
}
},
"authenticationAttributes": {object
"M0": {object
"T": {object
"G": {object
"cryptoMethod": {object
"rsassaPkcs1V15": false,boolean
"rsassaPss": falseboolean
},
"hashAlgorithm": {object
"sha1": false,boolean
"sha256": falseboolean
}
},
"S": {object
See G properties.
}
},
"R": {object
See T properties.
}
},
"S0": {object
See M0 properties.
}
},
"verifyAttributes": {object
"M0": {object
"T": {object
"V": {object
"cryptoMethod": {object
"rsassaPkcs1V15": false,boolean
"rsassaPss": falseboolean
},
"hashAlgorithm": {object
"sha1": false,boolean
"sha256": falseboolean
}
}
},
"R": {object
See T properties.
}
},
"S0": {object
See M0 properties.
}
}
},
"keyManagement": {object
"keyNum": 0,integer
"derivationAlgorithms": {object
"chipZka": falseboolean
},
"keyCheckModes": {object
"self": false,boolean
"zero": falseboolean
},
"hsmVendor": "Add example",string
"rsaAuthenticationScheme": {object
"2partySig": false,boolean
"3partyCert": false,boolean
"3partyCertTr34": falseboolean
},
"rsaSignatureAlgorithm": {object
"pkcs1V15": false,boolean
"pss": falseboolean
},
"rsaCryptAlgorithm": {object
"pkcs1V15": false,boolean
"oaep": falseboolean
},
"rsaKeyCheckMode": {object
"sha1": false,boolean
"sha256": falseboolean
},
"signatureScheme": {object
"randomNumber": false,boolean
"exportDeviceId": false,boolean
"enhancedRkl": falseboolean
},
"emvImportSchemes": {object
"plainCA": false,boolean
"chksumCA": false,boolean
"epiCA": false,boolean
"issuer": false,boolean
"icc": false,boolean
"iccPin": false,boolean
"pkcsv15CA": falseboolean
},
"keyBlockImportFormats": {object
"A": false,boolean
"B": false,boolean
"C": false,boolean
"D": falseboolean
},
"keyImportThroughParts": false,boolean
"desKeyLength": {object
"single": false,boolean
"double": false,boolean
"triple": falseboolean
},
"certificateTypes": {object
"encKey": false,boolean
"verificationKey": false,boolean
"hostKey": falseboolean
},
"loadCertOptions": [{array (object)
"signer": "certHost",string
"option": {object
"newHost": false,boolean
"replaceHost": falseboolean
}
}],
"crklLoadOptions": {object
"noRandom": false,boolean
"noRandomCrl": false,boolean
"random": false,boolean
"randomCrl": falseboolean
},
"symmetricKeyManagementMethods": {object
"fixedKey": false,boolean
"masterKey": false,boolean
"tdesDukpt": falseboolean
},
"keyAttributes": {object
"M0": {object
"T": {object
"C": {object
"restrictedKeyUsage": "Add example"string
},
"E": {object
See C properties.
}
},
"R": {object
See T properties.
}
},
"K1": {object
See M0 properties.
}
},
"decryptAttributes": {object
"A": {object
"decryptMethod": {object
"ecb": false,boolean
"cbc": false,boolean
"cfb": false,boolean
"ofb": false,boolean
"ctr": false,boolean
"xts": false,boolean
"rsaesPkcs1V15": false,boolean
"rsaesOaep": falseboolean
}
},
"T": {object
See A properties.
}
},
"verifyAttributes": {object
"M0": {object
"T": {object
"V": {object
"cryptoMethod": {object
"kcvNone": false,boolean
"kcvSelf": false,boolean
"kcvZero": false,boolean
"sigNone": false,boolean
"rsassaPkcs1V15": false,boolean
"rsassaPss": falseboolean
},
"hashAlgorithm": {object
"sha1": false,boolean
"sha256": falseboolean
}
},
"S": {object
See V properties.
}
},
"R": {object
See T properties.
}
},
"S0": {object
See M0 properties.
}
}
},
"keyboard": {object
"autoBeep": {object
"activeAvailable": false,boolean
"activeSelectable": false,boolean
"inactiveAvailable": false,boolean
"inactiveSelectable": falseboolean
},
"etsCaps": [{array (object)
"xPos": 0,integer
"yPos": 0,integer
"xSize": 0,integer
"ySize": 0,integer
"maximumTouchFrames": 0,integer
"maximumTouchKeys": 0,integer
"float": {object
"x": false,boolean
"y": falseboolean
}
}]
},
"textTerminal": {object
"type": "fixed",string
"resolutions": [{array (object)
"sizeX": 0,integer
"sizeY": 0integer
}],
"keyLock": false,boolean
"cursor": false,boolean
"forms": falseboolean
},
"printer": {object
"type": {object
"receipt": false,boolean
"passbook": false,boolean
"journal": false,boolean
"document": false,boolean
"scanner": falseboolean
},
"resolution": {object
"low": false,boolean
"medium": false,boolean
"high": false,boolean
"veryHigh": falseboolean
},
"readForm": {object
"ocr": false,boolean
"micr": false,boolean
"msf": false,boolean
"barcode": false,boolean
"pageMark": false,boolean
"readImage": false,boolean
"readEmptyLine": falseboolean
},
"writeForm": {object
"text": false,boolean
"graphics": false,boolean
"ocr": false,boolean
"micr": false,boolean
"msf": false,boolean
"barcode": false,boolean
"stamp": falseboolean
},
"extents": {object
"horizontal": false,boolean
"vertical": falseboolean
},
"control": {object
"eject": false,boolean
"perforate": false,boolean
"cut": false,boolean
"skip": false,boolean
"flush": false,boolean
"retract": false,boolean
"stack": false,boolean
"partialCut": false,boolean
"alarm": false,boolean
"pageForward": false,boolean
"pageBackward": false,boolean
"turnMedia": false,boolean
"stamp": false,boolean
"park": false,boolean
"expel": false,boolean
"ejectToTransport": false,boolean
"rotate180": false,boolean
"clearBuffer": falseboolean
},
"maxMediaOnStacker": 5,integer
"acceptMedia": false,boolean
"multiPage": false,boolean
"paperSources": {object
"upper": false,boolean
"lower": false,boolean
"external": false,boolean
"aux": false,boolean
"aux2": false,boolean
"park": false,boolean
"exampleProperty1": false,boolean
"exampleProperty2": falseboolean
},
"mediaTaken": false,boolean
"retractBins": 1,integer
"maxRetract": [0],array (integer)
"imageType": {object
"tif": false,boolean
"wmf": false,boolean
"bmp": false,boolean
"jpg": falseboolean
},
"frontImageColorFormat": {object
"binary": false,boolean
"grayscale": false,boolean
"full": falseboolean
},
"backImageColorFormat": {object
"binary": false,boolean
"grayScale": false,boolean
"full": falseboolean
},
"codelineFormat": {object
"cmc7": false,boolean
"e13b": false,boolean
"ocr": falseboolean
},
"imageSource": {object
"imageFront": false,boolean
"imageBack": false,boolean
"codeLine": falseboolean
},
"dispensePaper": false,boolean
"osPrinter": "Add example",string
"mediaPresented": false,boolean
"autoRetractPeriod": 0,integer
"retractToTransport": false,boolean
"coercivityType": {object
"low": false,boolean
"high": false,boolean
"auto": falseboolean
},
"controlPassbook": {object
"turnForward": false,boolean
"turnBackward": false,boolean
"closeForward": false,boolean
"closeBackward": falseboolean
},
"printSides": "notSupported"string
},
"barcodeReader": {object
"canFilterSymbologies": false,boolean
"symbologies": {object
"ean128": false,boolean
"ean8": false,boolean
"ean8_2": false,boolean
"ean8_5": false,boolean
"ean13": false,boolean
"ean13_2": false,boolean
"ean13_5": false,boolean
"jan13": false,boolean
"upcA": false,boolean
"upcE0": false,boolean
"upcE0_2": false,boolean
"upcE0_5": false,boolean
"upcE1": false,boolean
"upcE1_2": false,boolean
"upcE1_5": false,boolean
"upcA_2": false,boolean
"upcA_5": false,boolean
"codabar": false,boolean
"itf": false,boolean
"code11": false,boolean
"code39": false,boolean
"code49": false,boolean
"code93": false,boolean
"code128": false,boolean
"msi": false,boolean
"plessey": false,boolean
"std2Of5": false,boolean
"std2Of5Iata": false,boolean
"pdf417": false,boolean
"microPdf417": false,boolean
"dataMatrix": false,boolean
"maxiCode": false,boolean
"codeOne": false,boolean
"channelCode": false,boolean
"telepenOriginal": false,boolean
"telepenAim": false,boolean
"rss": false,boolean
"rssExpanded": false,boolean
"rssRestricted": false,boolean
"compositeCodeA": false,boolean
"compositeCodeB": false,boolean
"compositeCodeC": false,boolean
"posiCodeA": false,boolean
"posiCodeB": false,boolean
"triopticCode39": false,boolean
"codablockF": false,boolean
"code16K": false,boolean
"qrCode": false,boolean
"aztec": false,boolean
"ukPost": false,boolean
"planet": false,boolean
"postnet": false,boolean
"canadianPost": false,boolean
"netherlandsPost": false,boolean
"australianPost": false,boolean
"japanesePost": false,boolean
"chinesePost": false,boolean
"koreanPost": falseboolean
}
},
"biometric": {object
"type": {object
"facialFeatures": false,boolean
"voice": false,boolean
"fingerprint": false,boolean
"fingerVein": false,boolean
"iris": false,boolean
"retina": false,boolean
"handGeometry": false,boolean
"thermalFace": false,boolean
"thermalHand": false,boolean
"palmVein": false,boolean
"signature": falseboolean
},
"maxCapture": 0,integer
"templateStorage": 0,integer
"dataFormats": {object
"isoFid": false,boolean
"isoFmd": false,boolean
"ansiFid": false,boolean
"ansiFmd": false,boolean
"qso": false,boolean
"wso": false,boolean
"reservedRaw1": false,boolean
"reservedTemplate1": false,boolean
"reservedRaw2": false,boolean
"reservedTemplate2": false,boolean
"reservedRaw3": false,boolean
"reservedTemplate3": falseboolean
},
"encryptionalAlgorithm": {object
"ecb": false,boolean
"cbc": false,boolean
"cfb": false,boolean
"rsa": falseboolean
},
"storage": {object
"secure": false,boolean
"clear": falseboolean
},
"persistenceModes": {object
"persist": false,boolean
"clear": falseboolean
},
"matchSupported": "storedMatch",string
"scanModes": {object
"scan": false,boolean
"match": falseboolean
},
"compareModes": {object
"verify": false,boolean
"identity": falseboolean
},
"clearData": {object
"scannedData": false,boolean
"importedData": false,boolean
"setMatchedData": falseboolean
}
},
"camera": {object
"type": "cam",string
"cameras": {object
"room": false,boolean
"person": false,boolean
"exitSlot": false,boolean
"vendorSpecificCamera": falseboolean
},
"maxPictures": 0,integer
"camData": {object
"autoAdd": false,boolean
"manAdd": falseboolean
},
"maxDataLength": 0,integer
"pictureFile": falseboolean
},
"lights": {object
"cardReader": {object
"flashRate": {object
"off": false,boolean
"slow": false,boolean
"medium": false,boolean
"quick": false,boolean
"continuous": falseboolean
},
"color": {object
"red": false,boolean
"green": false,boolean
"yellow": false,boolean
"blue": false,boolean
"cyan": false,boolean
"magenta": false,boolean
"white": falseboolean
},
"direction": {object
"entry": false,boolean
"exit": falseboolean
},
"position": {object
"left": false,boolean
"right": false,boolean
"center": false,boolean
"top": false,boolean
"bottom": false,boolean
"front": false,boolean
"rear": falseboolean
}
},
"pinPad": {object
See cardReader properties.
},
"notesDispenser": {object
See cardReader properties.
},
"coinDispenser": {object
See cardReader properties.
},
"receiptPrinter": {object
See cardReader properties.
},
"passbookPrinter": {object
See cardReader properties.
},
"envelopeDepository": {object
See cardReader properties.
},
"billAcceptor": {object
See cardReader properties.
},
"envelopeDispenser": {object
See cardReader properties.
},
"documentPrinter": {object
See cardReader properties.
},
"coinAcceptor": {object
See cardReader properties.
},
"scanner": {object
See cardReader properties.
},
"contactless": {object
See cardReader properties.
},
"cardReader2": {object
See cardReader properties.
},
"notesDispenser2": {object
See cardReader properties.
},
"billAcceptor2": {object
See cardReader properties.
},
"statusGood": {object
See cardReader properties.
},
"statusWarning": {object
See cardReader properties.
},
"statusBad": {object
See cardReader properties.
},
"statusSupervisor": {object
See cardReader properties.
},
"statusInService": {object
See cardReader properties.
},
"fasciaLight": {object
See cardReader properties.
},
"vendorSpecificLight": {object
See cardReader properties.
}
},
"auxiliaries": {object
"operatorSwitch": {object
"run": false,boolean
"maintenance": false,boolean
"supervisor": falseboolean
},
"tamperSensor": false,boolean
"internalTamperSensor": false,boolean
"seismicSensor": false,boolean
"heatSensor": false,boolean
"proximitySensor": false,boolean
"ambientLightSensor": false,boolean
"enhancedAudioSensor": {object
"manual": false,boolean
"auto": false,boolean
"semiAuto": false,boolean
"bidirectional": falseboolean
},
"bootSwitchSensor": false,boolean
"displaySensor": false,boolean
"operatorCallButtonSensor": false,boolean
"handsetSensor": {object
"manual": false,boolean
"auto": false,boolean
"semiAuto": false,boolean
"microphone": falseboolean
},
"headsetMicrophoneSensor": {object
"manual": false,boolean
"auto": false,boolean
"semiAuto": falseboolean
},
"fasciaMicrophoneSensor": false,boolean
"safeDoor": {object
"closed": false,boolean
"open": false,boolean
"locked": false,boolean
"bolted": false,boolean
"tampered": falseboolean
},
"vandalShield": {object
"closed": false,boolean
"open": false,boolean
"locked": false,boolean
"service": false,boolean
"keyboard": false,boolean
"tampered": falseboolean
},
"frontCabinet": {object
See safeDoor properties.
},
"rearCabinet": {object
See safeDoor properties.
},
"leftCabinet": {object
See safeDoor properties.
},
"rightCabinet": {object
See safeDoor properties.
},
"openCloseIndicator": false,boolean
"audio": false,boolean
"heating": false,boolean
"consumerDisplayBacklight": false,boolean
"signageDisplay": false,boolean
"volume": 1,integer
"ups": {object
"low": false,boolean
"engaged": false,boolean
"powering": false,boolean
"recovered": falseboolean
},
"audibleAlarm": false,boolean
"enhancedAudioControl": {object
"headsetDetection": false,boolean
"modeControllable": falseboolean
},
"enhancedMicrophoneControlState": {object
"headsetDetection": false,boolean
"modeControllable": falseboolean
},
"microphoneVolume": 1,integer
"autoStartupMode": {object
"specific": false,boolean
"daily": false,boolean
"weekly": falseboolean
}
},
"vendorApplication": {object
"supportedAccessLevels": {object
"basic": false,boolean
"intermediate": false,boolean
"full": false,boolean
"accessNotSupported": falseboolean
}
}
}
Properties

completionCode

The completion code.

errorDescription

If included, this contains additional vendor dependent information to assist with problem resolution.

interfaces

Array of interfaces supported by this XFS4IoT service.

interfaces/name

Name of supported XFS4IoT interface. Following values are supported:

  • Common - Common interface. Every device implements this interface.
  • CardReader - CardReader interface.
  • CashAcceptor - CashAcceptor interface.
  • CashDispenser - CashDispenser interface.
  • CashManagement - CashManagement interface.
  • PinPad - PinPad interface.
  • Crypto - Crypto interface.
  • KeyManagement - KeyManagement interface.
  • Keyboard - Keyboard interface.
  • TextTerminal - TextTerminal interface.
  • Printer - Printer interface.
  • BarcodeReader - BarcodeReader interface.
  • Lights - Lights interface.
  • Auxiliaries - Auxiliaries interface.
  • VendorMode - VendorMode interface.
  • VendorApplication - VendorApplication interface.
  • Storage - Storage interface

interfaces/commands

The commands supported by the service.