Extensions for Financial Services (XFS)

XFS4IoT Specification

2024-03 Preview

November 12, 2024

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

© 2024 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
api-4 JSON Schema 2020-12 (https://json-schema.org)

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 message 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 defined using JSON Schema 2020-12 Ref. api-4.

2.3.1 - Message Definition

All messages follow the same JSON structure consisting of the following properties:

Property Property Type Required
header object ✓
payload object, null

As illustrated in the example below.

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

2.3.2 - Header Definition

The headers contains properties common to all messages as well as properties specific to a message type.

Additional properties are not allowed.

Property Property Type Required
type string ✓
name string ✓
version string ✓
requestId integer
timeout integer
status string, null
completionCode string, null
errorDescription string, null

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

{
    "header": {
        "type": "command",
        "name": "Common.Status",
        "version": "1.0",
        "requestId": 12345,
        "timeout": 1000
    }
}

2.3.2.1 - type Property

2.3.2.2 - name Property

The message name, for example Common.Status.

2.3.2.3 - version Property

The message version, for example 1.0.

2.3.2.4 - requestId Property

Unique request identifier supplied by the client used to correlate the command message with acknowledge, event and completion messages. The client will supply values that are positive, incremental and greater than or equal to 0. The service will check that the requestId does not conflict with a currently executing or queued command request from the same client and return status invalidRequestID if it does.

Unsolicited messages do not have a requestId.

2.3.2.5 - timeout Property

This property is only applicable to command messages.

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

Default: 0

2.3.2.6 - status Property

This property is only applicable to acknowledge messages.

If null the command has been accepted for execution and will complete with a completion message. Otherwise this property can be one of the following values:

  • invalidMessage - The JSON in the message is invalid and can't be parsed.
  • invalidRequestID - The request ID on the command is invalid. This could be because the value is not an integer, has a zero value, or because a command with the same request ID from the same client is already queued or is executing.
  • tooManyRequests - The service has currently received and queued more requests than it can process.

Default: null

2.3.2.7 - completionCode Property

This property is only applicable to completion messages.

If null the command completed successfully. Otherwise, the property will contain one of the following values:

  • 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.
  • notEnoughSpace - There is not enough space on the storage.

If the value is commandErrorCode, the payload errorCode property contains the command specific completion error code.

Default: null

2.3.2.8 - errorDescription Property

This property is only applicable to completion messages for which the completionCode value is neither canceled or timeOut.

If not null, this contains additional vendor dependent information to assist with problem resolution. The format of this string should not be relied on.

Default: null

2.3.3 - Payload Definition

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

If not null, the payload cannot be empty. It must contain at least one property.

2.3.3.1 - 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.

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.

When non-standard properties are used there is a risk that the same name could be used by different implementations, causing unexpected behaviors. Implementors should reduce the risk of this name clash by using a company name or code as a prefix for the property name. For example, a company called "Acme" might add the "acmeHardwareError" and "acmeLogMessage" properties.

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 parsed 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.

If for any reason the service does not accept and queue the command request, the acknowledge message header status property will indicate the reason. When this occurs, the acknowledge message is the final message related to the command request.

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

Not all commands that could require E2E security are currently covered. When E2E security is being enforced by a device, sensitive commands with no token defined will be blocked from executing. This is required to avoid any way of bypassing security. For example, the cash CashDispenser.Dispense command has a token format defined but the CashDispenser.TestCashUnits command does not. For security, CashDispenser. TestCashUnits must be blocked from dispensing cash, otherwise an attacker could simply replace the CashDispenser. Dispense with calls to CashDispenser.TestCashUnits. Restrictions are documented for each affected command.

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 2.0)
This message does not define any properties.

Completion Message

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

vendorName

Freeform string naming the hardware vendor.

Type: string
Required

services

Array of one or more services exposed by the publisher. This property is null if no services available.

Type: array (object), null
Default: null

services/serviceURI

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

Type: string
Format: URI
Required

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 2.0)
{ "vendorName": "ACME ATM Hardware GmbH", "services": [{ "serviceURI": "wss://ATM1:123/xfs4iot/v1.0/CardReader" }] }
Properties

vendorName

Freeform string naming the hardware vendor.

Type: string
Required

services

Array of one or more services exposed by the publisher. This property is null if no services available.

Type: array (object), null
Default: null

services/serviceURI

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

Type: string
Format: URI
Required

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 2.0)
This message does not define any properties.

Completion Message

Payload (version 3.0)
{ "common": { "device": "online", "devicePosition": "notInPosition", "powerSaveRecoveryTime": 10, "antiFraudModule": "ok", "exchange": "active", "endToEndSecurity": "enforced", "persistentDataStore": { "remaining": 0 } }, "cardReader": { "media": "unknown", "security": "notReady", "chipPower": "unknown", "chipModule": "ok", "magWriteModule": "ok", "frontImageModule": "ok", "backImageModule": "ok" }, "cashAcceptor": { "intermediateStacker": "empty", "stackerItems": "customerAccess", "banknoteReader": "ok", "dropBox": true, "positions": [{ "position": "inLeft", "shutter": "closed", "positionStatus": "empty", "transport": "ok", "transportStatus": "empty" }] }, "cashDispenser": { "intermediateStacker": "empty", "positions": [{ "position": "outDefault", "shutter": "closed", "positionStatus": "empty", "transport": "ok", "transportStatus": "empty" }] }, "cashManagement": { "dispenser": "ok", "acceptor": "ok" }, "check": { "acceptor": "ok", "media": "present", "toner": "full", "ink": "full", "frontImageScanner": "ok", "backImageScanner": "ok", "mICRReader": "ok", "stacker": "empty", "rebuncher": "empty", "mediaFeeder": "notEmpty", "positions": { "input": { "shutter": "closed", "positionStatus": "empty", "transport": "ok", "transportMediaStatus": "empty", "jammedShutterPosition": "notJammed" }, "output": See check/positions/input properties "refused": See check/positions/input properties } }, "mixedMedia": { "modes": { "cashAccept": true, "checkAccept": true } }, "keyManagement": { "encryptionState": "ready", "certificateState": "unknown" }, "keyboard": { "autoBeepMode": { "activeAvailable": false, "inactiveAvailable": false } }, "textTerminal": { "keyboard": "on", "keyLock": "on", "displaySizeX": 0, "displaySizeY": 0 }, "printer": { "media": "unknown", "paper": { "upper": "unknown", "lower": "unknown", "external": "unknown", "aux": "unknown", "aux2": "unknown", "park": "unknown", "vendorSpecificPaperSupply": "unknown" }, "toner": "unknown", "ink": "unknown", "lamp": "unknown", "mediaOnStacker": 7, "paperType": { "upper": "unknown", "lower": "unknown", "external": "unknown", "aux": "unknown", "aux2": "unknown", "park": "unknown", "exampleProperty1": "unknown", "exampleProperty2": See printer/paperType/exampleProperty1 }, "blackMarkMode": "unknown" }, "barcodeReader": { "scanner": "on" }, "biometric": { "subject": "present", "capture": false, "dataPersistence": "persist", "remainingStorage": 0 }, "camera": { "media": { "room": "ok", "person": "ok", "exitSlot": "ok", "vendorSpecificCameraMedia": "ok" }, "cameras": { "room": "ok", "person": "ok", "exitSlot": "ok", "vendorSpecificCameraState": See camera/media/vendorSpecificCameraMedia }, "pictures": { "room": 0, "person": 0, "exitSlot": 0, "vendorSpecificCameraPictures": 0 } }, "lights": { "cardReader": { "right": { "flashRate": "off", "color": "red", "direction": "entry" }, "top": See lights/cardReader/right properties }, "pinPad": See lights/cardReader properties "notesDispenser": See lights/cardReader properties "coinDispenser": See lights/cardReader properties "receiptPrinter": See lights/cardReader properties "passbookPrinter": See lights/cardReader properties "envelopeDepository": See lights/cardReader properties "checkUnit": See lights/cardReader properties "billAcceptor": See lights/cardReader properties "envelopeDispenser": See lights/cardReader properties "documentPrinter": See lights/cardReader properties "coinAcceptor": See lights/cardReader properties "scanner": See lights/cardReader properties "contactless": See lights/cardReader properties "cardReader2": See lights/cardReader properties "notesDispenser2": See lights/cardReader properties "billAcceptor2": See lights/cardReader properties "statusGood": See lights/cardReader properties "statusWarning": See lights/cardReader properties "statusBad": See lights/cardReader properties "statusSupervisor": See lights/cardReader properties "statusInService": See lights/cardReader properties "fasciaLight": See lights/cardReader properties "vendorSpecificLight": See lights/cardReader properties }, "banknoteNeutralization": { "state": { "mode": "fault", "submode": "allSafeSensorsIgnored" }, "safeDoor": "fault", "safeBolt": "fault", "tilt": "fault", "light": "fault", "gas": "initializing", "temperature": "fault", "seismic": "fault", "customInputs": { "disableGas": { "inputState": "disabled" }, "oemDisableLight": See banknoteNeutralization/customInputs/disableGas properties }, "powerSupply": { "info": { "powerInStatus": "powering", "powerOutStatus": "powering", "batteryStatus": "full", "batteryChargingStatus": "charging" }, "powerSaveRecoveryTime": 10 }, "warnings": { "protectionArmingFault": false, "protectionDisarmingFault": false, "externalMainPowerOutage": false, "storageUnitLowPowerSupply": false, "armedAutonomous": false, "armedAlarm": false, "gasWarningLevel": false, "seismicActivityWarningLevel": false }, "errors": { "protectionEnablingFailure": false, "protectionDisarmingFailure": false, "storageUnitPowerSupplyFailure": false, "backupBatteryFailure": false, "gasCriticalLevel": false, "light": false, "tilted": false, "seismicActivityCriticalLevel": false } }, "auxiliaries": { "operatorSwitch": "run", "tamperSensor": "on", "internalTamperSensor": "on", "seismicSensor": "on", "heatSensor": "on", "proximitySensor": "present", "ambientLightSensor": "veryDark", "enhancedAudioSensor": "present", "bootSwitchSensor": "off", "consumerDisplaySensor": "off", "operatorCallButtonSensor": "off", "handsetSensor": "onTheHook", "headsetMicrophoneSensor": "present", "fasciaMicrophoneSensor": "off", "cabinetDoor": "closed", "safeDoor": "closed", "vandalShield": "closed", "cabinetFrontDoor": "closed", "cabinetRearDoor": "closed", "cabinetLeftDoor": "closed", "cabinetRightDoor": "closed", "openClosedIndicator": "closed", "audio": { "rate": "on", "signal": "keypress" }, "heating": "off", "consumerDisplayBacklight": "off", "signageDisplay": "off", "volume": 1, "UPS": { "low": true, "engaged": false, "powering": false, "recovered": false }, "audibleAlarm": "on", "enhancedAudioControl": "publicAudioManual", "enhancedMicrophoneControl": "publicAudioManual", "microphoneVolume": 1 }, "deposit": { "depTransport": "ok", "envDispenser": "ok", "printer": "ok", "toner": "full", "shutter": "closed", "depositLocation": "unknown" }, "vendorMode": { "device": "online", "service": "enterPending" }, "vendorApplication": { "accessLevel": "notActive" }, "powerManagement": { "info": { "powerInStatus": "powering", "powerOutStatus": "powering", "batteryStatus": "full", "batteryChargingStatus": "charging" }, "powerSaveRecoveryTime": 10 } }
Properties

common

Status information common to all XFS4IoT services.

Type: object
Required

common/device

Specifies the state of the device. This property is required in Common.Status, but may be null in Common.StatusChangedEvent if it has not changed. 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.

Type: string
Required

common/devicePosition

Position of the device. This property is null in Common.Status if position status reporting is not supported, otherwise the 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.

Type: string, null
Default: null

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 the power saving mode has not been activated. This property is null in Common.Status if power save control is not supported.

Type: integer, null
Minimum: 0
Default: null

common/antiFraudModule

Specifies the state of the anti-fraud module if available. This property is null in Common.Status if there is no anti-fraud module, otherwise the 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.

Type: string, null
Default: null

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. This property is null in Common.Status if not supported, otherwise the following values are possible:

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

Type: string, null
Default: null

common/endToEndSecurity

Specifies the status of end to end security support on this device. This property is null in Common.Status if E2E security is not supported by this hardware and any command can be called without a token, otherwise the following values are possible.

Also see Common.CapabilityProperties.endToEndSecurity.

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

Type: string, null
Default: null

common/persistentDataStore

Specifies the state of the persistent data store supported by the service. This property is null in Common.Status if persistent data storage is not supported or in Common.StatusChangedEvent if it has not changed. It is recommended that a service only posts a Common.StatusChangedEvent based on this changing when significant changes occur to avoid too many trivial events being posted.

Type: object, null
MinProperties: 1
Default: null

common/persistentDataStore/remaining

Specifies the number of Kilobytes remaining in the persistent data store. This value must be less than or equal to the persistent data store capacity.

Type: integer
Minimum: 0

cardReader

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

Type: object, null
Default: null

cardReader/media

Specifies the transport/exit position media state. This property will be null if the capability to report media position is not supported by the device (e.g., a typical swipe reader or contactless chip card reader), otherwise one of the following values:

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

Type: string, null
Default: null

cardReader/security

Specifies the state of the security module. This property will be null if no security module is available, otherwise one of the following values:

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

Type: string, null
Default: null

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. This property will be null if the capability to report the state of the chip is not supported by the ID card unit device and will apply to contactless chip card readers, otherwise one of the following values:

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

Type: string, null
Default: null

cardReader/chipModule

Specifies the state of the chip card module reader. This property will be null if reporting the chip card module status is not supported, otherwise one of the following values:

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

Type: string, null
Default: null

cardReader/magWriteModule

Specifies the state of the magnetic card writer. This property will be null if reporting the magnetic card writing module status is not supported, otherwise one of the following values:

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

Type: string, null
Default: null

cardReader/frontImageModule

Specifies the state of the front image reader. This property will be null if reporting the front image reading module status is not supported, otherwise one of the following values:

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

Type: string, null
Default: null

cardReader/backImageModule

Specifies the state of the back image reader. This property will be null if reporting the back image reading module status is not supported, otherwise one of the following values:

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

Type: string, null
Default: null

cashAcceptor

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

Type: object, null
Default: null

cashAcceptor/intermediateStacker

Supplies the state of the intermediate stacker. This property is null in Common.Status if the physical device has no intermediate stacker, otherwise 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.

Type: string, null
Default: null

cashAcceptor/stackerItems

This property informs the application whether items on the intermediate stacker have been in customer access. This property is null in Common.Status if the physical device has no intermediate stacker, otherwise 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.

Type: string, null
Default: null

cashAcceptor/banknoteReader

Supplies the state of the banknote reader. This property is null in Common.Status if the physical device has no banknote reader, otherwise 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.

Type: string, null
Default: null

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 property 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. This property may be null if there is no drop box or its state has not changed in Common.StatusChangedEvent.

Type: boolean, null
Default: null

cashAcceptor/positions

Array of structures reporting status for each position from which items can be accepted. This may be null in Common.StatusChangedEvent if no position states have changed.

Type: array (object), null
Default: null

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.

Type: string
Required

cashAcceptor/positions/shutter

Supplies the state of the shutter. This property is null in Common.Status if the physical position has no shutter, otherwise 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.

Type: string, null
Default: null

cashAcceptor/positions/positionStatus

The status of the input or output position. This property is null in Common.Status if the device is not capable of reporting whether items are at the position, otherwise 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.
  • foreignItems - Foreign items have been detected in the position.

Type: string, null
Default: null

cashAcceptor/positions/transport

Supplies the state of the transport mechanism. The transport is defined as any area leading to or from the position. This property is null in Common.Status if the device has no transport or transport state reporting is not supported, otherwise 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.

Type: string, null
Default: null

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. This property is null in Common.Status if the device has no transport or is not capable of reporting whether items are on the transport, otherwise 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.

Type: string, null
Default: null

cashDispenser

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

Type: object, null
Default: null

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. This property is null in Common.Status if the physical device has no intermediate stacker, otherwise the 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.

Type: string, null
Default: null

cashDispenser/positions

Array of structures for each position to which items can be dispensed or presented. This may be null in Common.StatusChangedEvent if no position states have changed.

Type: array (object), null
Default: null

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.

