1 - Foreword
XFS4IoT has been identified as a successor to XFS 3.x to meet the following requirements:
- Replace the XFS and J/XFS standards in the marketplace.
- Target industries – Retail Banking.
- Operating System Agnostic and Technology and Language Adaptable.
- Multi-Vendor – Able to run common core high level functionality on multiple vendors hardware, while providing access to finer level device API granularity.
- Flexibility – enabling new hardware topologies, device types and functionality to be rapidly adapted.
- Support end to end application level security.
- Should not prevent the use of a low resource computing environment.
- 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.
- 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:
- 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.
- 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
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.
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.2 - Header Definition
The header 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.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 between 1 and 4294967295 inclusive (the maximum value of a 32 bit unsigned integer), incrementing with each command. The maximum value has been chosen for broad implementation compatibility. When the maximum value is reached the client must wrap the value back to 1. 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 requestId on the command is invalid. This could be because the value is not an integer, has a zero value, has not been incremented, exceeds the maximum value, or because a command with the same requestId from the same client connection 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.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 between 1 and 4294967295 inclusive (the maximum value of a 32 bit unsigned integer), incrementing with each command. When the maximum value is reached the client must wrap the value back to 1. 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, except when the previous requestId was at the maximum value of 4294967295, in which case a requestId of 1 is allowed. 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 requestId. The event header will not contain a requestId property. 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:
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.
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:
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:
- Keyboard.DataEntry
- Crypto.CryptoData
- Crypto.Digest
- 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.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 the major number of one of these message types changes changes, the major number of the other will be updated to match even if there are no changes or only minor changes to the other message type.
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.
The major and minor version numbers are incremented according to the scope of change described in the following sections.
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.
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 the client connection has been established with the service. The client is responsible for determining and setting version compatibility using the Common.GetInterfaceInfo and Common.SetVersions commands. These commands should be used before any other command to ensure the service sends message versions compatible with the client. If the client does not use the Common.SetVersions command the service may send message versions which are incompatible with the client. By default, the service will for each client connection, use the lowest available major version of each message it supports.
If incompatible the client must handle the incompatibilities, possibly by not using incompatible commands. If this is not an option, the client should close the connection and not use the service.
The following sequence demonstrates use of the Common.GetInterfaceInfo command to identify the command, event (including unsolicited) versions supported by the service, and the client use of the Common.SetVersions command to inform the service of the event versions that should be sent for the connection on which the command is sent.
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 is added:
- fraudAttempt
This 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 - Configuration
Services may support service specific configuration. To allow clients to retrieve detailed information about the configuration items supported by the service, configuration is defined using JSON schema [Ref. api-4]. This gives clients access to the configuration item names, types, constraints and hierarchy as well as other annotation information such as default values, examples and descriptions.
If descriptions are included these:
- Must be US English (en-US).
- Must be as concise as possible. Vendor documentation must still be used when descriptions are long or complex.
- May have basic Markdown formatting, e.g., bold, italic, ordered and unordered lists.
2.7.1 - Configuration Schema
As configuration is service specific, it is outside the scope of this specification to define the schema.
Clients must use the Common.GetConfigurationSchema command to retrieve the service specific schema.
Clients can then parse the schema definition to identify the configuration items supported by the service then use the Common.GetConfiguration and Common.SetConfiguration commands to get, set and delete configuration as required.
To prevent clients including configuration not supported by the service, the schema must use
"unevaluatedProperties": false to reject any configuration properties not explicitly defined. This removes the
potential for a client to expect specific behavior from the service that the service does not support.
When defining configuration items, it is recommended that configuration items be nested in objects representing the interfaces they configure. If vendor specific, the configuration options should be nested in objects specific to the vendor. This allows for a more organized and maintainable configuration structure that is less likely to clash with other vendor service implementations.
The following example schema demonstrates a configuration schema that could be returned from a service which supports the CashDispenser interface:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"unevaluatedProperties": false,
"properties": {
"cashDispenser": {
"description": "Cash dispenser interface configuration.",
"type": ["object", "null"],
"default": null,
"minProperties": 1,
"unevaluatedProperties": false,
"properties": {
"acme": {
"description": "Acme vendor specific configuration.",
"type": ["object", "null"],
"default": null,
"minProperties": 1,
"properties" : {
"maxDispenseItems": {
"description": "Maximum number of items that can be dispensed.",
"type": ["integer", "null"],
"minimum": 10,
"maximum": 100,
"default": 50
},
"clearTransportOnStartup": {
"description": "Specifies whether the Service Provider will test the device at
start-up and clear any media found in the transport. Valid values are:\n- 'reject'- The reject bin.\n-
'retract' - The retract bin.\n- 'present' - To default output position.",
"type": ["string", "null"],
"enum": ["reject", "retract", "present"],
"default": "reject"
}
}
}
}
}
}
}
2.7.2 - Configuration Command Use
The following sequence diagram demonstrates use of the configuration commands with the example schema:
2.8 - 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.
2.9 - Service Reset
A reset command is used to attempt to reset the primary device(s) back to a known good state. This will typically be the power-on initial state. Primary devices are those which determine the device state.
The service will not attempt to reset ancillary devices used by the service, e.g., a service which utilizes an ancillary device to control lights will not reset the ancillary device but may use it to switch off only those lights associated with the service.
A reset command:
- Should be used if a Common.ErrorEvent event is received, and the action indicates a reset is required.
- May be used when the Common.ErrorEvent action indicates either clear or maintenance manual intervention is required. However, the client should avoid over use of this command if the command repeatedly fails.
- Is not intended to be used when the service indicates the device state is online.
If a service implements multiple interface specific reset commands, clients should only use one. That is clients should not use each available reset 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
Event Messages
4 - Common Interface
This chapter defines the Common interface functionality and messages.
4.1 - Command Messages
4.1.1 - Common.GetInterfaceInfo
This command returns information related to the interfaces supported by the service.
Clients must, prior to use of any other commands, use this command to determine which interfaces, commands and message versions are supported by the service.
Client applications must, prior to use of any other commands, use the Common.SetVersions command to establish the event and unsolicited event message versions received from the service are those the client can handle.
As this command is fundamental to successful communication between the client and service, it is not subject to the same versioning rules as other commands. Command and completion messages will remain at version 1.x.
This command can be used while in Vendor Mode.
Command Message
| Payload, Version 1.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None4.1.2 - Common.SetVersions
This command sets the major version of the event and unsolicited message types the client wants the service to send.
Clients can only set message versions reported by the Common.GetInterfaceInfo command.
If a client requests this command multiple times on the same connection:
- The effect is cumulative. That is, message versions sent by the service are the union of all uses of this command.
- The version of a message specified in the last use of this command replaces any previously set version of that message.
Versions are set only for the client connection on which the command is received.
This command can be used while in Vendor Mode.
Command Message
Completion Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Event Messages
None4.1.3 - 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
Event Messages
None4.1.4 - 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
Event Messages
None4.1.5 - Common.Cancel
This command instructs the service to attempt to cancel one, more or all command requests associated with the client connection on which this command is received.
This command can be used while in Vendor Mode.
Command Message
Completion Message
Event Messages
None4.1.6 - Common.PowerSaveControl
⚠️ This command is deprecated.
This command activates or deactivates the power-saving mode. If the service receives another command while in power-saving mode:
- If the command requires the device to be powered up while in power-saving mode, the service automatically exits the power saving mode, and executes the requested command.
- If the command does not require the device to be powered up while in power-saving mode, the service will not exit the power saving mode.
Command Message
Completion Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Event Messages
None4.1.7 - Common.SetTransactionState
This command allows the application to specify the transaction state, which the service can then utilize in order to optimize performance. After receiving this command, this service can perform the necessary processing to start or end the customer transaction. This command should be called for every service that could be used in a customer transaction. The transaction state applies to every session.
Command Message
Completion Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Event Messages
None4.1.8 - Common.GetTransactionState
This command can be used to get the transaction state.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None4.1.9 - Common.GetCommandNonce
Get a nonce to be included in an Authorization Token for a command that will be used to ensure end to end security.
The device will overwrite any existing stored Command nonce with this new value. The value will be stored for future authentication. Any Authorization Token received will be compared with this stored nonce and if the Token doesn't contain the same nonce it will be considered invalid and rejected, causing the command that contains that Authorization Token to fail.
The nonce must match the algorithm used. For example, HMAC SHA256 means the nonce must be 256 bit/32 bytes.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None4.1.10 - Common.ClearCommandNonce
Clear the command nonce from the device. The command nonce is included in an Authorization Token for a command that will be used to ensure end to end security.
Clearing this value from the device will make any tokens with the old nonce invalid. It will not be possible to use any token, or perform any end-to-end secured operation, until a new nonce is created with Common.GetCommandNonce and a new token is created.
There is no requirement for the client to clear the command nonce, but doing so may be useful for various reasons:
- Clearing the command nonce once the application has finished with it will stop an attacker from using that value and may help improve security.
- Clearing the command nonce will cause the Common.NonceClearedEvent event to be fired immediately which avoids the client having to handle it at a later time. This could make event handling simpler.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Event Messages
None4.1.11 - Common.StartSecureOperation
This command is used in order for the application to indicate the intent to start a sequence of end-to-end security operations, of the type where a device authenticated result is returned via a command completion message.
This command provides an indication to the device to reset any existing data, and start accumulating data that will be included in the token data of the command completion message.
This command is also used to set a unique ID that will be included in the e2e security token. This is used to link together multiple operations in a single token. This is different to the nonce value, which is passed to a single command and included in a single token.
The error code noKeyValue is returned if no keys are loaded. The property
Common.endToEndSecurity can be
used to check the status of the device's end-to-end security support.
Command Message
Completion Message
Event Messages
None4.1.12 - Common.Reset
For a top level description of the generic behavior, expectations and use of a reset command, see Service Reset.
This command must not be implemented by a service if there is an interface specific reset command, e.g., CashManagement.Reset.
Command Message
| Payload, Version 1.0 |
|---|
| This message does not define any properties. |
Completion Message
| Payload, Version 1.0 |
|---|
| This message does not define any properties. |
Event Messages
None4.1.13 - Common.GetConfigurationSchema
This command gets the configuration schema supported by the service. The schema is returned as a JSON object that can be used to determine what configuration is available before calling Common.SetConfiguration.
Command Message
| Payload, Version 1.0 |
|---|
| This message does not define any properties. |
Completion Message
| Payload, Version 1.0 |
|---|
| This message does not define any properties. |
Event Messages
None4.1.14 - Common.GetConfiguration
This command is used to retrieve service configuration.
As configuration is service specific, it is outside the scope of this specification to define the schema contained in the payload.
Command Message
Completion Message
Event Messages
None4.1.15 - Common.SetConfiguration
This command is used to change service configuration.
Configuration is changed using JSON Merge Patch semantics as defined in RFC 7386 [Ref. api-7].
To set configuration item values, include the desired configuration item properties and their new values in the configuration property.
To delete specific configuration items and reset to default values, set the configuration item property to null. Configuration item properties not included in the configuration property will remain unchanged. When changing nested objects, only the specified properties within those objects are affected; other properties in the same object are preserved. To delete all configuration items, set selector to null or "/" and configuration to null.
Array properties cannot be partially changed. Individual array elements cannot be added, changed, or removed using JSON Merge Patch semantics. When the selector targets an array property or when the configuration property contains array values, the entire array must be replaced with a complete new array containing all desired elements. This applies whether the array is at the root level, nested within objects, or targeted directly by the selector. Consider using objects with meaningful keys instead of arrays where possible to enable granular configuration changes.
Configuration changes apply to the service and therefore affect all current and future client connections to that service. Any configuration changes made through this command will be visible to all connected clients and will persist for new connections established after the configuration changes. Configuration changes are stored persistently and will remain in effect across service restarts and system reboots.
If the specified configuration fails to validate against the schema returned from Common.GetConfigurationSchema the command will complete with completionCode invalidData and errorDescription will contain details of the validation errors.
If the specified configuration cannot be applied because the amount of storage required exceeds the available space, the command will complete with completionCode notEnoughSpace.
If the specified configuration is valid but does not change existing configuration, the command will complete with completionCode success.
If the command complete with any completionCode other than success none of the specified configuration items will be changed.
If configuration is changed a Common.ConfigurationChangedEvent will be sent. The event payload will only include configuration items that have changed.
Command Message
Completion Message
Event Messages
None4.2 - Unsolicited Messages
4.2.1 - Common.StatusChangedEvent
This event reports that a change of state has occurred. The new value of all properties which have changed value are included in the event payload. Any properties which have not changed state are null.
Unsolicited Message
4.2.2 - Common.ErrorEvent
This event reports that an error has occurred. In most cases, this is in addition to being reported via the error code that is returned as the command completion.
In order to supply the maximum information, these events should be sent as soon as an error is detected. In particular, if an error is detected during the processing of a command, then the event should be sent before the command completion message.
Unsolicited Message
4.2.3 - Common.NonceClearedEvent
This event reports that the end-to-end security nonce value has been cleared on the device. This could be because the nonce was explicitly cleared with Common.ClearCommandNonce, automatically cleared by a timeout, or cleared by actions documented for each device.
Unsolicited Message
4.2.4 - Common.ConfigurationChangedEvent
This event indicates the service configuration has changed.
The payload will contain the current values of the configuration items which changed.
Configuration payloads are service specific. See Configuration for details of how to get and set service specific configuration.
Unsolicited Message
| Payload, Version 1.0 |
|---|
| This message does not define any properties. |
5 - Card Reader Interface
This chapter defines the Card Reader interface functionality and messages.
This interface allows for the operation of the following categories of card readers:
- Motorized card reader/writer
- Swipe card reader (writing facilities only partially included)
- Dip card reader
- Latched dip card reader
- Contactless chip card readers
- Permanent chip card readers (each chip is accessed through a unique service)
Some motorized card reader/writers have storage units from which cards can be dispensed. Some have storage units in which a card can temporarily be parked to enable another card to be moved into the card reader.
The following tracks/chips and the corresponding international standards are considered in this document:
- Track 1 - ISO 7811
- Track 2 - ISO 7811
- Track 3 - ISO 7811 / ISO 4909
- Cash Transfer Card Track 1 - (JIS I: 8 bits/char) Japan
- Cash Transfer Card Track 3 - (JIS I: 8 bits/char) Japan
- Front Track 1 - (JIS II) Japan
- Watermark - Sweden
- Chip (contacted) - ISO 7816
- Chip (contactless) - ISO 10536, ISO 14443 and ISO 18092
In addition to the pure reading of the tracks mentioned above, security boxes can be used via this service to check the data of writable tracks for manipulation. These boxes (such as CIM or MM) are sensor-equipped devices that can check some other information on the card and compare it with the track data.
When the service controls a permanently connected chip card, unsupportedCommand will be returned to all commands except Common.Status, Common.Capabilities, CardReader.ChipPower, CardReader.ChipIO and CardReader.Reset.
The following defines the roles and responsibilities of an application within EMV: A distinction needs to be made between EMV Contact support and EMV Contactless support.
When defining an EMV Contact implementation:
- EMV Level 2 interaction is handled by the client or above.
- EMV Level 1 interaction is handled by the device.
All EMV status information that is defined as a Level 1 responsibility in the EMV specification should be handled by the service.
EMVCo grants EMV Level 1 Approvals to contact IFMs and EMVCo Level 2 Approvals to Application Kernels.
When defining an EMV Contactless implementation, the responsibilities will depend on the type of EMV contactless product being implemented.
There are different EMVCo defined product types. They can be found in the EMVCo Type Approval - Contactless Product - Administrative Process document [Ref. cardreader-1]. In this specification when referring to the Contactless Product Type, Intelligent Card Reader, the following must be included and handled by the device:
- An EMVCo Approved Level 1 Contactless PCD
- Entry Point and POS System Architecture according to Book A and B
- EMV Kernels according to Book C1 to C7 (minimum one kernel needs to be supported)
The Network, Consumer and Merchant Interfaces will be managed by the client or above.
5.1 - General Information
5.1.1 - References
| ID | Description |
|---|---|
| cardreader-1 | EMVCo Terminal Type Approval Contactless Product Administrative Process 2.9 |
| cardreader-2 | EMVCo Integrated Circuit Card Specifications for Payment Systems Version 4.3 |
| cardreader-3 | EMVCo Contactless Specifications for Payment Systems, Version 2.4 |
| cardreader-4 | ISO 8583:1987 Bank card originated messages — Interchange message specifications — Content for financial transactions |
| cardreader-5 | ISO 4217 |
5.1.2 - Intelligent Contactless Card Reader
In relation to contactless transactions, the terminology used in this specification is based on the EMV Contactless Specifications for Payment Systems. See References.
There are a number of types of payment systems (or EMV) compliant contactless card readers, from the Intelligent Card Reader where the reader device handles most of the transaction processing and only returns the result, to a transparent card reader where the contactless card reader device provides a generic communication channel to the card without having any in-built transaction processing capabilities.
A contactless payment system transaction can be performed in two different ways, magnetic stripe emulation where the data returned from the chip is formatted as if it was read from the magnetic stripe, and EMV-like where, in a similar way to a contact EMV transaction, the chip returns a full set of BER-TLV (Basic Encoding Rules-Tag Length Value) data. Each payment system defines when each type, or profile, is used for a transaction, but it is usually dependent on both the configuration of the terminal and contactless card being tapped.
This specification will use “magnetic stripe emulation” and “EMV-like” to identify the two profiles of contactless transactions.
Support for a generic contactless communication channel to the card is provided via the CardReader.ChipIO command. This is suitable for use with a transparent contactless card reader or with an intelligent contactless card reader device operating in a pass-through mode.
The CardReader.ReadRawData command can be used with an intelligent contactless card reader device to provide magnetic track emulation transactions. Only magnetic track emulation transactions can be supported using this command.
When using an intelligent contactless card reader to support both EMV-like and magnetic track emulation transactions a number of commands are required. The CardReader.EMVClessConfigure command allows the exchange of data to configure the reader for card acceptance and the CardReader.EMVClessPerformTransaction command enables the reader and performs the transaction with the card when it is tapped. In most cases all the transaction steps involving the card are completed within the initial card tap. A sequence diagram showing the expected command sequences, as well as the cardholder and client actions when performing a contactless card based transaction.
Some contactless payment systems allow a 2nd tap of the contactless card. For example, a 2nd tap can be used to process authorization data received from the host. In the case of issuer update data this second tap is performed via the CardReader.EMVClessIssuerUpdate command. A sequence diagram showing the expected CardReader command sequences, as well as the cardholder and client actions. The CardReader.EMVClessQueryApplications and CardReader.EMVClessConfigure commands specified later in this document refer to the EMV terminology “Application Identifier (AID) - Kernel Combinations”. A detailed explanation can be found in Refs. [cardreader-2] and [cardreader-3].
This document refers to BER-TLV tags. These are defined by each individual payment systems and contain the data exchanged between the client, contactless card and an intelligent contactless card reader. They are used to configure and prepare the intelligent contactless card reader for a transaction and are also part of the data that is returned by the reader on completion of a card tap.
Based on the applicable payment system application is expected to know which tags are required to be configured, what values to use for the tags and how to interpret the tags returned. Intelligent readers are expected to know the BER-TLV tag definitions supported per payment system application. The tags provided in this document are examples of the types of tags applicable to each command. They are not intended to be a definite list.
5.2 - Command Messages
5.2.1 - CardReader.QueryIFMIdentifier
This command is used to retrieve the complete list of registration authority Interface Module (IFM) identifiers. The primary registration authority is EMVCo, but other organizations are also supported for historical or local country requirements.
New registration authorities may be added in the future so applications should be able to handle the return of any additional properties included in ifmIDs.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None5.2.2 - CardReader.EMVClessQueryApplications
This command is used to retrieve the supported payment system applications available within an intelligent contactless card unit. The payment system application can either be identified by an AID or by the AID in combination with a Kernel Identifier. The Kernel Identifier has been introduced by the EMVCo specifications; see [Ref. cardreader-3].
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None5.2.3 - CardReader.ReadRawData
For motor driven card readers, the card unit checks whether a card has been inserted. If so, all specified tracks are read immediately. If reading the chip is requested, the chip will be contacted and reset and the ATR (Answer To Reset) data will be read. When this command completes the chip will be in contacted position. This command can also be used for an explicit cold reset of a previously contacted chip.
This command should only be used for user cards and should not be used for permanently connected chips.
If no card has been inserted, and for all other categories of card readers, the card unit waits for the period of time specified in the call for a card to be either inserted or pulled through. The next step is trying to read all tracks specified.
The CardReader.InsertCardEvent will be generated when there is no card in the card reader and the device is ready to accept a card.
For non-motorized card readers which read track data on card exit, the invalidData completion code is returned when a call to this command is made to read both track data and chip data.
For latched dip card readers, the device may, dependent on configuration, automatically latch the card when the chip card will be read, i.e. chip is specified. To make sure the card is unlatched so that it can be removed by the card holder, the CardReader.Move command must be issued.
For contactless chip card readers, a collision of two or more card signals may happen. In this case, if the device is not able to pick the strongest signal, the cardCollision error will be returned.
Command Message
Completion Message
Event Messages
5.2.4 - CardReader.WriteRawData
For motor-driven card readers, the ID card unit checks whether a card has been inserted. If so, the data is written to the tracks.
If no card has been inserted, and for all other categories of devices, the ID card unit waits for the application specified timeout for a card to be either inserted or pulled through. The next step is writing the data to the respective tracks.
The CardReader.InsertCardEvent event will be generated when there is no card in the card reader and the device is ready to accept a card.
The application must pass the magnetic stripe data in ASCII without any sentinels, encoded in Base64 (See CardReader.ReadRawData). If the data passed in is too long the invalidData error code will be returned.
This procedure is followed by data verification.
If power fails during a write the outcome of the operation will be vendor specific, there is no guarantee that the write will have succeeded.
Command Message
Completion Message
Event Messages
5.2.5 - CardReader.Move
This command is only applicable to motorized and latched dip card readers.
If after a successful completion event the card is at the exit position, the card will be accessible to the user. A CardReader.MediaRemovedEvent is generated to inform the application when the card is taken.
Motorized card readers
Motorized card readers can physically move cards from or to the transport or exit positions or a storage unit. The default operation is to move a card in the transport position to the exit position.
If the card is being moved from the exit position to the exit position, these are valid behaviors:
- The card does not move as the card reader can detect the card is already in the correct position.
- The card is moved back into the card reader then moved back to the exit to ensure the card is in the correct position.
Latched dip card readers
Latched dips card readers can logically move cards from the transport position to the exit position by unlatching the card. That is, the card will not physically move but will unlatch the card so that it can be removed by the card holder. If the media state is latched this command must be issued to make sure the card is unlatched so that it can be removed by the card holder. Dependent on configuration, the card may be physically latched or unlatched.
Command Message
Completion Message
Event Messages
None5.2.6 - CardReader.SetKey
This command is used for setting the DES key that is necessary for operating a CIM86 module. The command must be executed before the first read command is issued to the card reader.
Command Message
Completion Message
Event Messages
None5.2.7 - CardReader.ChipIO
This command is used to communicate with the chip. Transparent data is sent from the application to the chip and the response of the chip is returned transparently to the application.
The identification information, e.g., ATR of the chip must be obtained before issuing this command. The identification information for a user card or the Memory Card Identification (when available) must initially be obtained using CardReader.ReadRawData. The identification information for subsequent resets of a user card can be obtained using either CardReader.ReadRawData or CardReader.ChipPower. The ATR for permanent connected chips is always obtained through CardReader.ChipPower.
For contactless chip card readers, applications need to specify which chip to contact with, as part of chipData, if more than one chip has been detected and multiple identification data has been returned by the CardReader.ReadRawData command.
For contactless chip card readers a collision of two or more card signals may happen. In this case, if the device is not able to pick the strongest signal, the cardCollision error code will be returned.
Command Message
Completion Message
Event Messages
None5.2.8 - CardReader.Reset
For a top level description of the generic behavior, expectations and use of a reset command, see Service Reset.
If the device is a user card reader:
-
Dependent on the command properties, the device will attempt to move a card in transport or exit positions to the exit or transport positions or a retain storage unit.
-
For each card in the device (including parking storage units), a CardReader.MediaDetectedEvent will indicate the position or state of the card on completion of this command.
-
Dependent on device state, it may not be possible to move a card.
If the device is a permanent chip card unit, this command will power-off the chip.
Command Message
Completion Message
Event Messages
None5.2.9 - CardReader.ChipPower
This command handles the power actions that can be done on the chip.
For user chips, this command is only used after the chip has been contacted for the first time using the CardReader.ReadRawData command. For contactless user chips, this command may be used to deactivate the contactless card communication.
For permanently connected chip cards, this command is the only way to control the chip power.
Command Message
Completion Message
Event Messages
None5.2.10 - CardReader.EMVClessConfigure
This command is used to configure an intelligent contactless card reader before performing a contactless transaction. This command sets terminal related data elements, the list of terminal acceptable applications with associated application specific data and any encryption key data required for offline data authentication.
This command should be used prior to CardReader.EMVClessPerformTransaction. It may be called once on application start up or when any of the configuration parameters require to be changed. The configuration set by this command is persistent.
This command should be called with a complete list of acceptable payment system applications as any previous configurations will be replaced.
Command Message
Completion Message
Event Messages
None5.2.11 - CardReader.EMVClessPerformTransaction
This command is used to enable an intelligent contactless card reader. The transaction will start as soon as the card tap is detected.
Based on the configuration of the contactless chip card and the reader device, this command could return data formatted either as magnetic stripe information or as a set of BER-TLV encoded EMV tags.
This command supports magnetic stripe emulation cards and EMV-like contactless cards but cannot be used on storage contactless cards. The latter must be managed using the CardReader.ReadRawData and CardReader.ChipIO commands.
For specific payment system's card profiles an intelligent card reader could return a set of EMV tags along with magnetic stripe formatted data. In this case, two contactless card data structures will be returned, one containing the magnetic stripe like data and one containing BER-TLV encoded tags.
If no card has been tapped, the contactless chip card reader waits for the period of time specified in the command call for a card to be tapped.
For intelligent contactless card readers, any in-built audio/visual feedback such as Beep/LEDs, need to be controlled directly by the reader. These indications should be implemented based on the EMVCo and payment system's specifications.
Command Message
Completion Message
Event Messages
5.2.12 - CardReader.EMVClessIssuerUpdate
This command performs the post authorization processing on payment systems contactless cards.
Before an online authorized transaction is considered complete, further chip processing may be requested by the issuer. This is only required when the authorization response includes issuer update data; either issuer scripts or issuer authentication data.
The command enables the contactless card reader and waits for the customer to re-tap their card.
The contactless chip card reader waits for the period of time specified in the command request for a card to be tapped.
Command Message
Completion Message
Event Messages
5.3 - Event Messages
5.3.1 - CardReader.InsertCardEvent
This event notifies the application when the device is ready for the user to insert a card.
Event Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
5.3.2 - CardReader.MediaInsertedEvent
This event specifies that a card was inserted into the device.
Event Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
5.3.3 - CardReader.InvalidMediaEvent
This event specifies that the media the user is attempting to insert is not a valid card or it is a card but it is in the wrong orientation.
Event Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
5.3.4 - CardReader.TrackDetectedEvent
This event notifies the application what track data the inserted card has before the reading of the data has completed. This event will be posted once when tracks are detected during card insertion.
Event Message
5.3.5 - CardReader.EMVClessReadStatusEvent
This notifies that the communication (i.e., the commands exchanged linked to the tap) between the card and the intelligent contactless card reader are complete. The application can use this event to display intermediate messages, progress of card read, audio signals or anything else that might be required. The intelligent contactless card reader will continue the processing and the result of the processing will be returned in the output of the CardReader.EMVClessPerformTransaction command.
Event Message
5.4 - Unsolicited Messages
5.4.1 - CardReader.MediaRemovedEvent
This unsolicited event indicates the card was manually removed by the user either during processing of a command which requires the card to be present or the card is removed from the exit position.
Unsolicited Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
5.4.2 - CardReader.CardActionEvent
This event specifies where a card has been moved to by either the automatic power on or power off action of the device.
Unsolicited Message
5.4.3 - CardReader.MediaDetectedEvent
This is generated if media is detected during a CardReader.Reset. The event payload informs the application of the position or state of a card on the completion of the CardReader.Reset command. For devices with park storage units, there will be one event for each card found.
Unsolicited Message
6 - Cash Management Interface
This chapter defines the Cash Management interface functionality and messages.
This specification describes the functionality of an XFS4IoT compliant Cash Management interface. It defines the service-specific commands that can be issued to the service using the WebSocket endpoint.
This interface is to be used together with Storage, Cash Dispenser and/or Cash Acceptor interfaces to handle management of storage units, cash counts and banknote information.
6.1 - General Information
6.1.2 - Note Classification
Cash items are classified by the XFS4IoT specification according to the following definitions. Local requirements or device capability define which of these classifications are supported - see Common.Capabilities classifications. A cash item can only be classified as one of the following:
-
Not recognized (level 1 in XFS 3.x), defined as unrecognized in XFS4IoT.
-
Recognized counterfeit item (level 2 in XFS 3.x), defined as counterfeit in XFS4IoT.
-
Suspected counterfeit item (level 3 in XFS 3.x), defined as suspect in XFS4IoT.
-
Inked, defined as inked in XFS4IoT. Inked-stained banknotes are typically items which have been stained by anti-theft devices.
-
Genuine note (level 4 in XFS 3.x). Genuine items are further classified as follows:
- Fit for recycling, defined as fit in XFS4IoT
- Unfit for recycling, defined as unfit in XFS4IoT
Once classified as such, how items are handled may depend on local requirements or legislative note handling standards that may exist in various countries and economic regions. This can be used to support note handling functionality which includes:
-
Whether counterfeit or suspect items allowed to be returned to the customer during a cash-in transaction
-
The ability to remove counterfeit notes from circulation.
-
Reporting of recognized, counterfeit and suspected counterfeit notes.
-
Creating and reporting of note signatures in order to allow back-tracing of notes.
A note's classification can be changed based on the item's serial number, currency and value by specifying a classification list - see CashManagement.SetClassificationList. A classification list can be used to re-classify a matching item to a lower level, including classifying a genuine note as unfit for dispensing. Once reclassified, the note will be automatically handled according to the local country specific note handling standard or legislation for the note's new note classification, including any note retention rules. Any reclassification will result in the normal events and behavior, for example a CashManagement.InfoAvailableEvent will reflect the note's reclassification. Reclassification can be used to make dynamic changes to note handling procedures without a software upgrade, enabling functionality such as taking older notes out of circulation or handling of counterfeit notes on a local basis (commonly known as a blacklist). Note that if reclassification of an item is performed after a command which generates a CashManagement.InfoAvailableEvent, it has no impact on the content of the note information; the note’s classification remains what it was reported when the note was classified.
Reclassification cannot be used to change a note's classification to a level which makes it more likely to be accepted, for example, a note recognized as counterfeit by the device cannot be reclassified as genuine. In addition, it is not possible to re-classify a counterfeit note as unrecognized. No particular use case has been identified for reclassifying suspect or genuine items as unrecognized, but there is no reason to restrict this reclassification.
Classification lists can be specified using CashManagement.SetClassificationList and retrieved using CashManagement.GetClassificationList.
The classification list functionality can use a mask to specify serial numbers. The mask is defined as follows: A '?' character (0x003F) is the wildcard used to match a single Unicode character, and a '*' character (0x002A) is the wildcard used to match one or more Unicode characters.
For example, "S8H9??16?4" would represent a match for the serial numbers "S8H9231654" and "S8H9761684". A mask of "HD90*2" would be used to match serial numbers that begin with "HD90" and end with "2", for example "HD9028882", "HD9083276112". Note that the mask can only use one asterisk, and if a real character is required then it must be preceded by a backslash, for example: '\\' for a backslash, '\*' for an asterisk or '\?' for a question mark. Note that this flexibility means that it is possible to overlap definitions, for example "HD90*" and "HD902*" would both match on the serial number HD9028882".
6.2 - Command Messages
6.2.1 - CashManagement.GetBankNoteTypes
This command is used to obtain information about the banknote types that can be detected by the banknote reader or are supported by the configuration.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None6.2.2 - CashManagement.GetTellerInfo
This command only applies to Teller devices. It allows the application to obtain counts for each currency assigned to the teller. These counts represent the total amount of currency dispensed by the teller in all transactions.
This command also enables the application to obtain the position assigned to each teller. The teller information is persistent.
Command Message
Completion Message
Event Messages
None6.2.3 - CashManagement.SetTellerInfo
This command allows the application to initialize counts for each currency assigned to the teller. The values set by this command are persistent. This command only applies to Teller ATMs.
Command Message
Completion Message
Event Messages
None6.2.4 - CashManagement.GetItemInfo
This command is used to get information about detected items. It can be used to get information about individual items, all items of a certain classification, or all items that have information available. This information is available from the point where the first CashManagement.InfoAvailableEvent is generated until a transaction or replenishment command is executed including the following:
In addition, since the item information is not cumulative and can be replaced by any command that can move notes, it is recommended that applications that are interested in the available information should query for it following the CashManagement.InfoAvailableEvent but before any other command is executed.
Command Message
Completion Message
Event Messages
None6.2.5 - CashManagement.GetClassificationList
This command is used to retrieve the entire note classification information pre-set inside the device or set via the CashManagement.SetClassificationList command. This provides the functionality to blacklist notes and allows additional flexibility, for example to specify that notes can be taken out of circulation by specifying them as unfit. Any items not returned in this list will be handled according to normal classification rules.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None6.2.6 - CashManagement.SetClassificationList
This command is used to specify the entire note classification list. Any items not specified in this list will be handled according to normal classification rules. This information is persistent. Information set by this command overrides any existing classification list. If a note is reclassified, it is handled as though it was a note of the new classification. For example, a fit note reclassified as unfit would be treated as though it were unfit, which may mean that the note is not dispensed. Reclassification cannot be used to change a note’s classification to a higher level, for example, a note recognized as counterfeit by the device cannot be reclassified as genuine. In addition, it is not possible to re-classify a counterfeit note as unrecognized. If two or more classification elements specify overlapping note definitions, but different level values then the first one takes priority.
Command Message
Completion Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Event Messages
None6.2.7 - CashManagement.CloseShutter
This command closes the shutter.
Command Message
Completion Message
Event Messages
None6.2.8 - CashManagement.OpenShutter
This command opens the shutter.
In cases where multiple bunches are to be returned under explicit shutter control and the first bunch has already been presented and taken and the output position is empty, this command moves the next bunch to the output position before opening the shutter. This does not apply if the output position is not empty, for example if items had been re-inserted or dropped back into the output position as the shutter closed.
Command Message
Completion Message
Event Messages
None6.2.9 - CashManagement.Retract
This command retracts items from an output position or internal areas within the device. Retracted items will be moved to either a retract bin, a reject bin, cash-in/recycle storage units, the transport or an intermediate stacker area. If items from internal areas within the device are preventing items at an output position from being retracted, then the items from the internal areas will be retracted first. When the items are retracted from an output position the shutter is closed automatically, even if property shutterControl is false.
This command terminates a running transaction. The transaction is terminated even if this command does not complete successfully.
As the items to be retracted may be in different areas of the device, it may be possible to have combinations of events and completions related to how these discrete bunches are handled. For example if items are in the stacker and other items are presented, and the customer takes the presented items, then it is possible to post a CashManagement.ItemsTakenEvent as well as an additional Storage.StorageErrorEvent or a CashManagement.IncompleteRetractEvent for the remaining items.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
Command Message
Completion Message
Event Messages
6.2.10 - CashManagement.Reset
For a top level description of the generic behavior, expectations and use of a reset command, see Service Reset.
If a cash-in transaction is active or exchange is active then this command will end the transaction or exchange state as appropriate, even if this command does not complete successfully.
Persistent values, such as counts and configuration information are not cleared by this command.
The device will attempt to move any items found anywhere within the device to the position specified within the command parameters. This may not always be possible because of hardware problems. If the application does not wish to specify a storage unit or position it can set target to null. In this case the device will determine where to move any items found.
When end-to-end (E2E) security is being enforced by a device, if this command would result in notes being moved to a position where they would be accessible, this command will be blocked from executing. The exact definition of 'accessible' is hardware dependent but, for example, any position outside the safe, or any position where a attacker could access the cash should mean the command is blocked. Any attempt to execute the command will complete with the completion code unsupportedCommand. This is required because there is currently no E2E security defined for this command, and if the command were permitted it would be possible to extract cash and bypass E2E security.
As the items to be retracted may be in different areas of the device, it may be possible to have combinations of events and completions related to how these discrete bunches are handled. For example if items are in the stacker and other items are presented, and the customer takes the presented items, then it is possible to post a CashManagement.ItemsTakenEvent as well as an additional Storage.StorageErrorEvent or a CashManagement.IncompleteRetractEvent for the remaining items.
If items are found inside the device one or more CashManagement.MediaDetectedEvents will be generated to inform the application where the items have been moved to.
The shutterControl property will determine whether the shutter is controlled implicitly by this command or whether the application must explicitly open and close the shutter using the CashManagement.OpenShutter, CashManagement.CloseShutter or CashAcceptor.PresentMedia commands. If shutterControl is false then this command does not operate the shutter in any way, the application is responsible for all shutter control. If shutterControl is true, then this command operates the shutter as necessary so that the shutter is closed after the command completes successfully and any items returned to the customer have been removed.
The presentControl property will determine whether it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is true then all items are moved immediately to the correct output position for removal (a CashManagement.OpenShutter command will be needed in the case of explicit shutter control). If presentControl is false, then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
If requested, items are returned in a single bunch or multiple bunches in the same way as described for the CashAcceptor.CashIn command.
If performing a Mixed Media transaction and media items are to be moved to a storage unit or units, the requested unit(s) must support types appropriate to the media being stored.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
Command Message
Completion Message
Event Messages
6.2.11 - CashManagement.CalibrateCashUnit
This command will cause a vendor dependent sequence of hardware events which will calibrate one storage unit. This is necessary if a new type of bank note is put into the storage unit as the command enables the device to obtain the measures of the new bank notes.
This command cannot be used to calibrate storage units which have been locked by the application. An error code will be returned and a Storage.StorageErrorEvent generated.
Command Message
Completion Message
Event Messages
6.3 - Event Messages
6.3.1 - CashManagement.NoteErrorEvent
This event specifies the reason for a note detection error during the execution of a command.
Event Message
6.3.2 - CashManagement.InfoAvailableEvent
This event is generated when information is available for items detected during the cash processing operation.
Event Message
6.3.3 - CashManagement.IncompleteRetractEvent
This event is generated when an attempt to retract items has completed with an error and not all items have been retracted.
Event Message
6.4 - Unsolicited Messages
6.4.1 - CashManagement.TellerInfoChangedEvent
This event is generated when the counts assigned to a teller have changed. This event is only returned as a result of a CashManagement.SetTellerInfo command.
Unsolicited Message
6.4.2 - CashManagement.ItemsTakenEvent
This specifies that items have been taken. This event may be generated at any time.
Unsolicited Message
6.4.3 - CashManagement.ItemsInsertedEvent
This specifies that items have been inserted into the position by the user. This event may be generated at any time.
Unsolicited Message
6.4.4 - CashManagement.ItemsPresentedEvent
This specifies that items have been presented to the user, and the shutter has been opened to allow the user to take the items.
Unsolicited Message
6.4.5 - CashManagement.MediaDetectedEvent
This is generated if media is detected during a CashManagement.Reset command. The payload specifies the position of the media on completion of the command. If the device has been unable to successfully move the items found, then target will be null.
Unsolicited Message
6.4.6 - CashManagement.ShutterStatusChangedEvent
⚠️ This event is deprecated.
Within the limitations of the hardware sensors this event is generated whenever the status of a shutter changes. The shutter status can change because of an explicit, implicit or manual operation depending on how the shutter is operated.
This event is marked deprecated because it is replaced by Common.StatusChangedEvent.
Unsolicited Message
7 - Cash Dispenser Interface
This chapter defines the Cash Dispenser interface functionality and messages.
This specification describes the functionality of an XFS4IoT compliant Cash Dispenser interface. It defines the service-specific commands that can be issued to the service using the WebSocket endpoint.
Persistent values are maintained through power failures, open sessions, close sessions and system resets.
This specification covers the dispensing of items. An "item" is defined as any media that can be dispensed and includes coupons, documents, bills and coins.
7.2 - Command Messages
7.2.1 - CashDispenser.GetMixTypes
This command is used to obtain a list of supported mix algorithms and available house mix tables.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None7.2.2 - CashDispenser.GetMixTable
This command is used to obtain the specified house mix table. Mix tables can be set using CashDispenser.SetMixTable.
Command Message
Completion Message
Event Messages
None7.2.3 - CashDispenser.GetPresentStatus
This command is used to obtain the status of the most recent attempt to dispense and/or present items to the customer from a specified output position. The items may have been dispensed and/or presented as a result of the CashDispenser.Present or CashDispenser.Dispense command. This status is not updated as a result of any other command that can dispense/present items.
This value is persistent and is valid until the next time an attempt is made to present or dispense items to the customer, including across power cycles.
The denominations reported by this command may not accurately reflect the operation if the storage units have been re-configured, e.g., if the values associated with a storage unit are changed, or new storage units are configured.
If end-to-end security is supported, then this value is not cleared if a CashDispenser.Dispense with an invalid token is received. If a dispense token is invalid the dispense will fail with an invalidToken error, and the command will continue to report the existing status. This is to stop an attacker being able to reset the present status and conceal the last present result.
If end-to-end security is supported by the hardware, the present status will be protected by a security token. If end-to-end security is not supported then it's not possible to guarantee that the present status hasn't been altered, possibly by an attacker trying to hide the fact that cash was presented. To avoid this risk the client must always call this command and validate the security token.
If end-to-end security is being used the caller must pass in a nonce value. This value will be included in the security token that is returned. The caller must check that the original nonce value matches the token - if they do not match then the token is invalid.
Command Message
Completion Message
Event Messages
None7.2.4 - CashDispenser.Denominate
This command provides a denomination which specifies the number of items which are required from each storage unit to satisfy a given request and can be used to validate that any request supplied by the application can be dispensed. Requests are validated against the number of items and availability of each requested storage unit.
The request contains one of the following items:
- A service mix where the amount to be denominated is provided and the service determines the mix of items to meet the request. The algorithm or mix table used to determine the mix is specified and may include a partial list of items from specific storage units which must be included in the denomination. A partial mix must be specified if items of no currency value are to be included such as coupons or documents.
- An application mix where the number of items from each storage unit in the denomination is pre-determined and the request confirms whether it is possible to dispense that mix of items.
Multiple currencies may be specified using currencies.
If cashBox is true, then if the entire request cannot be satisfied by the service, the denomination may include an amount to be supplied from the teller's cash box.
Command Message
Completion Message
Event Messages
7.2.5 - CashDispenser.Dispense
This command dispenses items from the storage units. See CashDispenser.Denominate for a description of how the denomination may be specified. The items are moved to the intermediate stacker if the device has one, and a CashDispenser.Present command is used to present the items to the user. If the device does not have an intermediate stacker the items will be presented to the user using this command. The position property in the command data specifies which output position the items are intended to be presented to, and applies whether or not the items are actually presented by this command as items may need to be stacked in a particular position ready for presentation at the intended output position.
If cashBox is true and the entire denomination cannot be satisfied, a partial denomination will be returned with the remaining amount to be supplied from the teller's cash box.
If the device is a Teller Dispenser, position can be set to outDefault. If this is the case the tellerID is used to perform the dispense operation to the assigned teller position.
Note that a genuine note can be dispensed, but is not necessarily presented to the customer, e.g., a note can be skewed or can be unfit for dispensing.
The values in the completion message report the amount dispensed and the number of items dispensed from each storage unit.
If the dispensed amount cannot be presented in one bunch of items, but the device can automatically split it into multiple bunches, this will be denoted by the bunches property in the completion message. If it is set to "unknown" or a value larger than "1" multiple presents will be necessary. If the value is set to "1" the dispensed amount can be presented in one present operation.
The process of dispensing and presenting cash may be protected by end-to-end security. This means that the hardware will generate a command nonce (returned by Common.GetCommandNonce) and the caller must use this to create a security token that authorizes dispensing the cash.
It is possible to do multiple dispense and present operations in a row using the same dispense token, as long as the total value of cash doesn't exceed the value authorized by the token.
The device will track the command nonce and E2E token used during dispense operations. Only one token can be used with the current nonce - once a dispense command is called with a token then that token will be remembered, and it will not be possible to perform a dispense command with a different token until the original nonce and token are cleared.
The device will track the total value of cash that has been dispensed and presented using the current token. The device will block any attempt to dispense or present more cash than authorized by the current token.
Once the value of cash that has been dispensed and presented reaches the value of the token, the command nonce stored in the device will be cleared. This has the effect of making any existing tokens invalid so that they can't be used again. No more cash can be dispensed until a new command nonce is read and a new token is generated.
The command nonce may be cleared for other reasons too, for example after a power failure or after a fixed time. Any tokens using the old command nonce value will become invalid when the command nonce is cleared.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
Command Message
Completion Message
Event Messages
7.2.6 - CashDispenser.Present
This command will move items to the exit position for removal by the user. If a shutter exists, then it will be implicitly controlled during the present operation, even if shutterControl is false. The shutter will be closed when the user removes the items or the items are retracted. If the default position is specified the position set in the CashDispenser.Dispense command which caused these items to be dispensed will be used.
In the case where the shutter is unlocked but deliberately held shut, if the items could have been in customer access, then the errorCode presentErrorItems will be returned.
When this command successfully completes the items are in customer access.
If the previous CashDispenser.Dispense command specified that the amount must be presented in multiple bunches, the completion message includes details about remaining bunches. The additionalBunches property specifies whether there are any additional bunches to be dispensed to the customer and the number of outstanding present operations.
If the dispense operation is protected by end-to-end security, then the device will track the total value of cash presented. Once the value of cash that has been dispensed and presented reaches the value of the token, the command nonce stored in the device will be cleared. This has the effect of making any existing tokens invalid so that they can't be used again. No more cash can be dispensed until a new command nonce is read and a new token is generated.
Command Message
Completion Message
Event Messages
7.2.7 - CashDispenser.Reject
This command will move items from the intermediate stacker to a reject storage unit. The storage unit's counts are incremented by the number of items that were or were thought to be present at the time of the Reject or the number counted by the device during the Reject. Note that the Reject storage unit counts may be unreliable.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
7.2.8 - CashDispenser.SetMixTable
This command is used to set up the mix table specified by the mixNumber. Mix tables are persistent and are available to all applications in CashDispenser.Dispense and CashDispenser.Denominate commands. If mix table specified by the mixNumber already exists, then the information is overwritten with the new information.
A mix specifies how a given requested amount is composed of a set of cash items, for example USD 100 could be 5 x USD 20 or 10 x USD 10. A mix table specifies multiple mixes. An amount can be specified multiple times to include different combinations of cash items, if an amount is specified more than once the service will attempt to denominate or dispense the first amount in the table. If this mix is not possible (e.g., because of a storage unit failure) the service will search for the first mix which is possible. The service can only dispense amounts which are explicitly mentioned in the mix table.
Available mixes are reported by CashDispenser.GetMixTypes and the details of a stored mix table can be queried using CashDispenser.GetMixTable.
Command Message
Completion Message
Event Messages
None7.2.9 - CashDispenser.TestCashUnits
This command is used to test cash dispense storage units following replenishment. The command payload specifies where items dispensed as a result of this command should be moved to.
The operation performed to test the storage units is vendor dependent.
All storage units which match the following criteria are tested.
- cashOut is true
- status is ok
- replenishmentStatus is not empty
- appLockOut is false
If the hardware is able to do so tests are continued even if an error occurs while testing one of the storage units. The command completes with success completion message if the service successfully manages to test all the testable cash units regardless of the outcome of the test. This is the case if all testable storage units could be tested and a dispense was possible from at least one of the storage units.
A Storage.StorageErrorEvent will be sent for any cashOut unit which cannot be tested, or which failed the test. If no storage units could be tested or no storage units are testable then a cashUnitError code will be returned and Storage.StorageErrorEvent events generated for every storage unit that encountered a problem.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
When end-to-end (E2E) security is being enforced by a device, if this command would result in notes being moved to a position where they would be accessible, this command will be blocked from executing. The exact definition of 'accessible' is hardware dependent but, for example, any position outside the safe, or any position where a attacker could access the cash should mean the command is blocked. Any attempt to execute the command will complete with the completion code unsupportedCommand. This is required because there is currently no E2E security defined for this command, and if the command were permitted it would be possible to extract cash and bypass E2E security.
Command Message
Completion Message
Event Messages
7.2.10 - CashDispenser.Count
This command empties the specified storage unit(s). All items dispensed from the unit are counted and moved to the specified output location.
The number of items counted can be different from the number of items dispensed in cases where the Dispenser can detect this information. If the Dispenser cannot differentiate between what is dispensed and what is counted, then dispensed will be the same as counted.
Upon successful command execution the storage unit(s) counts are reset.
When end-to-end (E2E) security is being enforced by a device this command will be blocked from executing. Any attempt to execute the command will complete with the completion code unsupportedData. This is required because there is currently no E2E security defined for this command, and if the command were permitted it would be possible to extract cash and bypass E2E security.
Command Message
Completion Message
Event Messages
7.2.11 - CashDispenser.PrepareDispense
On some hardware it can take a significant amount of time for the Cash Dispenser to get ready to dispense media. On this type of hardware this command can be used to improve transaction performance.
If this command is supported, then applications can help to improve the time taken to dispense media by issuing this command as soon as the application knows that a dispense is likely to happen. This command either prepares the device for the next dispense operation or terminates the dispense preparation if the subsequent dispense operation is no longer required.
With the exception of the CashDispenser.Denominate and CashDispenser.Dispense commands, which will not stop the dispense preparation, any mechanical command on CashDispenser or CashAcceptor will automatically stop the dispense preparation.
If this command is executed and the device is already in the specified action state, then this execution will have no effect and will complete with a successful completion message.
Command Message
Completion Message
Event Messages
None7.3 - Event Messages
7.3.1 - CashDispenser.DelayedDispenseEvent
This event is generated if the start of a dispense operation has been delayed.
Event Message
7.3.2 - CashDispenser.StartDispenseEvent
This event is generated when a delayed dispense operation begins.
Event Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
7.3.3 - CashDispenser.IncompleteDispenseEvent
This event is generated during CashDispenser.Dispense when it has not been possible to dispense the entire denomination, but part of the requested denomination is on the intermediate stacker or in customer access. Note that in this case the values in this payload report the amount and number of each denomination that are in customer access or on the intermediate stacker. CashDispenser.GetPresentStatus can be used to determine whether the items are in customer access.
Event Message
8 - Cash Acceptor Interface
This chapter defines the Cash Acceptor interface functionality and messages.
This specification describes the functionality of an XFS4IoT compliant Cash Acceptor interface. It defines the interface-specific commands that can be issued to the service using the WebSocket endpoint.
Persistent values are maintained through power failures, open sessions, close sessions and system resets.
This specification covers the acceptance of items. An "item" is defined as any media that can be accepted and includes coupons, documents, bills and coins.
8.1 - Command Messages
8.1.1 - CashAcceptor.GetCashInStatus
This command is used to get information about the status of the currently active cash-in transaction, or in the case where no cash-in transaction is active the status of the most recently ended cash-in transaction. This value is persistent and is valid until the next CashAcceptor.CashInStart command and is not deleted by a dispense or check-in transaction.
If end-to-end security is supported by the hardware, the cash-in status will be protected by a security token. If end-to-end security is not supported then it's not possible to guarantee that the cash-in status hasn't been altered, possibly by an attacker. To avoid this risk the client must always call this command and validate the security token.
If end-to-end security is being used the caller must pass in a nonce value. This value will be included in the security token that is returned. The caller must check that the original nonce value matches the token - if they do not match then the token is invalid.
If end-to-end security is being used the caller must also call Common.StartSecureOperation with a unique ID before starting any cash in commands. This unique ID will be included in the token and is used so that a single token can protect multiple transactions. Note that the cash values in the token include all values since Common.StartSecureOperation was called. This means that, if there have been multiple cash in transactions, the token values will not match the other values in the result of this command. The token values will be the sum of all previous transactions since Common.StartSecureOperation was called.
Command Message
Completion Message
Event Messages
None8.1.2 - CashAcceptor.GetReplenishTarget
This command is used to determine which storage units can be specified as targets for a given source storage unit with the CashAcceptor.Replenish command. For example, it can be used to determine which targets can be used for replenishment from a replenishment container or from a recycle unit.
Command Message
Completion Message
Event Messages
None8.1.3 - CashAcceptor.GetDeviceLockStatus
This command is used to retrieve the lock/unlock statuses of the CashAcceptor device and each of its storage units. This is only supported if the physical locking and unlocking of the device or the storage units is supported.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None8.1.4 - CashAcceptor.GetDepleteSource
This command is used to determine which storage units can be specified as source storage units for a given target storage unit with the CashAcceptor.Deplete command. For example, it can be used to determine which sources can be used for depletion to a replenishment container or to a cash-in storage unit.
Command Message
Completion Message
Event Messages
None8.1.5 - CashAcceptor.GetPresentStatus
This command is used to obtain the status of the most recent attempt to present or return items to the customer. This information includes the number of items previously moved to the output position and the number of items which have yet to be returned as a result of the following commands: CashAcceptor.CashIn, CashAcceptor.CashInRollback, CashAcceptor.PreparePresent, CashAcceptor.PresentMedia, CashManagement.OpenShutter (in the case of returning multiple bunches).
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None8.1.6 - CashAcceptor.CashInStart
Before initiating a cash-in operation, an application must issue this command to begin a cash-in transaction. During a cash-in transaction any number of CashAcceptor.CashIn commands may be issued. The transaction is ended when either a CashAcceptor.CashInRollback, CashAcceptor.CashInEnd, CashManagement.Retract or CashManagement.Reset command is sent. Where shutterControl is false this command precedes any explicit operation of the shutters.
If an application wishes to determine where the notes went during a transaction it can execute a Storage.GetStorage before and after the transaction and then derive the difference.
A hardware failure during the cash-in transaction does not reset the note number list information; instead, the note number list information will include items that could be accepted and identified up to the point of the hardware failure.
If supported by cashInLimit, an individual cash-in transaction can be limited to a maximum number of items (totalItemsLimit) or a maximum amount (amountLimit). If not supported or specified, the number of items accepted in the transaction is limited by the capacity of the intermediateStacker. Any limitations specified by these parameters only apply to the individual cash-in transaction; subsequent transactions are not affected. The following table shows some examples of how the transaction can be limited.
| Transaction limits | totalItemsLimit | amountLimit |
|---|---|---|
| EUR 100 or GBP 200 or USD 500 Maximum number of items allowed limited by physical capability. |
0 | EUR 100 GBP 200 USD 500 |
| EUR 100 or GBP 200, USD refused Maximum 50 items allowed. |
50 | EUR 100 GBP 200 |
| USD 500, no limit on GBP, other currencies refused Maximum number of items allowed limited by physical capability. |
0 | GBP 0 USD 500 |
| EUR limited by physical capability of the device. Other currencies refused. | 0 | EUR 0 |
| EUR limited by physical capability of the device. GBP 100, USD refused. | 0 | EUR 0 GBP 100 |
Command Message
Completion Message
Event Messages
None8.1.7 - CashAcceptor.CashIn
This command moves items into the cash device from an input position.
On devices with implicit shutter control, the CashAcceptor.InsertItemsEvent will be generated when the device is ready to start accepting media.
The items may pass through the banknote reader for identification. Failure to identify items does not mean that the command has failed - even if some or all of the items are rejected by the banknote reader the command may return success. In this case one or more CashAcceptor.InputRefuseEvent events will be sent to report the rejection. See also the paragraph below about returning refused items.
If the device does not have a banknote reader, then the completion message will be empty.
If the device has a cash-in stacker then this command will cause inserted genuine items (see Note Classification) to be moved there after validation. Counterfeit, suspect or inked items may also be moved to the cash-in stacker, but some devices may immediately move them to a designated storage unit. Items on the stacker will remain there until the current cash-in transaction is either cancelled by the CashAcceptor.CashInRollback command or confirmed by the CashAcceptor.CashInEnd command. These commands will cause any non-genuine items on the cash-in stacker to be moved to the appropriate storage unit. If there is no cash-in stacker then this command will move items directly to the storage units and the CashAcceptor.CashInRollback command will not be supported. Storage unit information will be updated accordingly whenever notes are moved to a storage unit during this command.
Note that the acceptor status property may change value during a cash-in transaction. If media has been retained to storage units during a cash-in transaction, it may mean that acceptor is set to stop, which means subsequent cash-in operations may not be possible. In this case, the subsequent command fails with errorCode cashUnitError.
The shutterControl property will determine whether the shutter is controlled implicitly by this command or whether the application must explicitly open and close the shutter using the CashManagement.OpenShutter, CashManagement.CloseShutter or CashAcceptor.PresentMedia commands. If shutterControl is false then this command does not operate the shutter in any way, the application is responsible for all shutter control. If shutterControl is true, this command opens the shutter at the start of the command and closes it once bills are inserted.
The presentControl property will determine whether it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is true, then all items are moved immediately to the correct output position for removal (a CashManagement.OpenShutter command will be needed in the case of explicit shutter control). If presentControl is false, then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
It is possible that a device may divide bill or coin accepting into a series of sub-operations under hardware control. In this case a CashAcceptor.SubCashInEvent may be sent after each sub-operation, if the hardware capabilities allow it.
Returning items (single bunch):
If shutterControl is true, and a single bunch of items is returned then this command will complete once the notes have been returned. A CashManagement.ItemsPresentedEvent will be generated.
If shutterControl is false, and a single bunch of items is returned then this command will complete without generating a CashManagement.ItemsPresentedEvent, instead the event will be generated by the subsequent CashManagement.OpenShutter or CashAcceptor.PresentMedia command.
Returning items (multiple bunches):
It is possible that a device will in certain situations return refused items in multiple bunches. In this case, this command will not complete until the final bunch has been presented and after the last CashManagement.ItemsPresentedEvent has been generated. For these devices shutterControl and presentControl fields of the positionCapabilities structure returned from the Common.Capabilities / CashAcceptor.PositionCapabilities query must both be true otherwise it will not be possible to return multiple bunches. Additionally it may be possible to request the completion of this command with a Common.Cancel before the final bunch is presented so that after the completion of this command the CashManagement.Retract or CashManagement.Reset command can be used to move the remaining bunches, although the ability to do this will be hardware dependent.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
8.1.8 - CashAcceptor.CashInEnd
This command ends a cash-in transaction. If cash items are on the stacker as a result of a CashAcceptor.CashIn command these items are moved to the appropriate storage units.
The cash-in transaction is ended even if this command does not complete successfully.
In the special case where all the items inserted by the customer are classified as counterfeit and/or suspect items and the service is configured to automatically retain these item types then the command will complete with success even if the hardware may have already moved the counterfeit and/or suspect items to their respective storage units on the CashAcceptor.CashIn command and there are no items on the stacker at the start of the command. This allows the location of the notes retained to be reported in the completion payload. If no items are available for cash-in for any other reason, the noItems error code is returned.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
8.1.9 - CashAcceptor.CashInRollback
This command is used to roll back a cash-in transaction. It causes all the cash items cashed in since the last CashAcceptor.CashInStart command to be returned to the customer.
This command ends the current cash-in transaction. The cash-in transaction is ended even if this command does not complete successfully.
The shutterControl property will determine whether the shutter is controlled implicitly by this command or whether the application must explicitly open and close the shutter using the CashManagement.OpenShutter, CashManagement.CloseShutter or CashAcceptor.PresentMedia commands. If shutterControl is false then this command does not operate the shutter in any way, the application is responsible for all shutter control. If shutterControl is true, then this command opens the shutter and it is closed when all items are removed.
The presentControl property will determine whether it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is true then all items are moved immediately to the correct output position for removal (a CashManagement.OpenShutter command will be needed in the case of explicit shutter control). If presentControl is false, then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
Items are returned in a single bunch or multiple bunches in the same way as described for the CashAcceptor.CashIn command.
In the special case where all the items inserted by the customer are classified as counterfeit and/or suspect, and the service is configured to automatically retain these item types, then the command will complete with success even though no items are returned to the customer. This allows the location of the notes retained to be reported in the completion payload. The application can tell if items have been returned or not via the CashManagement.ItemsPresentedEvent. This event will be generated before the command completes when items are returned. This event will not be generated if no items are returned. If no items are available to rollback for any other reason, the noItems error code is returned.
If during command execution the counts of one or more storage units have changed, a Storage.CountsChangedEvent will be sent.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
8.1.10 - CashAcceptor.ConfigureNoteTypes
This command is used to change the note types the banknote reader should accept during cash-in. Only note types which are to be changed need to be specified in the command payload. If an unknown note type is given the completion code unsupportedData will be returned.
The values set by this command are persistent.
Command Message
Completion Message
Event Messages
None8.1.11 - CashAcceptor.CreateSignature
This command is used to create a reference signature which can be compared with the available signatures of the cash-in transactions to track back the customer.
When this command is executed, the device waits for a note to be inserted at the input position, transports the note to the recognition module, creates the signature and then returns the note to the output position.
The shutterControl property will determine whether the shutter is controlled implicitly by this command or whether the application must explicitly open and close the shutter using the CashManagement.OpenShutter, CashManagement.CloseShutter or CashAcceptor.PresentMedia commands. If shutterControl is false, then this command does not operate the shutter in any way, and the application is responsible for all shutter control. If shutterControl is true, then this command opens and closes the shutter at various times during the command execution and the shutter is finally closed when all items are removed.
The presentControl property will determine whether it is necessary to call the CashAcceptor.PresentMedia command in order to move items to the output position. If presentControl is true, then all items are moved immediately to the correct output position for removal (a CashManagement.OpenShutter command will be needed in the case of explicit shutter control). If presentControl is false, then items are not returned immediately and must be presented to the correct output position for removal using the CashAcceptor.PresentMedia command.
On devices with implicit shutter control, the CashAcceptor.InsertItemsEvent will be generated when the device is ready to start accepting media.
The application may have to execute this command repeatedly to make sure that all possible signatures are captured.
If a single note is entered and returned to the customer but cannot be processed fully (e.g. no recognition software in the recognition module, the note is not recognized, etc.) then a CashAcceptor.InputRefuseEvent will be sent and the command will complete. In this case, no note specific output properties will be returned.
Command Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
8.1.12 - CashAcceptor.ConfigureNoteReader
This command is used to configure the currency description configuration data into the banknote reader module. The format and location of the configuration data is vendor and/or hardware dependent.
Command Message
Completion Message
Event Messages
None8.1.13 - CashAcceptor.CompareSignature
This command is used to compare the signatures of a reference item with the available signatures of the cash-in transactions.
The reference signatures are created by the CashAcceptor.CreateSignature command.
The transaction signatures are obtained through the CashManagement.GetItemInfo command.
The signatures (1 to 4) of the reference banknote are typically the signatures of the four orientations of the banknote.
The CashAcceptor.CompareSignature command may return a single indication or a list of indications to the matching signatures, each one associated to a confidence level factor. If the service does not support the confidence level factor, it returns a single indication to the best matching signature with the confidence level factor set to 0.
If the comparison completed with no matching signatures found, then the command returns with completionCode set to null and signaturesIndex empty.
This command must be used outside of cash-in transactions and outside of the exchange state.
Due to the potential for signatures to be large, as well as the possibility that it may be necessary to compare the reference signature with a large number of signatures, applications should be aware of the amount of data passed as input to this command. In some cases, it may be necessary to execute this command more than once, with subsets of the total signatures, and then afterward compare the results from each execution.
Command Message
Completion Message
Event Messages
None8.1.14 - CashAcceptor.Replenish
This command replenishes items from a single storage unit to multiple storage units. Applications can use this command to ensure that there is the optimum number of items in the cassettes by moving items from a source storage unit to a target storage unit. This is especially applicable if a replenishment storage unit is used for the replenishment and can help to minimize manual replenishment operations.
The CashAcceptor.GetReplenishTarget command can be used to determine what storage units can be specified as target storage units for a given source storage unit. Any items which are removed from the source cash unit that are not of the correct currency and value for the target storage unit during execution of this command will be returned to the source storage unit.
The counts returned with the Storage.GetStorage command will be updated as part of the execution of this command.
If the command fails after some items have been moved, the command will complete with an appropriate error code, and a CashAcceptor.IncompleteReplenishEvent will be sent.
Command Message
Completion Message
Event Messages
8.1.15 - CashAcceptor.CashUnitCount
This command counts the items in the storage unit(s). If it is necessary to move items internally to count them, the items should be returned to the unit from which they originated before completion of the command. If items could not be moved back to the storage unit they originated from and did not get rejected, the command will complete with an appropriate error.
During the execution of this command one Storage.StorageChangedEvent will be generated for each storage unit that has been counted successfully, or if the counts have changed, even if the overall command fails.
If an application wishes to determine where the notes went during the command it can execute a Storage.GetStorage before and after the transaction and then derive the difference.
This command is designed to be used on devices where the counts cannot be guaranteed to be accurate and therefore may need to be automatically counted periodically. Upon successful completion, for those storage units that have been counted, the counts are accurately reported with the Storage.GetStorage command.
Command Message
Completion Message
Event Messages
8.1.16 - CashAcceptor.DeviceLockControl
This command can be used to lock or unlock a CashAcceptor device or one or more storage units. CashAcceptor.GetDeviceLockStatus can be used to obtain the current lock state of any items which support locking.
During normal device operation the device and storage units will be locked, and removal will not be possible. If supported, the device or storage units can be unlocked, ready for removal. In this situation the device will remain online and cash-in or dispense operations will be possible, as long as the device or storage units are not physically removed from their normal operating position.
If the lock action is specified and the device or storage units are already locked, or if the unlock action is specified and the device or storage units are already unlocked then the action will complete successfully.
Once a storage unit has been removed and reinserted it may then have a manipulated status. This status can only be cleared by issuing a Storage.StartExchange / Storage.EndExchange command sequence.
The device and all storage units will also be locked implicitly as part of the execution of the Storage.EndExchange or the CashManagement.Reset command.
The normal command sequence is as follows:
-
CashAcceptor.DeviceLockControl command is executed to unlock the device and some or all the storage units.
-
Optionally a cash-in transaction or a dispense transaction on a cash recycler device may be performed.
-
The operator was not required to remove any of the storage units, all storage units are still in their original position.
-
CashAcceptor.DeviceLockControl command is executed to lock the device and the storage units.
The relation of lock/unlock control with the Storage.StartExchange and the Storage.EndExchange commands is as follows:
-
CashAcceptor.DeviceLockControl command is executed to unlock the device and some or all the storage units.
-
Optionally a CashAcceptor.CashInStart / CashAcceptor.CashIn / CashAcceptor.CashInEnd cash-in transaction or a CashDispenser.Dispense / CashDispenser.Present transaction on a cash recycler device may be performed.
-
The operator removes and reinserts one or more of the previously unlocked storage units. The associated Storage.StorageChangedEvent will be posted and after the reinsertion the storage unit will show the status manualInsertion.
-
Storage.StartExchange command is executed.
-
Storage.EndExchange command is executed. During this command execution the service implicitly locks the device and all previously unlocked storage units. The status of the previously removed unit will be reset.
Command Message
Completion Message
Event Messages
8.1.17 - CashAcceptor.PresentMedia
This command opens the shutter and presents items to be taken by the customer. The shutter is automatically closed after the media is taken. The command can be called after a CashAcceptor.CashIn, CashAcceptor.CashInRollback, CashManagement.Reset or CashAcceptor.CreateSignature command and can be used with explicit and implicit shutter control. The command is only valid on positions where usage is rollback or refuse and where presentControl is false.
This command cannot be used to present items stacked through the CashDispenser interface. Where this is attempted the command fails with errorCode sequenceError.
Command Message
Completion Message
Event Messages
None8.1.18 - CashAcceptor.Deplete
This command moves items from multiple storage units to a single storage unit. Applications can use this command to ensure that there are the optimum number of items in the cassettes by moving items from source storage units to a target storage unit. This is especially applicable if surplus items are removed from multiple recycle storage units to a replenishment storage unit and can help to minimize manual replenishment operations.
The CashAcceptor.GetDepleteSource command can be used to determine what storage units can be specified as source storage units for a given target storage unit.
The counts returned by the Storage.GetStorage command will be updated as part of the execution of this command.
If the command fails after some items have been moved, the command will complete with an appropriate error code, and a CashAcceptor.IncompleteDepleteEvent will be sent.
Command Message
Completion Message
Event Messages
8.1.19 - CashAcceptor.PreparePresent
In cases where multiple bunches are to be returned under explicit shutter control, this command is used for the purpose of moving a remaining bunch to the output position explicitly before using the following commands:
The application can tell whether the additional items were left by using the CashAcceptor.GetPresentStatus command. This command does not affect the status of the current cash-in transaction.
Command Message
Completion Message
Event Messages
8.2 - Event Messages
8.2.1 - CashAcceptor.InputRefuseEvent
This event specifies that the device has refused either a portion or all the items.
Event Message
8.2.2 - CashAcceptor.SubCashInEvent
This event is generated when one of the sub cash-in operations into which the cash-in operation was divided has finished successfully.
Event Message
8.2.3 - CashAcceptor.InsertItemsEvent
This event notifies the application when the device is ready for the user to insert items.
Event Message
| Payload, Version 2.0 |
|---|
| This message does not define any properties. |
8.2.4 - CashAcceptor.IncompleteReplenishEvent
This event is generated when some items had been moved before the CashAcceptor.Replenish command failed with an error code (not "success"), but some items were moved then the details will be reported with this event. This event can only occur once per command.
Event Message
8.2.5 - CashAcceptor.IncompleteDepleteEvent
This event is generated when the CashAcceptor.Deplete command failed with an error code (not "success"), but some items were moved. In this case the details will be reported with this event. This event can only occur once per command.
Event Message
9 - Check Interface
Check Processing Modules accept one or more media items (Checks, Giros, etc) and process these items according to application requirements. The Check Interface supports devices that can handle a single item as well as those devices that can handle bunches of items. The following are the three main device types:
- Single Item: can accept and process a single item at a time.
- Multi-Item Feed with no stacker (known as an escrow in some environments): can accept a bunch of media from the customer but each item has to be processed fully (i.e. deposited in a storage unit or returned) before the next item can be processed.
- Multi-Item Feed with a stacker: can accept a bunch of media from the customer and all items can be processed together.
In the U.S., checks are always encoded in magnetic ink for reading by Magnetic Ink Character Recognition (MICR), and a single font is always used. In Europe some countries use MICR and some use Optical Character Recognition (OCR) character sets, with different fonts, for their checks.
The Check specification provides applications with an interface to control the following functions (depending on the capabilities of the specific underlying device):
- Capture an image of the front of an item in multiple formats and bit depths.
- Capture an image of the back of an item in multiple formats and bit depths.
- Read the code line of an item using a MICR reader.
- Read the code line of an item using OCR.
- Endorse (print text) on an item.
- Stamp an item.
- Return an item to the customer.
- Deposit an item in a storage unit.
- Retract items left by the customer.
The Check specification uses the concept of a Media-In transaction to track and control a customer's interaction with the device. A Media-In transaction consists of one or more Check.MediaIn commands. The transaction is initiated by the first Check.MediaIn command and remains active until the transaction is either confirmed through Check.MediaInEnd, or terminated by Check.MediaInRollback, Check.RetractMedia or Check.Reset. While a transaction is active the Check.GetTransactionStatus command reports the status of the current transaction. When a transaction is not active the Check.GetTransactionStatus command reports the status of the last transaction as well as some current status values.
In this the specification the terms "long edge" and "short edge" are used to describe the orientation of a check and length of its edges.
This interface is to be used together with the Storage interface to handle management of storage units.
9.1 - General Information
9.1.1 - References
| ID | Description |
|---|---|
| check-1 | OCR-A font - ANSI X3.17-1981 figure E1 |
| check-2 | OCR-B font - ANSI X3.49-1975 figure C2 |
| check-3 | E-13B MICR font - ISO 1004-1:2013 |
| check-4 | CMC7 MICR font - ISO 1004-2:2013 |
| check-5 | https://www.unicode.org/charts/PDF/U2440.pdf |
9.1.2 - Code Line Characters
This section describes how code line data is returned in the Check specification depending on how the code line was read:
- OCR-A font will conform to [Ref. check-1].
- OCR-B font will conform to [Ref. check-2].
- E-13B MICR font will conform to [Ref. check-3]. Note that the special E-13B banking symbols are defined by Unicode (see [Ref. check-5]), therefore E-13B code lines are provided without mapping - see Table 1 below for more details.
- CMC7 MICR font will conform to [Ref. check-4]. The special banking symbols in this font are not defined in Unicode, therefore they are mapped to standard characters as shown in Table 2 below.
In all cases unrecognized characters are reported as the REJECT/SUB character, 0x1A.
Table 1 - E-13B Special Banking Symbols
| Symbol | MICR Definition | Unicode | Unicode Definition |
|---|---|---|---|
| ⑆ | Transit | U+2446 | OCR Bank Branch Identification |
| ⑇ | Amount | U+2447 | OCR Amount of Check |
| ⑈ | On Us | U+2448 | OCR Dash |
| ⑉ | Dash | U+2449 | OCR Customer Account Number |
Table 2 - CMC7 Special Banking Symbols
| Symbol | Meaning | Mapping |
|---|---|---|
 |