Type: string
Default: "outDefault"

cashDispenser/positions/shutter

Supplies the state of the shutter. This property is null in Common.Status if the physical position has no shutter, otherwise the 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.

Type: string, null
Default: null

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. This property is null in Common.Status if the device is not capable of reporting whether items are at the position, otherwise 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.

Type: string, null
Default: null

cashDispenser/positions/transport

Supplies the state of the transport mechanism. The transport is defined as any area leading to or from the position. This property is null in Common.Status if the device has no transport or transport state reporting is not supported, otherwise 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.

Type: string, null
Default: null

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. This property is null in Common.Status if the device has no transport or is not capable of reporting whether items are on the transport, otherwise 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.

Type: string, null
Default: null

cashManagement

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

Type: object, null
Default: null

cashManagement/dispenser

Supplies the state of the storage units for dispensing cash. This may be null in Common.Status if the device is not capable of dispensing cash, otherwise the 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 appLockOut is set to true 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.

Type: string, null
Default: null

cashManagement/acceptor

Supplies the state of the storage units for accepting cash. This may be null in Common.Status if the device is not capable of accepting cash, otherwise the 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 appLockIn is set to true on every storage unit which can be locked, or when items are to be automatically retained within storage units (see retainAction), 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.

Type: string, null
Default: null

check

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

Type: object, null
Default: null

check/acceptor

Supplies the state of the overall acceptor storage units. This may be null in Common.StatusChangedEvent if the state has not changed. The following values are possible:

  • ok - All storage units present are in a good state.
  • state - One or more of the storage units is in a high, full or inoperative condition. Items can still be accepted into at least one of the storage units. The status of the storage units can be obtained through the Storage.GetStorage command.
  • stop - Due to a storage unit problem accepting is impossible. No items can be accepted because all of the storage units are in a full or in an inoperative condition.
  • unknown - Due to a hardware error or other condition, the state of the storage units cannot be determined.

Type: string, null
Default: null

check/media

Specifies the state of the media. This may be null in Common.Status if the capability to report the state of the media is not supported by the device, otherwise the following values are possible:

  • present - Media is present in the device.
  • notPresent - Media is not present in the device.
  • jammed - Media is jammed in the device.
  • unknown - The state of the media cannot be determined with the device in its current state.
  • position - Media is at one or more of the input, output and refused positions.

Type: string, null
Default: null

check/toner

Specifies the state of the toner or ink supply or the state of the ribbon of the endorser. This may be null in Common.Status if the physical device does not support endorsing or the capability to report the status of the toner/ink is not supported by the device, otherwise the following values are possible:

  • 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.
  • unknown - Status of toner or ink supply or the ribbon cannot be determined with the device in its current state.

Type: string, null
Default: null

check/ink

Specifies the status of the stamping ink in the device. This may be null in Common.Status if the physical device does not support stamping or the capability to report the status of the stamp ink supply is not supported by the device, otherwise the following values are possible:

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

Type: string, null
Default: null

check/frontImageScanner

Specifies the status of the image scanner that captures images of the front of the media items. This may be null in Common.Status if the physical device has no front scanner or the capability to report the status of the front scanner is not supported by the device, otherwise the following values are possible:

  • ok - The front scanner is OK.
  • fading - The front scanner performance is degraded.
  • inoperative - The front scanner is inoperative.
  • unknown - Status of the front scanner cannot be determined with the device in its current state.

Type: string, null
Default: null

check/backImageScanner

Specifies the status of the image scanner that captures images of the back of the media items. This may be null in Common.Status if the physical device has no back scanner or the capability to report the status of the back scanner is not supported by the device, otherwise the following values are possible:

  • ok - The back scanner is OK.
  • fading - The back scanner performance is degraded.
  • inoperative - The back scanner is inoperative.
  • unknown - Status of the back scanner cannot be determined with the device in its current state.

Type: string, null
Default: null

check/mICRReader

Specifies the status of the MICR code line reader. This may be null in Common.Status if the physical device has no MICR code line reader or the capability to report the status of the MICR code line reader is not supported by the device, otherwise the following values are possible:

  • ok - The MICR code line reader is OK.
  • fading - The MICR code line reader performance is degraded.
  • inoperative - The MICR code line reader is inoperative.
  • unknown - Status of the MICR code line reader cannot be determined with the device in its current state.

Type: string, null
Default: null

check/stacker

Supplies the state of the stacker (also known as an escrow). The stacker is where the media items are held while the application decides what to do with them. This may be null in Common.Status if the physical device has no stacker or the capability to report the status of the stacker is not supported by the device, otherwise the following values are possible:

  • empty - The stacker is empty.
  • notEmpty - The stacker is not empty.
  • full - The stacker is full. This state is set if the number of media items on the stacker has reached maxMediaOnStacker or some physical limit has been reached.
  • inoperative - The stacker is inoperative.
  • unknown - Due to a hardware error or other condition, the state of the stacker cannot be determined.

Type: string, null
Default: null

check/rebuncher

Supplies the state of the re-buncher (return stacker). The re-buncher is where media items are re-bunched ready for return to the customer. This may be null in Common.Status if the physical device has no re-buncher or the capability to report the status of the re-buncher is not supported by the device, otherwise the following values are possible:

  • empty - The re-buncher is empty.
  • notEmpty - The re-buncher is not empty.
  • full - The re-buncher is full. This state is set if the number of media items on the re-buncher has reached its physical limit.
  • inoperative - The re-buncher is inoperative.
  • unknown - Due to a hardware error or other condition, the state of the re-buncher cannot be determined.

Type: string, null
Default: null

check/mediaFeeder

Supplies the state of the media feeder. This value indicates if there are items on the media feeder waiting for processing via the Check.GetNextItem command. If null, the device has no media feeder or the capability to report the status of the media feeder is not supported by the device. This value can be one of the following values:

  • empty - The media feeder is empty.
  • notEmpty - The media feeder is not empty.
  • inoperative - The media feeder is inoperative.
  • unknown - Due to a hardware error or other condition, the state of the media feeder cannot be determined.

Type: string, null
Default: null

check/positions

Specifies the status of the input, output and refused positions. This may be null in Common.StatusChangedEvent if no position states have changed.

Type: object, null
MinProperties: 1
Default: null

check/positions/input

Specifies the status of the input position. This may be null in Common.StatusChangedEvent if no states have changed for the position.

Type: object, null
Default: null

check/positions/input/shutter

Specifies the state of the shutter. This property is null in Common.Status if the physical device has no shutter or shutter state reporting is not supported, otherwise the following values are possible:

  • closed - The shutter is operational and is closed.
  • open - The shutter is operational and is open.
  • jammed - The shutter is jammed and is not operational.
  • unknown - Due to a hardware error or other condition, the state of the shutter cannot be determined.

Type: string, null
Default: null
Required

check/positions/input/positionStatus

The status of the position. This property is null in Common.Status if the physical device is not capable of reporting whether or not items are at the position, otherwise 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.

Type: string, null
Default: null

check/positions/input/transport

Specifies the state of the transport mechanism. The transport is defined as any area leading to or from the position. This property is null in Common.Status if the physical device has no transport or transport state reporting is not supported, otherwise 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.

Type: string, null
Default: null

check/positions/input/transportMediaStatus

Returns information regarding items which may be present on the transport. This property is null in Common.Status if the physical device is not capable of reporting whether or not items are on the transport, otherwise the following values are possible:

  • empty - The transport is empty.
  • notEmpty - The transport is not empty.
  • unknown - Due to a hardware error or other condition it is not known whether there are items on the transport.

Type: string, null
Default: null

check/positions/input/jammedShutterPosition

Returns information regarding the position of the jammed shutter. This property is null in Common.Status if the physical device has no shutter or the reporting of the position of a jammed shutter is not supported, otherwise the following values are possible:

  • notJammed - The shutter is not jammed.
  • open - The shutter is jammed, but fully open.
  • partiallyOpen - The shutter is jammed, but partially open.
  • closed - The shutter is jammed, but fully closed.
  • unknown - The position of the shutter is unknown.

Type: string, null
Default: null

check/positions/output

Specifies the status of the output position. This may be null in Common.StatusChangedEvent if no states have changed for the position.

Type: object, null
Default: null

check/positions/refused

Specifies the status of the refused position. This may be null in Common.StatusChangedEvent if no states have changed for the position.

Type: object, null
Default: null

mixedMedia

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

Type: object, null
Default: null

mixedMedia/modes

Specifies the state of the transaction modes supported by the Service.

Type: object
MinProperties: 1
Required

mixedMedia/modes/cashAccept

Specifies whether transactions can accept cash. This property may be null if no change required or its state has not changed in Common.StatusChangedEvent.

Type: boolean, null
Default: null

mixedMedia/modes/checkAccept

Specifies whether transactions can accept checks. This property may be null if no change required or its state has not changed in Common.StatusChangedEvent.

Type: boolean, null
Default: null

keyManagement

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

Type: object, null
Default: null

keyManagement/encryptionState

Specifies the state of the encryption module. This may be null in Common.StatusChangedEvent if unchanged.

Type: string, null
Default: null

keyManagement/certificateState

Specifies the state of the public verification or encryption key in the PIN certificate modules. This may be null in Common.StatusChangedEvent if unchanged.

Type: string, null
Default: null

keyboard

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

Type: object, null
Default: null

keyboard/autoBeepMode

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

Type: object
Required

keyboard/autoBeepMode/activeAvailable

Specifies whether an automatic tone will be generated for all active keys. This may be null in Common.StatusChangedEvent if unchanged.

Type: boolean, null
Default: null

keyboard/autoBeepMode/inactiveAvailable

Specifies whether an automatic tone will be generated for all inactive keys. This may be null in Common.StatusChangedEvent if unchanged.

Type: boolean, null
Default: null

textTerminal

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

Type: object, null
Default: null

textTerminal/keyboard

Specifies the state of the keyboard in the text terminal unit. This property will be null in Common.Status if the keyboard is not available, otherwise one of the following values:

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

Type: string, null
Default: null

textTerminal/keyLock

Specifies the state of the keyboard lock of the text terminal unit. This property will be null in Common.Status if the keyboard lock switch is not available, otherwise one of the following values:

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

Type: string, null
Default: null

textTerminal/displaySizeX

Specifies the horizontal size of the display of the text terminal unit (the number of columns that can be displayed). This property will be null in Common.StatusChangedEvent if unchanged.

Type: integer, null
Minimum: 0
Default: null

textTerminal/displaySizeY

Specifies the vertical size of the display of the text terminal unit (the number of rows that can be displayed). This property will be null in Common.StatusChangedEvent if unchanged.

Type: integer, null
Minimum: 0
Default: null

printer

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

Type: object, null
Default: null

printer/media

Specifies the state of the print media (i.e. receipt, statement, passbook, etc.) as one of the following values. This property will be null in Common.Status for journal printers or if 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.

Type: string, null
Default: null

printer/paper

Specifies the state of paper supplies as one of the following values. Each individual supply state will be null in Common.Status 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.

Type: object, null
Default: null

printer/paper/upper

The state of the upper paper supply.

Type: string, null
Default: null

printer/paper/lower

The state of the lower paper supply.

Type: string, null
Default: null

printer/paper/external

The state of the external paper supply.

Type: string, null
Default: null

printer/paper/aux

The state of the auxiliary paper supply.

Type: string, null
Default: null

printer/paper/aux2

The state of the second auxiliary paper supply.

Type: string, null
Default: null

printer/paper/park

The state of the parking station paper supply.

Type: string, null
Default: null

printer/paper/vendorSpecificPaperSupply (example name)

The state of the additional vendor specific paper supplies.

Type: string, null
Default: null

printer/toner

Specifies the state of the toner or ink supply or the state of the ribbon. The property will be null in Common.Status if the capability is not supported by device, otherwise one of the following:

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

Type: string, null
Default: null

printer/ink

Specifies the status of the stamping ink in the printer. The property will be null in Common.Status if the capability is not supported by device, otherwise one of the following:

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

Type: string, null
Default: null

printer/lamp

Specifies the status of the printer imaging lamp. The property will be null in Common.Status if the capability is not supported by device, otherwise one of the following:

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

Type: string, null
Default: null

printer/mediaOnStacker

The number of media on the stacker; applicable only to printers with stacking capability therefore null if not applicable.

Type: integer, null
Minimum: 0
Default: null

printer/paperType

Specifies the type of paper loaded as one of the following. Only applicable properties are reported. This may be null in Common.StatusChangedEvent if unchanged.

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

Type: object, null
Default: null

printer/paperType/upper

The upper paper supply paper type.

Type: string, null
Default: null

printer/paperType/lower

The lower paper supply paper type.

Type: string, null
Default: null

printer/paperType/external

The external paper supply paper type.

Type: string, null
Default: null

printer/paperType/aux

The auxiliary paper supply paper type.

Type: string, null
Default: null

printer/paperType/aux2

The second auxiliary paper supply paper type.

Type: string, null
Default: null

printer/paperType/park

The parking station paper supply paper type.

Type: string, null
Default: null

printer/paperType/exampleProperty1 (example name)

The additional vendor specific paper types.

Type: string, null
Default: null

printer/blackMarkMode

Specifies the status of the black mark detection and associated functionality. The property is null if 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.

Type: string, null
Default: null

barcodeReader

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

Type: object, null
Default: null

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.

Type: string
Required

biometric

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

Type: object, null
Default: null

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).

This property is null if the physical device does not support the ability to report whether or not a subject is on the scanning position.

Type: string, null
Default: null

biometric/capture

Indicates whether scanned biometric data has been captured using the Biometric.Read and is currently stored and ready for comparison. This will be set to false when scanned data is cleared using the Biometric.Clear. This may be null in Common.StatusChangedEvent if unchanged.

Type: boolean, null
Default: null

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. This property is null if the property persistenceModes is null or both properties persist and clear are false. 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.

Type: string, null
Default: null

biometric/remainingStorage

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

Type: integer, null
Minimum: 0
Default: null

camera

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

Type: object, null
Default: null

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, the relevant property will be null. This property may be null in Common.StatusChangedEvent if unchanged.

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

Type: object, null
Default: null

camera/media/room

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

Type: string, null
Default: null

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.

Type: string, null
Default: null

camera/media/exitSlot

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

Type: string, null
Default: null

camera/media/vendorSpecificCameraMedia (example name)

Allows vendor specific cameras to be reported.

Type: string, null
Default: null

camera/cameras

Specifies the state of the cameras as one of the following. The relevant property will be null if not supported and this property may be null in Common.StatusChangedEvent if unchanged.

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

Type: object, null
Default: null

camera/cameras/room

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

Type: string, null
Default: null

camera/cameras/person

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

Type: string, null
Default: null

camera/cameras/exitSlot

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

Type: string, null
Default: null

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 relevant camera's property is 0. Properties may be null in Common.StatusChangedEvent if unchanged.

Type: object, null
Default: null

camera/pictures/room

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

Type: integer, null
Minimum: 0
Default: null

camera/pictures/person

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

Type: integer, null
Minimum: 0
Default: null

camera/pictures/exitSlot

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

Type: integer, null
Minimum: 0
Default: null

camera/pictures/vendorSpecificCameraPictures (example name)

Allows vendor specific cameras to be reported.

Type: integer, null
Minimum: 0
Default: null

lights

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

Type: object, null
Default: null

lights/cardReader

Card Reader Light. This property is null if not applicable.

Type: object, null
Default: null

lights/cardReader/right (example name)

Indicates the light position. It can be one of the following:

  • 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.
  • default - The default position.
  • ^[a-zA-Z]([a-zA-Z0-9]*)$ - The vendor specific position.

Type: object
MinProperties: 1
Name Pattern: ^left$|^right$|^center$|^top$|^bottom$|^front$|^rear$|^default$|^[a-zA-Z]([a-zA-Z0-9]*)$

lights/cardReader/right/flashRate

The light flash rate. This may be null in a Common.StatusChangedEvent if unchanged, otherwise 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).

Type: string, null
Default: null

lights/cardReader/right/color

The light color. This property can be null if not supported, only supports just one color or in a Common.StatusChangedEvent if unchanged, otherwise 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.

Type: string, null
Default: null

lights/cardReader/right/direction

The light direction. This property can be null if not supported or in a Common.StatusChangedEvent if unchanged, otherwise one of the following values:

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

Type: string, null
Default: null

lights/pinPad

Pin Pad Light. This property is null if not applicable.

Type: object, null
Default: null

lights/notesDispenser

Notes Dispenser Light. This property is null if not applicable.

Type: object, null
Default: null

lights/coinDispenser

Coin Dispenser Light. This property is null if not applicable.

Type: object, null
Default: null

lights/receiptPrinter

Receipt Printer Light. This property is null if not applicable.

Type: object, null
Default: null

lights/passbookPrinter

Passbook Printer Light. This property is null if not applicable.

Type: object, null
Default: null

lights/envelopeDepository

Envelope Depository Light. This property is null if not applicable.

Type: object, null
Default: null

lights/checkUnit

Check Unit Light. This property is null if not applicable.

Type: object, null
Default: null

lights/billAcceptor

Bill Acceptor Light. This property is null if not applicable.

Type: object, null
Default: null

lights/envelopeDispenser

Envelope Dispenser Light. This property is null if not applicable.

Type: object, null
Default: null

lights/documentPrinter

Document Printer Light. This property is null if not applicable.

Type: object, null
Default: null

lights/coinAcceptor

Coin Acceptor Light. This property is null if not applicable.

Type: object, null
Default: null

lights/scanner

Scanner Light. This property is null if not applicable.

Type: object, null
Default: null

lights/contactless

Contactless Reader Light. This property is null if not applicable.

Type: object, null
Default: null

lights/cardReader2

Card Reader 2 Light. This property is null if not applicable.

Type: object, null
Default: null

lights/notesDispenser2

Notes Dispenser 2 Light. This property is null if not applicable.

Type: object, null
Default: null

lights/billAcceptor2

Bill Acceptor 2 Light. This property is null if not applicable.

Type: object, null
Default: null

lights/statusGood

Status Indicator light - Good. This property is null if not applicable.

Type: object, null
Default: null

lights/statusWarning

Status Indicator light - Warning. This property is null if not applicable.

Type: object, null
Default: null

lights/statusBad

Status Indicator light - Bad. This property is null if not applicable.

Type: object, null
Default: null

lights/statusSupervisor

Status Indicator light - Supervisor. This property is null if not applicable.

Type: object, null
Default: null

lights/statusInService

Status Indicator light - In Service. This property is null if not applicable.

Type: object, null
Default: null

lights/fasciaLight

Fascia Light. This property is null if not applicable.

Type: object, null
Default: null

lights/vendorSpecificLight (example name)

Additional vendor specific lights.

Type: object, null
Default: null

banknoteNeutralization

The global status of the BanknoteNeutralization. If this property is null in Common.Status, BanknoteNeutralization is not supported. It might be null in Common.StatusChangedEvent but that does not mean the interface is not supported, only that its properties haven't changed.

Type: object, null
Default: null

banknoteNeutralization/state

The global state of the BanknoteNeutralization. This global state can be specified more precisely by using the optional property submode

Type: object
Required

banknoteNeutralization/state/mode

The global state of the BanknoteNeutralization.

  • fault - A system fault occurred or due to a hardware error or other condition, the status cannot be determined.
  • armed - The protection is now armed.
  • disarmed - The protection is now disarmed.
  • neutralizationTriggered - The neutralization trigger occurred.

It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/state/submode

Additional information related to the current mode of the BanknoteNeutralization. If this property is null, it is not applicable in the current context or it has not changed.

  • allSafeSensorsIgnored - Intentionally the protection is now partially armed in response to SetProtection "ignoreAllSafeSensors". All the safe sensors are ignored meanwhile the BanknoteNeutralization in the Storage Unit remains armed.
  • armPending - The protection activation is intentionally delayed by configuration.

It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/safeDoor

The state of the safe door viewed by the sensors dedicated to the BanknoteNeutralization.

  • fault - A fault has occurred on this sensor.
  • doorOpened - The door is opened.
  • doorClosed - The door is closed.
  • disabled - This sensor is disabled by configuration.

It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/safeBolt

The state of the safe bolt viewed by the sensors dedicated to the BanknoteNeutralization.

  • fault - A fault has occurred on this sensor.
  • boltUnlocked - The bolt is unlocked.
  • boltLocked - The bolt is locked.
  • disabled - This sensor is disabled by configuration.

It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/tilt

Specifies the tilt state as one of the following values:

  • fault - A fault has occurred on this sensor.
  • notTilted - It is in normal operating position.
  • tilted - It has been tilted from its normal operating position.
  • disabled - This sensor is disabled by configuration.

It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/light

Specifies the light sensing as one of the following values:

  • fault - A fault has occurred on this sensor.
  • notConfigured - The light module is found but it is not enabled by configuration.
  • detected - Light is detected.
  • notDetected - No light is detected.
  • disabled - This sensor is disabled by configuration.

If the light module is not supported, null will be reported in Common.Status. It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/gas

Specifies the gas sensing as one of the following values:

  • initializing - The status is not available yet. It is important to mention that the warm-up and calibration of the gas sensor can take a few minutes.
  • fault - A fault has occurred on this sensor.
  • notConfigured - The gas module is found but it is not enabled by configuration.
  • notDetected - No gas detected.
  • partialWarningLevel - A warning level of gas is partially detected.
  • warningLevel - A warning level of gas is undoubtedly detected.
  • partialCriticalLevel - A critical level of gas is partially detected.
  • criticalLevel - A critical level of gas is undoubtedly detected.
  • disabled - This sensor is disabled by configuration.

If the gas module is not supported, null will be reported in Common.Status. It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/temperature

Specifies the temperature sensing as one of the following values:

  • fault - A fault has occurred on this sensor.
  • ok - The temperature is in the operating range.
  • tooCold - Too cold temperature.
  • tooHot - Too hot temperature.
  • disabled - This sensor is disabled by configuration.

It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/seismic

Specifies the seismic sensing in the BanknoteNeutralization as one of the following values:

  • fault - A fault has occurred on this sensor.
  • notConfigured - The seismic sensor is found but it is not enabled by configuration.
  • notDetected - No seismic activity detected.
  • warningLevel - A warning level of seismic activity has been detected.
  • criticalLevel - A critical level of seismic activity has been detected.
  • disabled - This sensor is disabled by configuration.

If the seismic module is not supported, null will be reported in Common.Status. It might be null in Common.StatusChangedEvent if it has not changed.

Type: string, null
Default: null

banknoteNeutralization/customInputs

A list of state for one or more custom input accordingly to those defined in CustomInputs in Capabilities. If there is no available configured Custom inputs, null will be reported in Common.Status It might be null in Common.StatusChangedEvent if it has not changed.

Type: object, null
Default: null

banknoteNeutralization/customInputs/disableGas (example name)

Describes what an input is capable of or can be configured to handle:

The following standard names are defined:

  • maintenance - Request the Banknote Neutralization to go in maintenance mode.
  • triggerNeutralization - Request the Banknote Neutralization to trigger the neutralization.
  • disableGas - Request the Banknote Neutralization to disable the gas detection.
  • disableSeismic - Request the Banknote Neutralization to disable the seismic detection.
  • disableSafeDoorAttack - Request the Banknote Neutralization to disable the safe door attack detection.

Additional non-standard input type names are also allowed:

  • oem[A-Z][a-zA-Z]* - a non standard input type name.

Type: object
Name Pattern: ^(maintenance|triggerNeutralization|disableGas|disableSeismic|disableSafeDoorAttack|oem[A-Z][a-zA-Z]*)$

banknoteNeutralization/customInputs/disableGas/inputState

Specifies the status of a custom input as one of the following values:

  • fault - A fault has occurred on the custom input, the status cannot be determined.
  • ok - The custom input is in a non-triggered state.
  • triggered - The custom input has been triggered.
  • disabled - The custom input is disabled by configuration.

Type: string
Default: "disabled"

banknoteNeutralization/powerSupply

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

Type: object, null
Default: null

banknoteNeutralization/powerSupply/info

Information that can be generically applied to module providing power ranging from a simple non-rechargeable battery to a more complex device such as a UPS. This will be null if is not supported.

Type: object, null
Default: null

banknoteNeutralization/powerSupply/info/powerInStatus

Specify the input power or mains power status. Specified as one of the following:

  • powering - The input power source is live and supplying power to the power supply module.
  • noPower - The input power source fails and no power to the power supply module. This property may be null in Common.StatusChangedEvent if unchanged.

Type: string, null
Default: null

banknoteNeutralization/powerSupply/info/powerOutStatus

Specify the output power status. Specified as one of the following:

  • powering - The power supply module is powering to the connected devices.
  • noPower - The power supply module is not supplying power to the connected devices. This property may be null in Common.StatusChangedEvent if unchanged.

Type: string, null
Default: null

banknoteNeutralization/powerSupply/info/batteryStatus

The charge level of the battery. Specified as one of the following:

  • full - The battery charge level is full, either the battery is new or fully charged for a rechargeable battery.
  • low - Although the battery level is still operational, this is an advance notice which should trigger a maintenance schedule without delay.
  • operational - The charge level is nominally between the levels "full" and "low".
  • critical - The battery level is no longer operational, this is an alert which should trigger maintenance without delay. Consider that the device may also not be powered properly.
  • failure - A battery fault detected. The device powered by the battery is no longer powered properly. Immediate maintenance should be performed. This property may be null in Common.StatusChangedEvent if unchanged or if the device does not have a battery.

Type: string, null
Default: null

banknoteNeutralization/powerSupply/info/batteryChargingStatus

The charging status of the battery. This will be null if the battery is not rechargeable. Specified as one of the following:

  • charging - The battery is charging power. When the battery is fully charged, the state changes to "notCharging" and the property BatteryStatus reports "full".
  • discharging - The battery is discharging power.
  • notCharging - The battery is not charging power. This property may be null in Common.StatusChangedEvent if unchanged or if the battery is not rechargeable.

Type: string, null
Default: null

banknoteNeutralization/powerSupply/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 the power saving mode has not been activated. This property is null if power save control is not supported or Common.StatusChangedEvent if unchanged..

Type: integer, null
Minimum: 0
Default: null

banknoteNeutralization/warnings

This indicates warnings that require special attention but banknote neutralization is still operational. Each status is reflected by a boolean value which is true if the warning status is detected otherwise it is false.

Type: object, null
Default: null

banknoteNeutralization/warnings/protectionArmingFault

At least one BanknoteNeutralization protection of a Storage Unit stayed disarmed after attempting to arm it.

Type: boolean
Default: false

banknoteNeutralization/warnings/protectionDisarmingFault

At least one BanknoteNeutralization protection of a Storage Unit stayed armed after attempting to disarm it.

Type: boolean
Default: false

banknoteNeutralization/warnings/externalMainPowerOutage

A main power outage of the BanknoteNeutralization occurred.

Type: boolean
Default: false

banknoteNeutralization/warnings/storageUnitLowPowerSupply

At least the power supply of one BanknoteNeutralization of a Storage Unit is low.

Type: boolean
Default: false

banknoteNeutralization/warnings/armedAutonomous

The protection is armed but at least one BanknoteNeutralization of a Storage Unit runs in an autonomous mode.

Type: boolean
Default: false

banknoteNeutralization/warnings/armedAlarm

The protection is armed but the BanknoteNeutralization is in alarm mode.

Type: boolean
Default: false

banknoteNeutralization/warnings/gasWarningLevel

A warning level of gas is detected.

Type: boolean
Default: false

banknoteNeutralization/warnings/seismicActivityWarningLevel

A warning level of the seismic activity is detected.

Type: boolean
Default: false

banknoteNeutralization/errors

This indicates errors reflect reasons of failure requiring immediate attention. Each status is reflected by a boolean value which is true if the error status is detected otherwise it is false. If one of them is true, banknote neutralization no longer works under normal conditions and may no longer be fully operational.

Type: object, null
Default: null

banknoteNeutralization/errors/protectionEnablingFailure

A critical error occurred while arming it.

Type: boolean
Default: false

banknoteNeutralization/errors/protectionDisarmingFailure

A critical error occurred while disarming it.

Type: boolean
Default: false

banknoteNeutralization/errors/storageUnitPowerSupplyFailure

There is a failure of at least one BanknoteNeutralization power supply of a Storage Unit.

Type: boolean
Default: false

banknoteNeutralization/errors/backupBatteryFailure

There is a failure of the backup battery.

Type: boolean
Default: false

banknoteNeutralization/errors/gasCriticalLevel

A critical level of gas is detected.

Type: boolean
Default: false

banknoteNeutralization/errors/light

Light is detected.

Type: boolean
Default: false

banknoteNeutralization/errors/tilted

At least one BanknoteNeutralization unit has been tilted from its normal operating position.

Type: boolean
Default: false

banknoteNeutralization/errors/seismicActivityCriticalLevel

A critical level of the seismic activity is detected.

Type: boolean
Default: false

auxiliaries

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

Type: object, null
Default: null

auxiliaries/operatorSwitch

Specifies the state of the Operator switch.

  • run - The switch is in run mode.
  • maintenance - The switch is in maintenance mode.
  • supervisor - The switch is in supervisor mode.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/tamperSensor

Specifies the state of the Tamper sensor.

  • off - There is no indication of a tampering attempt.
  • on - There has been a tampering attempt.

This property is null if not applicable.

Type: string, null
Default: null

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:

  • off - There is no indication of a tampering attempt.
  • on - There has been a tampering attempt.

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/proximitySensor

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

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/enhancedAudioSensor

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

  • present - There is a headset connected.
  • notPresent - There is no headset connected.

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/consumerDisplaySensor

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

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/operatorCallButtonSensor

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

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/handsetSensor

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

  • onTheHook - The Handset is on the hook.
  • offTheHook - The Handset is off the hook.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/headsetMicrophoneSensor

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

  • present - There is a headset microphone connected.
  • notPresent - There is no headset microphone connected.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/fasciaMicrophoneSensor

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

  • off - The Fascia Microphone is turned off.
  • on - The Fascia Microphone is turned on.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/cabinetDoor

Specifies the overall state of the Cabinet Doors. 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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/openClosedIndicator

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

  • closed - The terminal is closed for a consumer.
  • open - The terminal is open to be used by a consumer.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/audio

Specifies the state of the Audio Indicator. This property is null if not applicable.

Type: object, null
Default: null

auxiliaries/audio/rate

Specifies the state of the Audio Indicator as one of the following values. This may be null in Common.StatusChangedEvent if unchanged.

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/audio/signal

Specifies the Audio sound as one of the following values. This may be null in Common.StatusChangedEvent if unchanged.

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/heating

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

  • off - The internal heating is turned off.
  • on - The internal heating is turned on.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/consumerDisplayBacklight

Specifies the Consumer Display Backlight as one of the following:

  • off - The Consumer Display Backlight is turned off.
  • on - Consumer Display Backlight is turned on.

This property is null if not applicable.

Type: string, null
Default: null

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:

  • off - The Signage Display is turned off.
  • on - The Signage Display is turned on.

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/volume

Specifies the value of the Volume Control. 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. This property is null if not applicable.

Type: integer, null
Minimum: 1
Maximum: 1000
Default: null

auxiliaries/UPS

Specifies the state of the Uninterruptible Power Supply. This property is null if not applicable. Properties contained in this property may be null in Common.StatusChangedEvent if unchanged.

Type: object, null
Default: null

auxiliaries/UPS/low

The charge level of the UPS is low.

Type: boolean, null
Default: null

auxiliaries/UPS/engaged

The UPS is engaged.

Type: boolean, null
Default: null

auxiliaries/UPS/powering

The UPS is powering the system.

Type: boolean, null
Default: null

auxiliaries/UPS/recovered

The UPS was engaged when the main power went off.

Type: boolean, null
Default: null

auxiliaries/audibleAlarm

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

  • off - The Alarm is turned off.
  • on - The Alarm is turned on.

This property is null if not applicable.

Type: string, null
Default: null

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:

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

This property is null if not applicable.

Type: string, null
Default: null

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 following values:

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

This property is null if not applicable.

Type: string, null
Default: null

auxiliaries/microphoneVolume

Specifies the value of the Microphone Volume Control. 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. This property is null if not applicable.

Type: integer, null
Minimum: 1
Maximum: 1000
Default: null

deposit

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

Type: object, null
Default: null

deposit/depTransport