S1 - Start of Bank Account | a |
 |
S2 - Start of the Amount field | b |
 |
S3 - Terminate Routing | c |
 |
S4 - Unused | d |
 |
S5 - Transit / Routing | e |
Example
| Check code line | code line reported in XFS4IoT |
|---|---|
| ABCD1234 |
aABCDb1234c |
9.1.3 - Example Transaction flows
This section describes example check only flows.
9.1.3.1 - Devices with stacker
This section describes flows for modules with stacker.
9.1.3.1.1 - Successful Check Bunch Processing
This flow describes a successful Check processing flow using Check commands.
9.1.3.1.2 - Partial Return Processing
This flow describes a Check processing flow using Check commands where some items are returned.
9.1.3.1.3 - Processing with errors
This flow describes a Check processing flow with some errors items using Check commands.
9.1.3.1.4 - Processing with rollback
This flow describes a Check processing flow with rollback using Check commands. This flow is identical to Successful Check Bunch Processing up to Check.SetMediaParameters completion message.
9.1.3.1.5 - Processing with retract
This flow describes a Check processing flow with retract using Check commands. This flow is identical to Successful Check Bunch Processing up to Check.SetMediaParameters completion message.
9.1.3.1.6 - Processing with application refuse
This flow describes a Check processing flow using Check commands where the application can refuse items. Only applicable if applicationRefuse is true.
9.1.3.1.7 - Processing with application refuse and items refused
This flow describes a Check processing flow using Check commands where the application refuses some items. Only applicable if applicationRefuse is true.
9.1.3.2 - Devices without stacker
This section describes flows for modules without stacker. In the following flows, single and bunch check devices follow the same flow, except that only one item is inserted for single devices and the Check.GetNextItem command always return reporting that there are no more items to process.
9.1.3.2.1 - Successful Check Bunch Processing - No Stacker
This flow describes a successful Check processing flow using Check commands on a module without stacker.
9.1.3.2.2 - Check Bunch Processing with some items returned - No Stacker
This flow describes a Check processing flow using Check commands on a module without stacker where some items are returned.
9.1.3.2.3 - Check Bunch Processing with errors - No Stacker
This flow describes a Check processing flow using Check commands on a module without stacker where the next item's code line can't be read.