Specifies the state of the deposit transport mechanism that transports the envelope into the deposit container. This property is null in Common.Status if the device has no deposit transport, otherwise the following values are possible:

  • ok - The deposit transport is in a good state.
  • inoperative - The deposit transport is inoperative due to a hardware failure or media jam.
  • unknown - Due to a hardware error or other condition the state of the deposit transport cannot be determined.

Type: string, null
Default: null

deposit/envDispenser

Specifies the state of the envelope dispenser.

This property is null in Common.Status if the device has no envelope dispenser, otherwise the following values are possible:

  • ok- The envelope dispenser is present and in a good state.
  • inoperative - The envelope dispenser is present but in an inoperable state. No envelopes can be dispensed.
  • unknown - Due to a hardware error or other condition, the state of the envelope dispenser cannot be determined.

Type: string, null
Default: null

deposit/printer

Specifies the state of the printer.

This property is null in Common.Status if the device has no printer, otherwise the following values are possible:

  • ok- The printer is present and in a good state.
  • inoperative - The printer is in an inoperable state.
  • unknown - Due to a hardware error or other condition, the state of the printer cannot be determined.

Type: string, null
Default: null

deposit/toner

Specifies the state of the toner (or ink) for the printer. This may be null in Common.Status if the physical device does not support printing or the capability to report the status of the toner/ink is not supported by the device, otherwise the following values are possible:

  • 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.
  • unknown - Status of toner or ink supply or the ribbon cannot be determined with the device in its current state.

Type: string, null
Default: null

deposit/shutter

Specifies the state of the shutter or door.

This may be null in Common.Status if the physical device has no shutter, otherwise the following values are possible:

  • closed - The shutter is closed.
  • open - The shutter is open.
  • jammed - The shutter is jammed.
  • unknown - Due to a hardware error or other condition, the state of the shutter cannot be determined.

Type: string, null
Default: null

deposit/depositLocation

Specifies the location of the item deposited at the end of the last Deposit.Entry command.

This may be null in Common.Status if not supported or in Common.StatusChangedEvent if unchanged, otherwise the following values are possible:

  • unknown - Cannot determine the location of the last deposited item.
  • container - The item is in the container.
  • transport - The item is in the transport.
  • printer - The item is in the printer.
  • shutter - The item is at the shutter (available for removal).
  • none - No item was entered on the last Deposit.Entry.
  • removed - The item was removed.

Type: string, null
Default: null

vendorMode

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

Type: object, null
Default: null

vendorMode/device

Specifies the status of the Vendor Mode Service. This property may be null in events if the status did not change, otherwise will be one of the following values:

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

Type: string, null
Default: null

vendorMode/service

Specifies the service state. This property may be null in events if the state did not change, otherwise will be 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.

Type: string, null
Default: null

vendorApplication

Status information for XFS4IoT services implementing the Vendor Application interface. This will be null in Common.Status if the interface is not supported.

Type: object, null
Default: null

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.

Type: string
Required

powerManagement

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

Type: object, null
Default: null

powerManagement/info

Information that can be generically applied to module providing power ranging from a simple non-rechargeable battery to a more complex device such as a UPS. This will be null if is not supported.

Type: object, null
Default: null

powerManagement/info/powerInStatus

Specify the input power or mains power status. Specified as one of the following:

  • powering - The input power source is live and supplying power to the power supply module.
  • noPower - The input power source fails and no power to the power supply module. This property may be null in Common.StatusChangedEvent if unchanged.

Type: string, null
Default: null

powerManagement/info/powerOutStatus

Specify the output power status. Specified as one of the following:

  • powering - The power supply module is powering to the connected devices.
  • noPower - The power supply module is not supplying power to the connected devices. This property may be null in Common.StatusChangedEvent if unchanged.

Type: string, null
Default: null

powerManagement/info/batteryStatus

The charge level of the battery. Specified as one of the following:

  • full - The battery charge level is full, either the battery is new or fully charged for a rechargeable battery.
  • low - Although the battery level is still operational, this is an advance notice which should trigger a maintenance schedule without delay.
  • operational - The charge level is nominally between the levels "full" and "low".
  • critical - The battery level is no longer operational, this is an alert which should trigger maintenance without delay. Consider that the device may also not be powered properly.
  • failure - A battery fault detected. The device powered by the battery is no longer powered properly. Immediate maintenance should be performed. This property may be null in Common.StatusChangedEvent if unchanged or if the device does not have a battery.

Type: string, null
Default: null

powerManagement/info/batteryChargingStatus

The charging status of the battery. This will be null if the battery is not rechargeable. Specified as one of the following:

  • charging - The battery is charging power. When the battery is fully charged, the state changes to "notCharging" and the property BatteryStatus reports "full".
  • discharging - The battery is discharging power.
  • notCharging - The battery is not charging power. This property may be null in Common.StatusChangedEvent if unchanged or if the battery is not rechargeable.

Type: string, null
Default: null

powerManagement/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 the power saving mode has not been activated. This property is null if power save control is not supported or Common.StatusChangedEvent if unchanged..

Type: integer, null
Minimum: 0
Default: null

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 2.0)
This message does not define any properties.

Completion Message

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

interfaces

Array of interfaces supported by this XFS4IoT service.

Type: array (object)
Required

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.
  • Biometric - Biometric interface.
  • Check - Check interface.
  • MixedMedia - MixedMedia interface.
  • Deposit - Deposit interface.
  • BanknoteNeutralization - Intelligent Banknote Neutralization System interface.
  • German - German country specific interface.

Type: string
Required

interfaces/commands

The commands supported by the service.

Type: object
Required

interfaces/commands/CardReader.ReadRawData (example name)

A command name.

Type: object
Name Pattern: ^[0-9A-Za-z]*\.[0-9A-Za-z]*$

interfaces/commands/CardReader.ReadRawData/versions

The versions of the command supported by the service. There will be one item for each major version supported. The minor version number qualifies the exact version of the message the service supports.

Type: array (string)
Pattern: ^[1-9][0-9]*\.([1-9][0-9]*|0)$
Required

interfaces/events

The events (both event and unsolicited) supported by the service. May be null if no events are supported.

Type: object, null
Default: null

interfaces/events/CardReader.MediaInsertedEvent (example name)

An event name.

Type: object
Name Pattern: ^[0-9A-Za-z]*\.[0-9A-Za-z]*$

interfaces/events/CardReader.MediaInsertedEvent/versions

The versions of the event supported by the service. There will be one item for each major version supported. The minor version number qualifies the exact version of the message the service supports.

Type: array (string)
Pattern: ^[1-9][0-9]*\.([1-9][0-9]*|0)$
Required

interfaces/maximumRequests

Specifies the maximum number of requests which can be queued by the Service. This will be 0 if the maximum number of requests is unlimited.

Type: integer
Minimum: 0
Default: 0

common

Capability information common to all XFS4IoT services.

Type: object
Required

common/serviceVersion

Specifies the Service Version.

Type: string
Required

common/deviceInformation

Array of deviceInformation structures. If the service uses more than one device there will be on array element for each device.

Type: array (object)
Required

common/deviceInformation/modelName

Specifies the device model name. The property is null if the device model name is unknown.

Type: string, null
Default: null

common/deviceInformation/serialNumber

Specifies the unique serial number of the device. The property is null if the serial number is unknown.

Type: string, null
Default: null

common/deviceInformation/revisionNumber

Specifies the device revision number. The property is null if the device revision number is unknown.

Type: string, null
Default: null

common/deviceInformation/modelDescription

Contains a description of the device. The property is null if the model description is unknown.

Type: string, null
Default: null

common/deviceInformation/firmware

Array of firmware structures specifying the names and version numbers of the firmware that is present. Single or multiple firmware versions can be reported. If the firmware versions are not reported, then this property is null.

Type: array (object), null
Default: null

common/deviceInformation/firmware/firmwareName

Specifies the firmware name. The property is null if the firmware name is unknown.

Type: string, null
Default: null

common/deviceInformation/firmware/firmwareVersion

Specifies the firmware version. The property is null if the firmware version is unknown.

Type: string, null
Default: null

common/deviceInformation/firmware/hardwareRevision

Specifies the hardware revision. The property is null if the hardware revision is unknown.

Type: string, null
Default: null

common/deviceInformation/software

Array of software structures specifying the names and version numbers of the software components that are present. Single or multiple software versions can be reported. If the software versions are not reported, then this property is null.

Type: array (object), null
Default: null

common/deviceInformation/software/softwareName

Specifies the software name. The property is null if the software name is unknown.

Type: string, null
Default: null

common/deviceInformation/software/softwareVersion

Specifies the software version. The property is null if the software version is unknown.

Type: string, null
Default: null

common/powerSaveControl

Specifies whether power saving control is available.

Type: boolean
Default: false

common/antiFraudModule

Specifies whether the anti-fraud module is available.

Type: boolean
Default: false

common/endToEndSecurity

If present then end to end security is supported. The sub-properties detail exactly how it is supported and what level of support is enabled. Also see common.StatusProperties.endToEndSecurity for the current status of end to end security, such as if it is being enforced, or if configuration is required.

If this is null then end to end security is not supported by this service.

Type: object, null
Default: null

common/endToEndSecurity/required

Specifies the level of support for end to end security

  • ifConfigured - The device is capable of supporting E2E security, but it will not be enforced if not configured, for example because the required keys are not loaded.
  • always - E2E security is supported and enforced at all times. Failure to supply the required security details will lead to errors. If E2E security is not correctly configured, for example because the required keys are not loaded, all secured commands will fail with an error.

Type: string
Required

common/endToEndSecurity/hardwareSecurityElement

Specifies if this device has a Hardware Security Element (HSE) which validates the security token. If this property is false it means that validation is performed in software.

Type: boolean
Required

common/endToEndSecurity/responseSecurityEnabled

Specifies if this device will return a security token as part of the response data to commands that support end to end security, for example, to validate the result of a dispense operation. This property is null in Common.Status if the device is incapable of returning a response token, otherwise one of the following values:

  • ifConfigured - The device is capable of supporting E2E security if correctly configured. If E2E security has not been correctly configured, for example because the required keys are not loaded, commands will complete without a security token.
  • always - A security token will be included with command responses. If E2E security is not correctly configured, for example because the required keys are not loaded, the command will complete with an error.

Type: string

common/endToEndSecurity/commands

Array of commands which require an E2E token to authorize. These commands will fail if called without a valid token.

The commands that can be listed here depends on the XFS4IoT standard, but it's possible that the standard will change over time, so for maximum compatibility an application should check this property before calling a command.

Note that this only includes commands that require a token. Commands that take a nonce and return a token will not be listed here. Those commands can be called without a nonce and will continue to operate in a compatible way.

Type: array (string)
Pattern: ^[A-Za-z][A-Za-z0-9]*\.[A-Za-z][A-Za-z0-9]*$
Required

common/endToEndSecurity/commandNonceTimeout

If this device supports end to end security and can return a command nonce with the command Common.GetCommandNonce, and the device automatically clears the command nonce after a fixed length of time, this property will report the number of seconds between returning the command nonce and clearing it.

The value is given in seconds but it should not be assumed that the timeout will be accurate to the nearest second. The nonce may also become invalid before the timeout, for example because of a power failure.

The device may impose a timeout to reduce the chance of an attacker re-using a nonce value or a token. This timeout will be long enough to support normal operations such as dispense and present including creating the required token on the host and passing it to the device. For example, a command nonce might time out after one hour (that is, 3600 seconds).

In all other cases, commandNonceTimeout will have a value of zero. Any command nonce will never timeout. It may still become invalid, for example because of a power failure or when explicitly cleared using the Common.ClearCommandNonce command.

Type: integer
Minimum: 0
Required

common/persistentDataStore

Specifies the capabilities of the persistent data store supported by the service. The persistent data store is used to store client data and assets such as forms. This property is null if persistent data storage is not supported.

Type: object, null
MinProperties: 1
Default: null

common/persistentDataStore/capacity

Specifies the total number of Kilobytes that can be stored.

Clients should use this, in conjunction with the remaining status to determine how to make best use of the available space, for example, a client may elect to store all data where the service reports ample capacity or dynamically set and delete partial data when the available space is small.

If the service effectively has no practical persistent storage limit, for example when executing on a general purpose operating system with a large drive, the service may report a capacity value less than the drive size representing the persistent data size it can handle while remaining performant.

Type: integer
Minimum: 1

cardReader

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

Type: object, null
Default: null

cardReader/type

Specifies the type of the ID card unit as one of the following:

  • motor - The ID card unit is a motor driven card unit.
  • swipe - The ID card unit is a swipe (pull-through) card unit.
  • dip - The ID card unit is a dip card unit. This dip type is not capable of latching cards entered.
  • latchedDip - The ID card unit is a latched dip card unit. This device type is used when a dip card unit device supports chip communication. The latch ensures the consumer cannot remove the card during chip communication. Any card entered will automatically latch when a request to initiate a chip dialog is made (via the CardReader.ReadRawData command). The CardReader.Move command is used to unlatch the card.
  • contactless - The ID card unit is a contactless card unit, i.e. no insertion of the card is required.
  • intelligentContactless - The ID card unit is an intelligent contactless card unit, i.e. no insertion of the card is required and the card unit has built-in EMV or smart card application functionality that adheres to the EMVCo Contactless Specifications [Ref. cardreader-3] or individual payment system's specifications. The ID card unit is capable of performing both magnetic stripe emulation and EMV-like transactions.
  • permanent - The ID card unit is dedicated to a permanently housed chip card (no user interaction is available with this type of card).

Type: string
Required

cardReader/readTracks

Specifies the tracks that can be read by the card reader. May be null if not applicable.

Type: object, null
Default: null

cardReader/readTracks/track1

The card reader can access track 1.

Type: boolean
Default: false

cardReader/readTracks/track2

The card reader can access track 2.

Type: boolean
Default: false

cardReader/readTracks/track3

The card reader can access track 3.

Type: boolean
Default: false

cardReader/readTracks/watermark

The card reader can access the Swedish watermark track.

Type: boolean
Default: false

cardReader/readTracks/frontTrack1

The card reader can access front track 1.

Type: boolean
Default: false

cardReader/readTracks/frontImage

The card reader can read the front image of the card.

Type: boolean
Default: false

cardReader/readTracks/backImage

The card reader can read the back image of the card.

Type: boolean
Default: false

cardReader/readTracks/track1JIS

The card reader can access JIS I track 1.

Type: boolean
Default: false

cardReader/readTracks/track3JIS

The card reader can access JIS I track 3.

Type: boolean
Default: false

cardReader/readTracks/ddi

The card reader can provide dynamic digital identification of the magnetic strip.

Type: boolean
Default: false

cardReader/writeTracks

Specifies the tracks that can be written by the card reader. May be null if no tracks can be written.

Type: object, null
Default: null

cardReader/writeTracks/track1

The card reader can write on track 1.

Type: boolean
Default: false

cardReader/writeTracks/track2

The card reader can write on track 2.

Type: boolean
Default: false

cardReader/writeTracks/track3

The card reader can write on track 3.

Type: boolean
Default: false

cardReader/writeTracks/frontTrack1

The card reader can write on front track 1.

Type: boolean
Default: false

cardReader/writeTracks/track1JIS

The card reader can write on JIS I track 1.

Type: boolean
Default: false

cardReader/writeTracks/track3JIS

The card reader can write on JIS I track 3.

Type: boolean
Default: false

cardReader/chipProtocols

Specifies the chip card protocols that are supported by the card reader. May be null if none are supported.

Type: object, null
Default: null

cardReader/chipProtocols/chipT0

The card reader can handle the T=0 protocol.

Type: boolean
Default: false

cardReader/chipProtocols/chipT1

The card reader can handle the T=1 protocol.

Type: boolean
Default: false

cardReader/chipProtocols/chipProtocolNotRequired

The carder is capable of communicating with the chip without requiring the application to specify any protocol.

Type: boolean
Default: false

cardReader/chipProtocols/chipTypeAPart3

The card reader can handle the ISO 14443 (Part3) Type A contactless chip card protocol.

Type: boolean
Default: false

cardReader/chipProtocols/chipTypeAPart4

The card reader can handle the ISO 14443 (Part4) Type A contactless chip card protocol.

Type: boolean
Default: false

cardReader/chipProtocols/chipTypeB

The card reader can handle the ISO 14443 Type B contactless chip card protocol.

Type: boolean
Default: false

cardReader/chipProtocols/chipTypeNFC

The card reader can handle the ISO 18092 (106/212/424kbps) contactless chip card protocol.

Type: boolean
Default: false

cardReader/securityType

Specifies the type of security module as one of the following or null if the device has no security module.

  • mm - The security module is a MMBox.
  • cim86 - The security module is a CIM86.

Type: string, null
Default: null

cardReader/powerOnOption

Specifies the power-on (or off) capabilities of the device hardware as one of the following options (applicable only to motor driven ID card units). May be null if the device does not support power on (or off) options.

  • exit - The card will be moved to the exit position.
  • retain - The card will be moved to a retain storage unit.
  • exitThenRetain - The card will be moved to the exit position for a finite time, then if not taken, the card will be moved to a retain storage unit. The time for which the card remains at the exit position is vendor dependent.
  • transport - The card will be moved to the transport position.

If multiple retain storage units are present, the storage unit to which the card is retained is vendor specific.

Type: string, null
Default: null

cardReader/powerOffOption

Specifies the power-off capabilities of the device hardware. See powerOnOption.

Type: string, null
Default: null

cardReader/fluxSensorProgrammable

Specifies whether the Flux Sensor on the card unit is programmable.

Type: boolean
Default: false

cardReader/readWriteAccessFromExit

Specifies whether a card may be read or written after having been moved to the exit position with a CardReader.Move command. The card will be moved back into the card reader.

Type: boolean
Default: false

cardReader/writeMode

The write capabilities, with respect to whether the device can write low coercivity (loco) and/or high coercivity (hico) magnetic stripes. May be null if not applicable.

Type: object, null
Default: null

cardReader/writeMode/loco

Supports writing of loco magnetic stripes.

Type: boolean
Default: false

cardReader/writeMode/hico

Supports writing of hico magnetic stripes.

Type: boolean
Default: false

cardReader/writeMode/auto

The Service is capable of automatically determining whether loco or hico magnetic stripes should be written.

Type: boolean
Default: false

cardReader/chipPower

The chip power management capabilities (in relation to the user or permanent chip controlled by the Service. May be null if not applicable.

Type: object, null
Default: null

cardReader/chipPower/cold

The card reader can power on the chip and reset it (Cold Reset).

Type: boolean
Default: false

cardReader/chipPower/warm

The card reader can reset the chip (Warm Reset).

Type: boolean
Default: false

cardReader/chipPower/off

The card reader can power off the chip.

Type: boolean
Default: false

cardReader/memoryChipProtocols

The memory card protocols that are supported. May be null if not applicable.

Type: object, null
Default: null

cardReader/memoryChipProtocols/siemens4442

The device supports the Siemens 4442 Card Protocol (also supported by the Gemplus GPM2K card).

Type: boolean
Default: false

cardReader/memoryChipProtocols/gpm896

The device supports the Gemplus GPM 896 Card Protocol.

Type: boolean
Default: false

cardReader/positions

Specifies the target positions that are supported for the CardReader.Move command. This is independent of the storage units. May be null if not applicable.

Type: object, null
Default: null

cardReader/positions/exit

The device can move a card to the exit position. In this position, the card is accessible to the user.

Type: boolean
Default: false

cardReader/positions/transport

The device can move a card to the transport. In this position, the card is not accessible to the user. A service which supports this position must also support the exit position.

Type: boolean
Default: false

cardReader/cardTakenSensor

Specifies whether or not the card reader has the ability to detect when a card is taken from the exit slot by a user. If true, a CardReader.MediaRemovedEvent will be sent when the card is removed.

Type: boolean
Default: false

cashAcceptor

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

Type: object, null
Default: null

cashAcceptor/type

Supplies the type of CashAcceptor. The following values are possible:

  • tellerBill - The CashAcceptor is a Teller Bill Acceptor.
  • selfServiceBill - The CashAcceptor is a Self-Service Bill Acceptor.
  • tellerCoin - The CashAcceptor is a Teller Coin Acceptor.
  • selfServiceCoin - The CashAcceptor is a Self-Service Coin Acceptor.

Type: string
Required

cashAcceptor/maxCashInItems

Supplies the maximum number of items that can be accepted in a single CashAcceptor.CashIn command. This value reflects the hardware limitations of the device and therefore it does not change as part of the CashAcceptor.CashInStart command.

Type: integer
Minimum: 1
Default: 1

cashAcceptor/shutter

If true then the device has a shutter and explicit shutter control through the commands CashManagement.OpenShutter and CashManagement.CloseShutter is supported. The definition of a shutter will depend on the h/w implementation. On some devices where items are automatically detected and accepted then a shutter is simply a latch that is opened and closed, usually under implicit control by the Service. On other devices, the term shutter refers to a door, which is opened and closed to allow the customer to place the items onto a tray. If a Service cannot detect when items are inserted and there is a shutter on the device, then it must provide explicit application control of the shutter.

Type: boolean
Default: false

cashAcceptor/shutterControl

If true the shutter is controlled implicitly by the service.

If false the shutter must be controlled explicitly by the application using the CashManagement.OpenShutter and CashManagement.CloseShutter commands.

In either case the CashAcceptor.PresentMedia command may be used if the presentControl property is false.

This property is always true if the device has no shutter. This property applies to all shutters and all positions.

Type: boolean
Default: false

cashAcceptor/intermediateStacker

Specifies the number of items the intermediate stacker for cash-in can hold. Will be null if there is no intermediate stacker for cash-in available.

Type: integer, null
Minimum: 0
Default: null

cashAcceptor/itemsTakenSensor

Specifies whether the CashAcceptor can detect when items at the exit position are taken by the user. If true the Service generates an accompanying CashManagement.ItemsTakenEvent. If false this event is not generated. This property relates to all output positions.

Type: boolean
Default: false

cashAcceptor/itemsInsertedSensor

Specifies whether the CashAcceptor has the ability to detect when items have been inserted by the user. If true the service generates an accompanying CashManagement.ItemsInsertedEvent. If false this event is not generated. This relates to all input positions and should not be reported as true unless item insertion can be detected.

Type: boolean
Default: false

cashAcceptor/positions

Array of position capabilities for all positions configured in this service.

Type: array (object)
Required

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.

Type: string
Required

cashAcceptor/positions/usage

Indicates if a position is used to input, reject or rollback.

Type: object
Required

cashAcceptor/positions/usage/in

It is an input position.

Type: boolean
Default: false

cashAcceptor/positions/usage/refuse

It is an output position used to refuse items.

Type: boolean
Default: false

cashAcceptor/positions/usage/rollback

It is an output position used to rollback items.

Type: boolean
Default: false

cashAcceptor/positions/shutterControl

If true the shutter is controlled implicitly by the Service.

If false the shutter must be controlled explicitly by the application using the CashManagement.OpenShutter and CashManagement.CloseShutter commands.

In either case the CashAcceptor.PresentMedia command may be used if presentControl is false. The shutterControl property is always true if the described position has no shutter.

Type: boolean
Default: true

cashAcceptor/positions/itemsTakenSensor

Specifies whether or not the described position can detect when items at the exit position are taken by the user.

If true the service generates an accompanying CashManagement.ItemsTakenEvent. If false this event is not generated.

This property relates to output and refused positions.

Type: boolean
Default: false

cashAcceptor/positions/itemsInsertedSensor

Specifies whether the described position has the ability to detect when items have been inserted by the user.

If true the service generates an accompanying CashManagement.ItemsInsertedEvent. If false this event is not generated.

This property relates to all input positions.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas

Specifies the areas to which items may be retracted from this position. This is not reported if the device cannot retract.

Type: object, null
Default: null

cashAcceptor/positions/retractAreas/retract

Items may be retracted to a retract storage unit.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas/reject

Items may be retracted to a reject storage unit.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas/transport

Items may be retracted to the transport.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas/stacker

Items may be retracted to the intermediate stacker.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas/billCassettes

Items may be retracted to item cassettes, i.e. cash-in and recycle storage units. This property has been deprecated in favor of the property itemCassette.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas/cashIn

Items may be retracted to a cash-in storage unit.

Type: boolean
Default: false

cashAcceptor/positions/retractAreas/itemCassette

Items may be retracted to item cassettes, i.e. cash-in and recycle storage units.

Type: boolean
Default: false

cashAcceptor/positions/presentControl

Specifies how the presenting of media items is controlled.

If true then the CashAcceptor.PresentMedia command is not supported and items are moved to the output position for removal as part of the relevant command, e.g. CashAcceptor.CashIn or CashAcceptor.CashInRollback where there is implicit shutter control.

If false then items returned or rejected can be moved to the output position using the CashAcceptor.PresentMedia command, this includes items returned or rejected as part of a CashAcceptor.CashIn or CashAcceptor.CashInRollback operation. The CashAcceptor.PresentMedia command will open and close the shutter implicitly.

Type: boolean
Default: false

cashAcceptor/positions/preparePresent

Specifies how the presenting of items is controlled.

If false then items to be removed are moved to the output position as part of the relevant command. e.g. CashManagement.OpenShutter, CashAcceptor.PresentMedia or CashAcceptor.CashInRollback.

If true then items are moved to the output position using the CashAcceptor.PreparePresent command.

Type: boolean
Default: false

cashAcceptor/retractAreas

Specifies the area to which items may be retracted. If the device does not have a retract capability this will be null.

Type: object, null
Default: null

cashAcceptor/retractAreas/retract

The items may be retracted to a retract storage unit.

Type: boolean
Default: false

cashAcceptor/retractAreas/transport

The items may be retracted to the transport.

Type: boolean
Default: false

cashAcceptor/retractAreas/stacker

The items may be retracted to the intermediate stacker.

Type: boolean
Default: false

cashAcceptor/retractAreas/reject

The items may be retracted to a reject storage unit.

Type: boolean
Default: false

cashAcceptor/retractAreas/billCassette

The items may be retracted to cash-in and recycle storage units. This property has been deprecated in favor of the property itemCassette.

Type: boolean
Default: false

cashAcceptor/retractAreas/cashIn

Items may be retracted to cash-in storage units.

Type: boolean
Default: false

cashAcceptor/retractTransportActions

Specifies the actions which may be performed on items which have been retracted to the transport. If the device does not have the capability to retract items to the transport or move items from the transport this will be null.

Type: object, null
Default: null

cashAcceptor/retractTransportActions/present

The items may be presented.

Type: boolean
Default: false

cashAcceptor/retractTransportActions/retract

The items may be moved to a retract storage unit.

Type: boolean
Default: false

cashAcceptor/retractTransportActions/reject

The items may be moved to a reject storage unit.

Type: boolean
Default: false

cashAcceptor/retractTransportActions/billCassette

The items may be moved to the cash-in and recycle storage units. This property has been deprecated in favor of the property itemCassette.

Type: boolean
Default: false

cashAcceptor/retractStackerActions

Specifies the actions which may be performed on items which have been retracted to the stacker. If the device does not have the capability to retract items to the stacker or move items from the stacker this will be null.

Type: object, null
Default: null

cashAcceptor/cashInLimit

Specifies which cash-in limitations are supported for the CashAcceptor.CashInStart command. If the device does not have the capability to limit the amount or the number of items during cash-in operations this property is null.

Type: object, null
Default: null

cashAcceptor/cashInLimit/byTotalItems

The number of successfully processed cash-in items can be limited by specifying the total number of items.

Type: boolean
Default: false

cashAcceptor/cashInLimit/byAmount

The number of successfully processed cash-in items can be limited by specifying the maximum amount of a specific currency.

Type: boolean
Default: false

cashAcceptor/countActions

Specifies the count action supported by the CashAcceptor.CashUnitCount command. If the device does not support counting then this property is null.

Type: object, null
Default: null

cashAcceptor/countActions/individual

The counting of individual storage units is supported.

Type: boolean
Default: false

cashAcceptor/countActions/all

The counting of all storage units is supported.

Type: boolean
Default: false

cashAcceptor/retainAction

If counterfeit, inked or suspect items are supported by the Service (see classifications), this specifies whether such items are retained by the device if detected during a cash-in transaction. See acceptor for details of the impact on offering cash-in transactions if unable to retain items due to storage unit status.

This applies regardless of whether their specific note type is configured to not be accepted by CashAcceptor.ConfigureNoteTypes.

This property may be null if none of these note classifications are supported.

Type: object, null
Default: null

cashAcceptor/retainAction/counterfeit

Items classified as counterfeit are retained during a cash-in transaction.

Type: boolean
Default: false

cashAcceptor/retainAction/suspect

Items classified as suspect are retained during a cash-in transaction.

Type: boolean
Default: false

cashAcceptor/retainAction/inked

Items classified as inked are retained during a cash-in transaction.

Type: boolean
Default: false

cashDispenser

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

Type: object, null
Default: null

cashDispenser/type

Supplies the type of Dispenser. Following values are possible:

  • tellerBill - The Dispenser is a Teller Bill Dispenser.
  • selfServiceBill - The Dispenser is a Self-Service Bill Dispenser.
  • tellerCoin - The Dispenser is a Teller Coin Dispenser.
  • selfServiceCoin - The Dispenser is a Self-Service Coin Dispenser.

Type: string
Required

cashDispenser/maxDispenseItems

Supplies the maximum number of items that can be dispensed in a single dispense operation.

Type: integer
Minimum: 1
Required

cashDispenser/shutterControl

If true the shutter is controlled implicitly by the Service. If false the shutter must be controlled explicitly by the application using the CashManagement.OpenShutter and CashManagement.CloseShutter commands.

This property is always true if the device has no shutter. This property applies to all shutters and all output positions.

Type: boolean
Default: false

cashDispenser/retractAreas

Specifies the area to which items may be retracted. If the device does not have a retract capability this will be null.

Type: object, null
Default: null

cashDispenser/retractAreas/retract

The items may be retracted to a retract storage unit.

Type: boolean
Default: false

cashDispenser/retractAreas/transport

The items may be retracted to the transport.

Type: boolean
Default: false

cashDispenser/retractAreas/stacker

The items may be retracted to the intermediate stacker.

Type: boolean
Default: false

cashDispenser/retractAreas/reject

The items may be retracted to a reject storage unit.

Type: boolean
Default: false

cashDispenser/retractAreas/itemCassette

The items may be retracted to storage units which would be used during a Cash In transaction including recycling storage units.

Type: boolean
Default: false

cashDispenser/retractAreas/cashIn

The items may be retracted to storage units which would be used during a Cash In transaction not including recycling storage units.

Type: boolean
Default: false

cashDispenser/retractTransportActions

Specifies the actions which may be performed on items which have been retracted to the transport. If the device does not have the capability to retract items to the transport or move items from the transport this will be null.

Type: object, null
Default: null

cashDispenser/retractTransportActions/present

The items may be presented.

Type: boolean
Default: false

cashDispenser/retractTransportActions/retract

The items may be moved to a retract storage unit.

Type: boolean
Default: false

cashDispenser/retractTransportActions/reject

The items may be moved to a reject storage unit.

Type: boolean
Default: false

cashDispenser/retractTransportActions/itemCassette

The items may be moved to storage units which would be used during a Cash In transaction including recycling storage units.

Type: boolean
Default: false

cashDispenser/retractTransportActions/cashIn

The items may be moved to storage units which would be used during a Cash In transaction not including recycling storage units.

Type: boolean
Default: false

cashDispenser/retractStackerActions

Specifies the actions which may be performed on items which have been retracted to the stacker. If the device does not have the capability to retract items to the stacker or move items from the stacker this will be null.

Type: object, null
Default: null

cashDispenser/intermediateStacker

Specifies whether the Dispenser supports stacking items to an intermediate position before the items are moved to the exit position.

Type: boolean
Default: false

cashDispenser/itemsTakenSensor

Specifies whether the Dispenser can detect when items at the exit position are taken by the user. This applies to all output positions.

If true the Service generates an accompanying CashManagement.ItemsTakenEvent.

If false this event is not generated.

Type: boolean
Default: false

cashDispenser/positions

Specifies the Dispenser output positions which are available.

Type: object
Required

cashDispenser/positions/left

The Dispenser has a left output position.

Type: boolean
Default: false

cashDispenser/positions/right

The Dispenser has a right output position.

Type: boolean
Default: false

cashDispenser/positions/center

The Dispenser has a center output position.

Type: boolean
Default: false

cashDispenser/positions/top

The Dispenser has a top output position.

Type: boolean
Default: false

cashDispenser/positions/bottom

The Dispenser has a bottom output position.

Type: boolean
Default: false

cashDispenser/positions/front

The Dispenser has a front output position.

Type: boolean
Default: false

cashDispenser/positions/rear

The Dispenser has a rear output position.

Type: boolean
Default: false

cashDispenser/moveItems

Specifies the Dispenser move item options which are available. If not applicable, this property is null.

Type: object, null
Default: null

cashDispenser/moveItems/fromCashUnit

The Dispenser can dispense items from the storage units to the intermediate stacker while there are items on the transport.

Type: boolean
Default: false

cashDispenser/moveItems/toCashUnit

The Dispenser can retract items to the storage units while there are items on the intermediate stacker.

Type: boolean
Default: false

cashDispenser/moveItems/toTransport

The Dispenser can retract items to the transport while there are items on the intermediate stacker.

Type: boolean
Default: false

cashDispenser/moveItems/toStacker

The Dispenser can dispense items from the storage units to the intermediate stacker while there are already items on the intermediate stacker that have not been in customer access. Items remaining on the stacker from a previous dispense may first need to be rejected explicitly by the application if they are not to be presented.

Type: boolean
Default: false

cashManagement

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

Type: object, null
Default: null

cashManagement/cashBox

This property is only applicable to teller type devices. It specifies whether or not tellers have been assigned a cash box.

Type: boolean
Default: false

cashManagement/exchangeType

Specifies the type of storage unit exchange operations supported by the device.

Type: object
Required

cashManagement/exchangeType/byHand

The device supports manual replenishment either by filling the storage unit by hand or by replacing the storage unit.

Type: boolean
Default: false

cashManagement/itemInfoTypes

Specifies the types of information that can be retrieved through the CashManagement.GetItemInfo command. This property is null if not supported.

Type: object, null
Default: null

cashManagement/itemInfoTypes/serialNumber

Serial Number of the item.

Type: boolean
Default: false

cashManagement/itemInfoTypes/signature

Signature of the item.

Type: boolean
Default: false

cashManagement/itemInfoTypes/image

Image of the item.

Type: boolean
Default: false

cashManagement/classificationList

Specifies whether the Service has the capability to maintain a classification list of serial numbers as well as supporting the associated operations.

Type: boolean
Default: false

cashManagement/classifications

Specifies the classifications supported - see Note Classification.

Type: object

cashManagement/classifications/unrecognized

Items can be classified as unrecognized.

Type: boolean
Default: true

cashManagement/classifications/counterfeit

Items can be recognized as counterfeit.

Type: boolean
Default: false

cashManagement/classifications/suspect

Items can be suspected as counterfeit.

Type: boolean
Default: false

cashManagement/classifications/inked

Ink-stained items are recognized.

Type: boolean
Default: false

cashManagement/classifications/fit

Genuine items fit for recycling are recognized.

Type: boolean
Default: true

cashManagement/classifications/unfit

Genuine items not fit for recycling are recognized.

Type: boolean
Default: false

check

Capability information for XFS4IoT services implementing the Check interface. This will be null if the Check interface is not supported.

Type: object, null
Default: null

check/type

Specifies the type of the physical device. The following values are possible:

  • singleMediaInput - Device accepts a single media item from the customer.
  • bunchMediaInput - Device accepts a bunch of media items from the customer.

Type: string
Required

check/maxMediaOnStacker

Specifies the maximum number of media items that the stacker can hold (zero if the device does not have a stacker). If the device has a bunch media input capability and the stacker is not present or has a capacity of one then the application must process each item inserted sequentially as described in section Multi-Feed Devices without a Stacker.

Type: integer
Minimum: 0
Default: 0

check/printSize

Specifies the maximum print capabilities on the back side of the check, null if device has no back printing capabilities. If the media item is inserted in one of the orientations specified in insertOrientation, the device will print on the back side of the media. If the media item is inserted in a different orientation to those specified in insertOrientation then printing may occur on the front side, upside down or both.

Type: object, null
Default: null

check/printSize/rows

Specifies the maximum number of rows of text that the device can print on the media item. This value is 1 for single line printers.

Type: integer
Minimum: 0
Default: 0

check/printSize/cols

Specifies the maximum number of characters that can be printed on a row.

Type: integer
Minimum: 0
Default: 0

check/stamp

Specifies whether the device has stamping capabilities. If the media item is inserted in one of the orientations specified in insertOrientation, the device will stamp on the front side of the media. If the media item is inserted in a different orientation to those specified in insertOrientation then stamping may occur on the back, upside down or both.

Type: boolean
Default: false

check/rescan

Specifies whether the device has the capability to either physically rescan media items after they have been inserted into the device or is able to generate any image supported by the device during the ReadImage command (regardless of the images requested during the MediaIn command). If true then the item can be rescanned or the images can be generated using the parameters passed in the ReadImage command. If false then all images required (various color, file format, bit depth) must be gathered during execution of the MediaIn command.

Type: boolean
Default: false

check/presentControl

Specifies how the presenting of media items is controlled during the MediaInEnd and MediaInRollback commands. If true the presenting is controlled implicitly by the Service. If false the presenting must be controlled explicitly by the application using the PresentMedia command. This applies to all positions.

Type: boolean
Required

check/applicationRefuse

Specifies if the Device supports the MediaIn command mode where the application decides to accept or refuse each media item that has successfully been accepted by the device. If true then the Service supports this mode. If false then the Service does not support this mode (or the device does not have a stacker).

Type: boolean
Default: false

check/retractLocation

Specifies the locations to which the media can be retracted using the Check.RetractMedia command, as a combination of these properties. May be null if not supported:

Type: object, null
MinProperties: 1
Default: null

check/retractLocation/storage

Retract the media to a storage unit.

Type: boolean
Default: false

check/retractLocation/transport

Retract the media to the transport.

Type: boolean
Default: false

check/retractLocation/stacker

Retract the media to the stacker.

Type: boolean
Default: false

check/retractLocation/rebuncher

Retract the media to the re-buncher.

Type: boolean
Default: false

check/resetControl

Specifies the manner in which the media can be handled on Reset, as a combination of these properties. May be null if the command is not supported:

Type: object, null
MinProperties: 1
Default: null

check/resetControl/eject

Eject the media.

Type: boolean
Default: false

check/resetControl/storageUnit

Retract the media to retract storage unit.

Type: boolean
Default: false

check/imageType

Specifies the image format supported by this device, as a combination of these properties. May be null if not supported.

Type: object, null
MinProperties: 1
Default: null

check/imageType/tif

The device can return scanned images in TIFF 6.0 format.

Type: boolean
Default: false

check/imageType/wmf

The device can return scanned images in WMF (Windows Metafile) format.

Type: boolean
Default: false

check/imageType/bmp

The device can return scanned images in windows BMP format.

Type: boolean
Default: false

check/imageType/jpg

The device can return scanned images in JPG format.

Type: boolean
Default: false

check/frontImage

Specifies the capabilities of the front image supported by this device. May be null if front images are not supported.

Type: object, null
Default: null

check/frontImage/colorFormat

Specifies the image color formats supported by this device, as a combination of these properties:

Type: object
Required

check/frontImage/colorFormat/binary

The device can return scanned images in binary.

Type: boolean
Default: false

check/frontImage/colorFormat/grayScale

The device can return scanned images in gray scale.

Type: boolean
Default: false

check/frontImage/colorFormat/full

The device can return scanned images in full color.

Type: boolean
Default: false

check/frontImage/scanColor

Specifies the image scan colors supported by this device and individually controllable by the application. Scan colors are used to enhance the scanning results on colored scan media. This value is specified as a combination of these properties:

Type: object
Required

check/frontImage/scanColor/red

The device can return images scanned with red light.

Type: boolean
Default: false

check/frontImage/scanColor/green

The device can return images scanned with green light.

Type: boolean
Default: false

check/frontImage/scanColor/blue

The device can return images scanned with blue light.

Type: boolean
Default: false

check/frontImage/scanColor/yellow

The device can return images scanned with yellow light.

Type: boolean
Default: false

check/frontImage/scanColor/white

The device can return images scanned with white light.

Type: boolean
Default: false

check/frontImage/scanColor/infraRed

The device can return images scanned with infrared light.

Type: boolean
Default: false

check/frontImage/scanColor/ultraViolet

The device can return images scanned with ultraviolet light.

Type: boolean
Default: false

check/frontImage/defaultScanColor

Specifies the default image color format used by this device (i.e. when not explicitly set). The following values are possible:

  • red - The default color is red light.
  • green - The default color is green light.
  • blue - The default color is blue light.
  • yellow - The default color is yellow light.
  • white - The default color is white light.
  • infraRed - The default color is infrared light.
  • ultraViolet - The default color is ultraviolet light.

Type: string
Required

check/backImage

Specifies the capabilities of the back image supported by this device. May be null if back images are not supported.

Type: object, null
Default: null

check/codelineFormat

Specifies the code line formats supported by this device, as a combination of these properties:

Type: object
MinProperties: 1
Required

check/codelineFormat/cmc7

The device can read MICR CMC7 [Ref. check-4] code lines.

Type: boolean
Default: false

check/codelineFormat/e13b

The device can read MICR E13B [Ref. check-3] code lines.

Type: boolean
Default: false

check/codelineFormat/ocr

The device can read code lines using Optical Character Recognition. The default or pre-configured OCR font will be used.

Type: boolean
Default: false

check/codelineFormat/ocra

The device can read code lines using Optical Character Recognition font A. The ASCII codes will conform to [Ref. check-1].

Type: boolean
Default: false

check/codelineFormat/ocrb

The device can read code lines using Optical Character Recognition font B. The ASCII codes will conform to [Ref. check-2].

Type: boolean
Default: false

check/dataSource

Specifies the reading/imaging capabilities supported by this device, as a combination of these properties:

Type: object
MinProperties: 1
Required

check/dataSource/imageFront

The device can scan the front image of the document.

Type: boolean
Default: false

check/dataSource/imageBack

The device can scan the back image of the document.

Type: boolean
Default: false

check/dataSource/codeLine

The device can recognize the code line.

Type: boolean
Default: false

check/insertOrientation

Specifies the media item insertion orientations supported by the Device such that hardware features such as MICR reading, endorsing and stamping will be aligned with the correct edges and sides of the media item. Devices may still return code lines and images even if one of these orientations is not used during media insertion. If the media items are inserted in one of the orientations defined in this capability then any printing or stamping will be on the correct side of the media item. If the media is inserted in a different orientation then any printing or stamping may be on the wrong side, upside down or both. This value is reported based on the customer's perspective. This value is a combination of these properties:

Type: object
MinProperties: 1
Required

check/insertOrientation/codeLineRight

The media item should be inserted short edge first with the code line to the right.

Type: boolean
Default: false

check/insertOrientation/codeLineLeft

The media item should be inserted short edge first with the code line to the left.

Type: boolean
Default: false

check/insertOrientation/codeLineBottom

The media item should be inserted long edge first with the code line to the bottom.

Type: boolean
Default: false

check/insertOrientation/codeLineTop

The media item should be inserted long edge first with the code line to the top.

Type: boolean
Default: false

check/insertOrientation/faceUp

The media item should be inserted with the front of the media item facing up.

Type: boolean
Default: false

check/insertOrientation/faceDown

The media item should be inserted with the front of the media item facing down.

Type: boolean
Default: false

check/positions

Specifies the capabilities of up to three logical position types.

Type: object
MinProperties: 1
Required

check/positions/input

Structure that specifies the capabilities of the input position.

Type: object, null
Default: null

check/positions/input/itemsTakenSensor

Specifies whether or not the described position can detect when items at the exit position are taken by the user. If true the Service generates an accompanying MediaTakenEvent. If false this event is not generated. This relates to output and refused positions, so will be null for input positions.

Type: boolean, null
Default: null

check/positions/input/itemsInsertedSensor

Specifies whether the described position has the ability to detect when items have been inserted by the user. If true the Service generates an accompanying MediaInsertedEvent. If false this event is not generated. This relates to all input positions, so will always be null for input positions.

Type: boolean, null
Default: null

check/positions/input/retractAreas

Specifies the areas to which items may be retracted from this position. May be null if items can not be retracted from this position.

Type: object, null
MinProperties: 1
Default: null

check/positions/input/retractAreas/retractBin

Can retract items in this position to a retract storage unit.

Type: boolean
Default: false

check/positions/input/retractAreas/transport

Can retract items in this position to the transport.

Type: boolean
Default: false

check/positions/input/retractAreas/stacker

Can retract items in this position to the stacker.

Type: boolean
Default: false

check/positions/input/retractAreas/rebuncher

Can retract items in this position to the re-buncher.

Type: boolean
Default: false

check/positions/output

Structure that specifies the capabilities of the output position.

Type: object, null
Default: null

check/positions/refused

Structure that specifies the capabilities of the refused position.

Type: object, null
Default: null

check/imageAfterEndorse

Specifies whether the device can generate an image after text is printed on the media item. If true then the generation of the image can be specified using the SetMediaParameters command. If false, this functionality is not available. This capability applies to media items whose destination is a storage unit; the returnedItemsProcessing capability indicates whether this functionality is supported for media items that are to be returned to the customer.

Type: boolean
Default: false

check/returnedItemsProcessing

Specifies the processing that this device supports for media items that are identified to be returned to the customer using the SetMediaParameters command, as a combination of these properties or null if none apply:

Type: object, null
MinProperties: 1
Default: null

check/returnedItemsProcessing/endorse

This device can endorse a media item to be returned to the customer; the endorsement is specified using the SetMediaParameters command.

Type: boolean
Default: false

check/returnedItemsProcessing/endorseImage

This device can generate an image of a media item to be returned to the customer after it has been endorsed; the request for the image is specified using the SetMediaParameters command.

Type: boolean
Default: false

check/printSizeFront

Reports the printing capabilities of the device on the front side of the check, null if device has no front printing capabilities. If the media item is inserted in one of the orientations specified in insertOrientation, the device will print on the front side of the media. If the media item is inserted in a different orientation to those specified in insertOrientation then printing may occur on the back side, upside down or both.

Type: object, null
Default: null

mixedMedia

Capability information for XFS4IoT services implementing the MixedMedia interface. This will be null if the MixedMedia interface is not supported.

Type: object, null
Default: null

mixedMedia/modes

Specifies the transaction modes supported by the Service.

Type: object
MinProperties: 1
Required

mixedMedia/modes/cashAccept

Specifies whether transactions can accept cash. This property may be null if no change required or its state has not changed in Common.StatusChangedEvent.

Type: boolean, null
Default: null

mixedMedia/modes/checkAccept

Specifies whether transactions can accept checks. This property may be null if no change required or its state has not changed in Common.StatusChangedEvent.

Type: boolean, null
Default: null

mixedMedia/dynamic

Specifies whether the mode can be modified during a transaction.

Type: boolean
Default: false

pinPad

Capability information for XFS4IoT services implementing the PinPad interface. This will be null if the PinPad interface is not supported.

Type: object, null
Default: null

pinPad/pinFormats

Supported PIN format.

Type: object

pinPad/pinFormats/ibm3624

PIN left justified, filled with padding characters, PIN length 4-16 digits. The padding character is a hexadecimal digit in the range 0x00 to 0x0F.

Type: boolean
Default: false

pinPad/pinFormats/ansi

PIN is preceded by 0x00 and the length of the PIN (0x04 to 0x0C), filled with padding character 0x0F to the right, PIN length 4-12 digits, XORed with PAN (Primary Account Number, minimum 12 digits without check number).

Type: boolean
Default: false

pinPad/pinFormats/iso0

PIN is preceded by 0x00 and the length of the PIN (0x04 to 0x0C), filled with padding character 0x0F to the right, PIN length 4-12 digits, XORed with PAN (Primary Account Number without check number, no minimum length specified, missing digits are filled with 0x00).

Type: boolean
Default: false

pinPad/pinFormats/iso1

PIN is preceded by 0x01 and the length of the PIN (0x04 to 0x0C), padding characters are taken from a transaction field (10 digits).

Type: boolean
Default: false

pinPad/pinFormats/eci2

PIN left justified, filled with padding characters, PIN only 4 digits.

Type: boolean
Default: false

pinPad/pinFormats/eci3

PIN is preceded by the length (digit), PIN length 4-6 digits, the padding character can range from 0x0 through 0xF".

Type: boolean
Default: false

pinPad/pinFormats/visa

PIN is preceded by the length (digit), PIN length 4-6 digits. If the PIN length is less than six digits the PIN is filled with 0x0 to the length of six, the padding character can range from 0x0 through 0x9 (This format is also referred to as VISA2).

Type: boolean
Default: false

pinPad/pinFormats/diebold

PIN is padded with the padding character and may be not encrypted, single encrypted or double encrypted.

Type: boolean
Default: false

pinPad/pinFormats/dieboldCo

PIN with the length of 4 to 12 digits, each one with a value of 0x0 to 0x9, is preceded by the one-digit coordination number with a value from 0x0 to 0xF, padded with the padding character with a value from 0x0 to 0xF and may be not encrypted, single encrypted or double encrypted.

Type: boolean
Default: false

pinPad/pinFormats/visa3

PIN with the length of 4 to 12 digits, each one with a value of 0x0 to 0x9, is followed by a delimiter with the value of 0xF and then padded by the padding character with a value between 0x0 to 0xF.

Type: boolean
Default: false

pinPad/pinFormats/banksys

PIN is encrypted and formatted according to the Banksys PIN block specifications.

Type: boolean
Default: false

pinPad/pinFormats/emv

The PIN block is constructed as follows: PIN is preceded by 0x02 and the length of the PIN (0x04 to 0x0C), filled with padding character 0x0F to the right, formatted up to 248 bytes of other data as defined within the EMV 4.0 specifications and finally encrypted with an RSA key.

Type: boolean
Default: false

pinPad/pinFormats/iso3

PIN is preceded by 0x03 and the length of the PIN (0x04 to 0x0C), padding characters sequentially or randomly chosen, XORed with digits from PAN.

Type: boolean
Default: false

pinPad/pinFormats/ap

PIN is formatted according to the Italian Bancomat specifications (see [Ref. pinpad-5]). It is known as the Authentication Parameter PIN block and is created with a 5 digit PIN, an 18 digit PAN, and the 8 digit CCS from the track data.

Type: boolean
Default: false

pinPad/pinFormats/iso4

PIN is formatted according to ISO 9564-1: 2017 Format-4 (uses AES Encryption).

Type: boolean
Default: false

pinPad/presentationAlgorithms

Supported presentation algorithms. This property is null if not supported.

Type: object, null
Default: null

pinPad/presentationAlgorithms/presentClear

Algorithm for the presentation of a clear text PIN to a chipcard. Each digit of the clear text PIN is inserted as one nibble (=halfbyte) into ChipData.

Type: boolean
Default: false

pinPad/display

Specifies the type of the display used in the PIN pad module. This property is null if not supported.

Type: object, null
Default: null

pinPad/display/none

No display unit.

Type: boolean
Default: false

pinPad/display/ledThrough

Lights next to text guide user.

Type: boolean
Default: false

pinPad/display/display

A real display is available (this doesn't apply for self-service).

Type: boolean
Default: false

pinPad/idcConnect

Specifies whether the PIN pad is directly physically connected to the ID card unit. If the value is true, the PIN will be transported securely during the command PinPad.PresentIdc.

Type: boolean
Default: false

pinPad/validationAlgorithms

Specifies the algorithms for PIN validation supported by the service. This property is null if not supported.

Type: object, null
Default: null

pinPad/validationAlgorithms/des

DES algorithm.

Type: boolean
Default: false

pinPad/validationAlgorithms/visa

Visa algorithm.

Type: boolean
Default: false

pinPad/pinCanPersistAfterUse

Specifies whether the device can retain the PIN after a PIN processing command.

Type: boolean
Default: false

pinPad/typeCombined

Specifies whether the keypad used in the secure PIN pad module is integrated within a generic Win32 keyboard. true means the secure PIN keypad is integrated within a generic Win32 keyboard and standard Win32 key events will be generated for any key when there is no active Keyboard.GetData or Keyboard.GetPin command. Note that XFS continues to support defined PIN keys only, and is not extended to support new alphanumeric keys.

Type: boolean
Default: false

pinPad/setPinblockDataRequired

Specifies whether the command PinPad.SetPinblockData must be called before the PIN is entered via Keyboard.GetPin and retrieved via PinPad.GetPinblock.

Type: boolean
Default: false

pinPad/pinBlockAttributes

Attributes supported by the PinPad.GetPinblock command to generate encrypted PIN block.

Type: object, null
Default: null

pinPad/pinBlockAttributes/P0 (example name)

Specifies the key usages supported by the PinPad.PinBlock command. The following values are possible:

  • P0 - PIN Encryption

Type: object
MinProperties: 1
Name Pattern: ^P0$

pinPad/pinBlockAttributes/P0/T (example name)

Specifies the encryption algorithms supported by the PinPad.PinBlock command. The following values are possible:

  • A - AES.
  • D - DEA.
  • R - RSA.
  • T - Triple DEA (also referred to as TDEA).

Type: object
MinProperties: 1
Name Pattern: ^[ADRT]$

pinPad/pinBlockAttributes/P0/T/E (example name)

Specifies the encryption modes supported by the PinPad.PinBlock command. The following value is possible:

  • E - Encrypt

Type: object
Name Pattern: ^E$

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod

Specifies the cryptographic method supported. If the algorithm is 'A', 'D', or 'T', then the following properties can be true:

  • ecb - The ECB encryption method.
  • cbc - The CBC encryption method.
  • cfb - The CFB encryption method.
  • ofb - The OFB encryption method.
  • ctr - The CTR method defined in NIST SP800-38A (See [Ref. pinpad-7]).
  • xts - The XTS method defined in NIST SP800-38E (See [Ref. pinpad-8]).

If the algorithm is 'R', then following properties can be true:

  • rsaesPkcs1V15 - Use the RSAES_PKCS1-v1.5 algorithm.
  • rsaesOaep - Use the RSAES OAEP algorithm.

Type: object
Required

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/ecb

The ECB encryption method.

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/cbc

The CBC encryption method.

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/cfb

The CFB encryption method.

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/ofb

The OFB encryption method.

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/ctr

The CTR method defined in NIST SP800-38A (See [Ref. pinpad-7]).

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/xts

The XTS method defined in NIST SP800-38E (See [Ref. pinpad-8]).

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/rsaesPkcs1V15

The RSAES_PKCS1-v1.5 algorithm.

Type: boolean
Default: false

pinPad/pinBlockAttributes/P0/T/E/cryptoMethod/rsaesOaep

The RSAES OAEP algorithm.

Type: boolean
Default: false

crypto

Capability information for XFS4IoT services implementing the Crypto interface. This will be null if the Crypto interface is not supported.

Type: object, null
Default: null

crypto/emvHashAlgorithm

Specifies which hash algorithm is supported for the calculation of the HASH. This property is null if not supported.

Type: object, null
Default: null

crypto/emvHashAlgorithm/sha1Digest

The SHA 1 digest algorithm is supported by the Crypto.Digest command.

Type: boolean
Default: false

crypto/emvHashAlgorithm/sha256Digest

The SHA 256 digest algorithm, as defined in ISO/IEC 10118-3:2004 [Ref. crypto-1] and FIPS 180-2 [Ref. crypto-2], is supported by the Crypto.Digest command.

Type: boolean
Default: false

crypto/cryptoAttributes

Attributes supported by the Crypto.CryptoData command to encrypt or decrypt data.

Type: object, null
Default: null

crypto/cryptoAttributes/D0 (example name)

The following key usage is possible:

  • D0 - Symmetric data encryption.
  • D1 - Asymmetric data encryption.

Type: object
MinProperties: 1
Name Pattern: ^D[0-1]$

crypto/cryptoAttributes/D0/D (example name)

Specifies the encryption algorithms supported by the Crypto.CryptoData command. The following values are possible:

  • A - AES.
  • D - DEA.
  • R - RSA.
  • T - Triple DEA (also referred to as TDEA).

Type: object
MinProperties: 1
Name Pattern: ^[ADRT]$

crypto/cryptoAttributes/D0/D/D (example name)

Specifies the Mode of Use supported by the Crypto.CryptoData command. The following values are possible:

  • D - Decrypt
  • E - Encrypt

Type: object
Name Pattern: ^[DE]$

crypto/cryptoAttributes/D0/D/D/cryptoMethod

Specifies the cryptographic method supported by the Crypto.CryptoData command. If the key usage is symmetric encryption methods 'D0'), then the following properties can be true.

  • ecb - The ECB encryption method.
  • cbc - The CBC encryption method.
  • cfb - The CFB encryption method.
  • ofb - The OFB encryption method.
  • ctr - The CTR method defined in NIST SP800-38A (See [Ref. crypto-4])
  • xts - The XTS method defined in NIST SP800-38E (See [Ref. crypto-5])

If the key usage is asymmetric encryption methods 'D1', then the following properties can be true.

  • rsaesPkcs1V15 - RSAES_PKCS1-v1.5 algorithm.
  • rsaesOaep - The RSAES OAEP algorithm.

Type: object
Required

crypto/cryptoAttributes/D0/D/D/cryptoMethod/ecb

The ECB encryption method.

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/cbc

The CBC encryption method.

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/cfb

The CFB encryption method.

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/ofb

The OFB encryption method.

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/ctr

The CTR method defined in NIST SP800-38A (See [Ref. crypto-4])

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/xts

The XTS method defined in NIST SP800-38E. (See [Ref. crypto-5])

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/rsaesPkcs1V15

The RSAES_PKCS1-v1.5 algorithm.

Type: boolean
Default: false

crypto/cryptoAttributes/D0/D/D/cryptoMethod/rsaesOaep

The RSAES OAEP algorithm.

Type: boolean
Default: false

crypto/authenticationAttributes

Attributes supported by the Crypto.GenerateAuthentication command to generate authentication data.

Type: object, null
Default: null

crypto/authenticationAttributes/M0 (example name)

The following key usages are possible:

  • M0 - ISO 16609 MAC Algorithm 1 (using TDEA).
  • M1- ISO 9797-1 MAC Algorithm 1.
  • M2 - ISO 9797-1 MAC Algorithm 2.
  • M3 - ISO 9797-1 MAC Algorithm 3.
  • M4 - ISO 9797-1 MAC Algorithm 4.
  • M5 - ISO 9797-1:1999 MAC Algorithm 5.
  • M6 - 9797-1:2011 MAC Algorithm 5/CMAC.
  • M7 - HMAC.
  • M8 - ISO 9797-1:2011 MAC Algorithm 6.
  • S0 - Asymmetric key pair for digital signature.
  • S1 - Asymmetric key pair, CA.
  • S2 - Asymmetric key pair, nonX9.24 key.

Type: object
MinProperties: 1
Name Pattern: ^M[0-8]$|^S[0-2]$

crypto/authenticationAttributes/M0/T (example name)

Specifies the encryption algorithms supported by the Crypto.GenerateAuthentication command. The following value is possible:

  • A - AES.
  • D - DEA.
  • R - RSA.
  • T - Triple DEA (also referred to as TDEA).

Type: object
MinProperties: 1
Name Pattern: ^[ADRT]$

crypto/authenticationAttributes/M0/T/G (example name)

Specifies the Mode of Use supported by the Crypto.GenerateAuthentication command. The following values are possible:

  • C - Both Generate and Verify.
  • G - Generate. This be used to generate a MAC.
  • S - Signature
  • T - Both Sign and Decrypt.

Type: object, null
Name Pattern: ^[CGST]$
Default: null

crypto/authenticationAttributes/M0/T/G/cryptoMethod

Specifies the asymmetric signature verification method supported by the Crypto.GenerateAuthentication command.

If the key usage is one of the MAC usages (e.g. 'M0'), this property should be null.

Type: object, null
MinProperties: 1
Default: null

crypto/authenticationAttributes/M0/T/G/cryptoMethod/rsassaPkcs1V15

The RSASSA-PKCS1-v1.5 algorithm.

Type: boolean
Default: false

crypto/authenticationAttributes/M0/T/G/cryptoMethod/rsassaPss

The RSASSA-PSS algorithm.

Type: boolean
Default: false

crypto/authenticationAttributes/M0/T/G/hashAlgorithm

Specifies the hash algorithm supported.

If the key usage is one of the MAC usages (e.g. 'M0'), this property should be null.

Type: object, null
MinProperties: 1
Default: null

crypto/authenticationAttributes/M0/T/G/hashAlgorithm/sha1

The SHA 1 digest algorithm.

Type: boolean
Default: false

crypto/authenticationAttributes/M0/T/G/hashAlgorithm/sha256

The SHA 256 digest algorithm, as defined in ISO/IEC 10118-3:2004 [Ref. crypto-1] and FIPS 180-2 [Ref. crypto-2].

Type: boolean
Default: false

crypto/verifyAttributes

Attributes supported by the Crypto.VerifyAuthentication command to verify authentication data.

Type: object, null
Default: null

crypto/verifyAttributes/M0/T (example name)

Specifies the encryption algorithms supported by Crypto.VerifyAuthentication command. The following value is possible:

  • A - AES.
  • D - DEA.
  • R - RSA.
  • T - Triple DEA (also referred to as TDEA).

Type: object
MinProperties: 1
Name Pattern: ^[ADRT]$

crypto/verifyAttributes/M0/T/V (example name)

Specifies the Mode of Use supported by Crypto.VerifyAuthentication command. The following values are possible:

  • V - Verify. This be used to verify a MAC.

Type: object, null
Name Pattern: ^V$
Default: null

crypto/verifyAttributes/M0/T/V/cryptoMethod

Specifies the asymmetric signature verification method supported by the Crypto.VerifyAuthentication command.

If the key usage is one of the MAC usages (e.g. 'M0'), this property should be null.

Type: object, null
MinProperties: 1
Default: null

crypto/verifyAttributes/M0/T/V/hashAlgorithm

Specifies the hash algorithm supported.

If the key usage is one of the MAC usages (e.g. 'M0'), this property should be null.

Type: object, null
MinProperties: 1
Default: null

keyManagement

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

Type: object, null
Default: null

keyManagement/keyNum

Number of the keys which can be stored in the encryption/decryption module.

Type: integer
Minimum: 0
Required

keyManagement/keyCheckModes

Specifies the key check modes that are supported to check the correctness of an imported key value. The modes available for each key may depend on security requirements of the algorithm. The algorithm (i.e. DES, 3DES, AES) and use is determined by the algorithm of the key being checked and security requirements. This property is null if not supported.

Type: object, null
Default: null

keyManagement/keyCheckModes/self

The key check value is created by an encryption of the key with itself. For a double-length or triple-length key the KCV is generated using 3DES encryption using the first 8 bytes of the key as the source data for the encryption.

Type: boolean
Default: false

keyManagement/keyCheckModes/zero

The key check value is created by encrypting a zero value with the key.

Type: boolean
Default: false

keyManagement/rsaAuthenticationScheme

Specifies the types of Remote Key Loading/Authentication that are supported. This property is null if not supported.

Type: object, null
Default: null

keyManagement/rsaAuthenticationScheme/twoPartySig

Two-party Signature based authentication.

Type: boolean
Default: false

keyManagement/rsaAuthenticationScheme/threePartyCert

Three-party Certificate based authentication.

Type: boolean
Default: false

keyManagement/rsaAuthenticationScheme/threePartyCertTr34

Three-party Certificate based authentication described by X9 TR34-2019 [Ref. keymanagement-9].

Type: boolean
Default: false

keyManagement/rsaSignatureAlgorithm

Specifies the types of RSA Signature Algorithm that are supported.

Type: object, null
Default: null

keyManagement/rsaSignatureAlgorithm/pkcs1V15

pkcs1V15 Signatures supported.

Type: boolean
Default: false

keyManagement/rsaSignatureAlgorithm/pss

pss Signatures supported.

Type: boolean
Default: false

keyManagement/rsaCryptAlgorithm

Specifies the types of RSA Encipherment Algorithm that are supported. This property is null if not supported.

Type: object, null
Default: null

keyManagement/rsaCryptAlgorithm/pkcs1V15

pkcs1V15 algorithm supported.

Type: boolean
Default: false

keyManagement/rsaCryptAlgorithm/oaep

oaep algorithm supported.

Type: boolean
Default: false

keyManagement/rsaKeyCheckMode

Specifies which hash algorithms used to generate the public key check value/thumb print are supported. This property is null if not supported.

Type: object, null

keyManagement/rsaKeyCheckMode/sha1

sha1 is supported as defined in [Ref. keymanagement-2].

Type: boolean
Default: false

keyManagement/rsaKeyCheckMode/sha256

sha256 is supported as defined in ISO/IEC 10118-3:2004 [Ref. keymanagement-7] and FIPS 180-2 [Ref. keymanagement-8].

Type: boolean
Default: false

keyManagement/signatureScheme

Specifies which capabilities are supported by the Signature scheme. This property is null if not supported.

Type: object, null

keyManagement/signatureScheme/randomNumber

Specifies if the service returns a random number from the KeyManagement.StartKeyExchange command within the RSA Signature Scheme.

Type: boolean
Default: false

keyManagement/signatureScheme/exportDeviceId

Specifies if the service supports exporting the device Security Item within the RSA Signature Scheme.

Type: boolean
Default: false

keyManagement/signatureScheme/enhancedRkl

Specifies that the service supports the Enhanced Signature Remote Key Scheme. This scheme allows the customer to manage their own public keys independently of the Signature Issuer. When this mode is supported then the key loaded signed with the Signature Issuer key is the host root public key PKROOT, rather than PKHOST.

Type: boolean
Default: false

keyManagement/emvImportSchemes

Identifies the supported EMV Import Scheme(s). This property is null if not supported.

Type: object, null
Default: null

keyManagement/emvImportSchemes/plainCA

A plain text CA public key is imported with no verification.

Type: boolean
Default: false

keyManagement/emvImportSchemes/chksumCA

A plain text CA public key is imported using the EMV 2000 verification algorithm. See [Ref. keymanagement-3].

Type: boolean
Default: false

keyManagement/emvImportSchemes/epiCA

A CA public key is imported using the selfsign scheme defined in the Europay International, EPI CA Module Technical - Interface specification Version 1.4, [Ref. ref-keymanagement-4].

Type: boolean
Default: false

keyManagement/emvImportSchemes/issuer

An Issuer public key is imported as defined in EMV 2000 Book II, [Ref. keymanagement-3].

Type: boolean
Default: false

keyManagement/emvImportSchemes/icc

An ICC public key is imported as defined in EMV 2000 Book II, [Ref. keymanagement-3].

Type: boolean
Default: false

keyManagement/emvImportSchemes/iccPin

An ICC PIN public key is imported as defined in EMV 2000 Book II, [Ref. keymanagement-3].

Type: boolean
Default: false

keyManagement/emvImportSchemes/pkcsv15CA

A CA public key is imported and verified using a signature generated with a private key for which the public key is already loaded..

Type: boolean
Default: false

keyManagement/keyBlockImportFormats

Supported key block formats. This property is null if not supported.

Type: object, null
Default: null

keyManagement/keyBlockImportFormats/A

Supports X9.143 key block version ID A.

Type: boolean
Default: false

keyManagement/keyBlockImportFormats/B

Supports X9.143 key block version ID B.

Type: boolean
Default: false

keyManagement/keyBlockImportFormats/C

Supports X9.143 key block version ID C.

Type: boolean
Default: false

keyManagement/keyBlockImportFormats/D

Supports X9.143 key block version ID D.

Type: boolean
Default: false

keyManagement/keyImportThroughParts

Specifies whether the device is capable of importing keys in multiple parts.

Type: boolean
Default: false

keyManagement/desKeyLength

Specifies which DES key lengths are supported. This property is null if not supported.

Type: object, null
Default: null

keyManagement/desKeyLength/single

8 byte DES keys are supported.

Type: boolean
Default: false

keyManagement/desKeyLength/double

16 byte DES keys are supported.

Type: boolean
Default: false

keyManagement/desKeyLength/triple

24 byte DES keys are supported.

Type: boolean
Default: false

keyManagement/certificateTypes

Specifies supported certificate types. This property is null if not supported.

Type: object, null
Default: null

keyManagement/certificateTypes/encKey

Supports the device public encryption certificate.

Type: boolean
Default: false

keyManagement/certificateTypes/verificationKey

Supports the device public verification certificate.

Type: boolean
Default: false

keyManagement/certificateTypes/hostKey

Supports the Host public certificate.

Type: boolean
Default: false

keyManagement/loadCertOptions

Specifying the options supported by the KeyManagement.LoadCertificate command. This property is null if not supported.

Type: object, null
MinProperties: 1
Default: null

keyManagement/loadCertOptions/certHost (example name)

Specifies a supported signer. The following signers are possible.

  • certHost - The current Host RSA Private Key is used to sign the token.
  • sigHost - The current Host RSA Private Key is used to sign the token, signature format is used.
  • hl - A Higher-Level Authority RSA Private Key is used to sign the token.
  • certHostTr34 - The current Host RSA Private Key is used to sign the token, compliant with X9 TR34-2019 [Ref. keymanagement-9].
  • caTr34 - The Certificate Authority RSA Private Key is used to sign the token, compliant with X9 TR34-2019 [Ref. keymanagement-9].
  • hlTr34 - A Higher-Level Authority RSA Private Key is used to sign the token, compliant with X9 TR34-2019 [Ref. keymanagement-9].

Type: object
Name Pattern: ^(certHost|sigHost|hl|certHostTr34|caTr34|hlTr34|hlTr34)$

keyManagement/loadCertOptions/certHost/newHost

Load a new Host certificate, where one has not already been loaded.

Type: boolean
Default: false

keyManagement/loadCertOptions/certHost/replaceHost

Replace (or rebind) the device to a new Host certificate, where the new Host certificate is signed by signer.

Type: boolean
Default: false

keyManagement/crklLoadOptions

Supported options to load the Key Transport Key using the Certificate Remote Key Loading protocol. This property is null if not supported.

Type: object, null
Default: null

keyManagement/crklLoadOptions/noRandom

Import a Key Transport Key without generating and using a random number.

Type: boolean
Default: false

keyManagement/crklLoadOptions/noRandomCrl

Import a Key Transport Key with a Certificate Revocation List appended to the input message. A random number is not generated nor used.

Type: boolean
Default: false

keyManagement/crklLoadOptions/random

Import a Key Transport Key by generating and using a random number.

Type: boolean
Default: false

keyManagement/crklLoadOptions/randomCrl

Import a Key Transport Key with a Certificate Revocation List appended to the input parameter. A random number is generated and used.

Type: boolean
Default: false

keyManagement/symmetricKeyManagementMethods

Specifies the Symmentric Key Management modes. This property is null if not supported.

Type: object, null
Default: null

keyManagement/symmetricKeyManagementMethods/fixedKey

This method of key management uses fixed keys for transaction processing.

Type: boolean
Default: false

keyManagement/symmetricKeyManagementMethods/masterKey

This method uses a hierarchy of Key Encrypting Keys and Transaction Keys. The highest level of Key Encrypting Key is known as a Master Key. Transaction Keys are distributed and replaced encrypted under a Key Encrypting Key.

Type: boolean
Default: false

keyManagement/symmetricKeyManagementMethods/tdesDukpt

This method uses TDES Derived Unique Key Per Transaction (see [Ref. keymanagement-10]).

Type: boolean
Default: false

keyManagement/keyAttributes

Attributes supported by KeyManagement.ImportKey command for the key to be loaded.

Type: object

keyManagement/keyAttributes/M0 (example name)

Specifies the key usages supported by KeyManagement.ImportKey command and key usage string length must be two. The following values are possible:

  • B0 - Base Derivation Key (BDK).
  • B1 - Initial DUKPT Key.
  • B2 - Base Key Variant Key (deprecated).
  • B3 - Key Derivation Key (Non ANSI X9.24).
  • C0 - CVK Card Verification Key.
  • D0 - Symmetric Key for Data Encryption.
  • D1 - Asymmetric Key for Data Encryption.
  • D2 - Data Encryption Key for Decimalization Table.
  • D3 - Data Encryption Key for Sensitive Data.
  • E0 - EMV / Chip Issuer Master Key: Application Cryptogram.
  • E1 - EMV / Chip Issuer Master Key: Secure Messaging for Confidentiality.
  • E2 - EMV / Chip Issuer Master Key: Secure Messaging for Integrity.
  • E3 - EMV / Chip Issuer Master Key: Data Authentication Code.
  • E4 - EMV / Chip Issuer Master Key: Dynamic.
  • E5 - EMV / Chip Issuer Master Key: Card Personalization.
  • E6 - EMV / Chip Issuer Master Key: Other Initialization Vector (IV).
  • E7 - EMV / Chip Asymmetric Key Pair for EMV/Smart Card based PIN/PIN Block Encryption.
  • I0 - Initialization Vector (IV).
  • K0 - Key Encryption or wrapping.
  • K1 - X9.143 Key Block Protection Key.
  • K2 - TR-34 Asymmetric Key.
  • K3 - Asymmetric Key for key agreement / key wrapping.
  • K4 - Key Block Protection Key, ISO 20038.
  • M0 - MAC Key, ISO 16609 MAC algorithm 1 (using TDEA).
  • M1 - MAC Key, ISO 9797-1 MAC Algorithm 1.
  • M2 - MAC Key, ISO 9797-1 MAC Algorithm 2.
  • M3 - MAC Key, ISO 9797-1 MAC Algorithm 3.
  • M4 - MAC Key, ISO 9797-1 MAC Algorithm 4.
  • M5 - MAC Key, ISO 9797-1:2011 MAC Algorithm 5.
  • M6 - MAC Key, ISO 9797-1:2011 MAC Algorithm 5 / CMAC.
  • M7 - HMAC Key.
  • M8 - MAC Key, ISO 9797-1:2011 MAC Algorithm 6.
  • P0 - PIN Encryption.
  • P1 - PIN Generation Key (reserved for ANSI X9.132-202x).
  • S0 - Asymmetric Key Pair for Digital Signature.
  • S1 - Asymmetric Key Pair, CA Key.
  • S2 - Asymmetric Key Pair, non-ANSI X9.24 Key.
  • V0 - PIN Verification Key, PVK, other algorithm.
  • V1 - PIN Verification Key, IBM 3624.
  • V2 - PIN Verification Key, VISA PVV.
  • V3 - PIN Verification Key, ANSI X9-132 algorithm 1.
  • V4 - PIN Verification Key, ANSI X9-132 algorithm 2.
  • V5 - PIN Verification Key, ANSI X9.132 algorithm 3.
  • 00 - 99 - These numeric values are reserved for proprietary use.

Type: object
MinProperties: 1
Name Pattern: ^B[0-3]$|^C0$|^D[0-3]$|^E[0-7]$|^I0$|^K[0-4]$|^M[0-8]$|^P[0-1]$|^S[0-2]$|^V[0-5]$|^[0-9][0-9]$

keyManagement/keyAttributes/M0/T (example name)

Specifies the encryption algorithms supported by the KeyManagement.ImportKey command. The following values are possible:

  • A - AES.
  • D - DEA (Note that this is included for backwards compatibility).
  • H - HMAC (specify the underlying hash algorithm in optional field).
  • R - RSA.
  • T - Triple DEA (TDEA).
  • 0 - 9 - These numeric values are reserved for proprietary use.

Type: object
MinProperties: 1
Name Pattern: ^[0-9ADHRT]$

keyManagement/keyAttributes/M0/T/C (example name)

Specifies the Mode of Use supported by KeyManagement.ImportKey key. The following values are possible:

  • B - Both Encrypt/Wrap and Decrypt/Unwrap.
  • C - Both Generate and Verify.
  • D - Decrypt / Unwrap Only.
  • E - Encrypt / Wrap Only.
  • G - Generate Only.
  • S - Signature Only.
  • T - Both Sign and Decrypt.
  • V - Verify Only.
  • X - Key used to derive other keys(s).
  • Y - Key used to create key variants.
  • 0 - 9 - These numeric values are reserved for proprietary use.

Type: object, null
Name Pattern: ^[0-9BCDEGSTVXY]$
Default: null

keyManagement/keyAttributes/M0/T/C/restrictedKeyUsage

If the key usage is a key encryption usage (e.g. 'K0') this specifies the key usage of the keys that can be encrypted by the key.

This property should be null if restricted key usage is not supported or required.

The following values are possible:

  • B0 - BDK Base Derivation Key.
  • B1 - Initial DUKPT key.
  • B2 - Base Key Variant Key.
  • B3 - Key Derivation Key (Non ANSI X9.24).
  • C0 - CVK Card Verification Key.
  • D0 - Symmetric Key for Data Encryption.
  • D1 - Asymmetric Key for Data Encryption.
  • D2 - Data Encryption Key for Decimalization Table.
  • D3 - Data Encryption Key for Sensitive Data.
  • E0 - EMV / Chip Issuer Master Key: Application Cryptogram.
  • E1 - EMV / Chip Issuer Master Key: Secure Messaging for Confidentiality.
  • E2 - EMV / Chip Issuer Master Key: Secure Messaging for Integrity.
  • E3 - EMV / Chip Issuer Master Key: Data Authentication Code.
  • E4 - EMV / Chip Issuer Master Key: Dynamic.
  • E5 - EMV / Chip Issuer Master Key: Card Personalization.
  • E6 - EMV / Chip Issuer Master Key: Other Initialization Vector (IV).
  • E7 - EMV / Chip Asymmetric Key Pair for EMV/Smart Card based PIN/PIN Block Encryption.
  • I0 - Initialization Vector (IV).
  • K0 - Key Encryption or wrapping.
  • K1 - X9.143 Key Block Protection Key.
  • K2 - TR-34 Asymmetric Key.
  • K3 - Asymmetric Key for key agreement / key wrapping.
  • K4 - Key Block Protection Key, ISO 20038.
  • M0 - ISO 16609 MAC algorithm 1 (using TDEA).
  • M1 - ISO 9797-1 MAC Algorithm 1.
  • M2 - ISO 9797-1 MAC Algorithm 2.
  • M3 - ISO 9797-1 MAC Algorithm 3.
  • M4 - ISO 9797-1 MAC Algorithm 4.
  • M5 - ISO 9797-1:2011 MAC Algorithm 5.
  • M6 - ISO 9797-1:2011 MAC Algorithm 5 / CMAC.
  • M7 - HMAC.
  • M8 - ISO 9797-1:2011 MAC Algorithm 6.
  • P0 - PIN Encryption.
  • P1 - PIN Generation Key (reserved for ANSI X9.132-202x).
  • S0 - Asymmetric key pair for digital signature.
  • S1 - Asymmetric key pair, CA key.
  • S2 - Asymmetric key pair, nonX9.24 key.
  • V0 - PIN verification, KPV, other algorithm.
  • V1 - PIN verification, IBM 3624.
  • V2 - PIN verification, VISA PVV.
  • V3 - PIN verification, X9-132 algorithm 1.
  • V4 - PIN verification, X9-132 algorithm 2.
  • V5 - PIN Verification Key, ANSI X9.132 algorithm 3.
  • 00 - 99 - These numeric values are reserved for proprietary use.

Type: string, null
Pattern: ^B[0-3]$|^C0$|^D[0-3]$|^E[0-7]$|^I0$|^K[0-4]$|^M[0-8]$|^P[0-1]$|^S[0-2]$|^V[0-5]$|^[0-9][0-9]$
Default: null

keyManagement/decryptAttributes

Attributes supported by the KeyManagement.ImportKey command for the key used to decrypt or unwrap the key being imported.

Type: object, null
Default: null

keyManagement/decryptAttributes/A (example name)

Specifies the encryption algorithms supported by the KeyManagement.ImportKey command. The following values are possible:

  • A - AES.
  • D - DEA.
  • R - RSA.
  • T - Triple DEA (also referred to as TDEA).
  • 0 - 9 - These numeric values are reserved for proprietary use.

Type: object
Name Pattern: ^[0-9ADRT]$

keyManagement/decryptAttributes/A/decryptMethod

Specifies the cryptographic method supported.

If the algorithm is 'A', 'D', or 'T', then one or more of the following properties must be true.

  • ecb - The ECB encryption method.
  • cbc - The CBC encryption method.
  • cfb - The CFB encryption method.
  • ofb - The OFB encryption method.
  • ctr - The CTR method defined in NIST SP800-38A (See [Ref. keymanagement-11]).
  • xts - The XTS method defined in NIST SP800-