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.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 headers contains properties common to all messages as well as properties specific to a message type.
Additional properties are not allowed.
| Property | Property Type | Required |
|---|---|---|
| type | string | ✓ |
| name | string | ✓ |
| version | string | ✓ |
| requestId | integer | |
| timeout | integer | |
| status | string, null | |
| completionCode | string, null | |
| errorDescription | string, null |
The following example illustrates the header for a Common.Status command message.
{
"header": {
"type": "command",
"name": "Common.Status",
"version": "1.0",
"requestId": 12345,
"timeout": 1000
}
}
2.3.2.4 - requestId Property
Unique request identifier supplied by the client used to correlate the command message with acknowledge, event and completion messages. The client will supply values that are positive, incremental and greater than or equal to 0. The service will check that the requestId does not conflict with a currently executing or queued command request from the same client and return status invalidRequestID if it does.
Unsolicited messages do not have a requestId.
2.3.2.5 - timeout Property
This property is only applicable to command messages.
Timeout in milliseconds for the command to complete. If set to 0, the command will not timeout but can be canceled.
Default: 0
2.3.2.6 - status Property
This property is only applicable to acknowledge messages.
If null the command has been accepted for execution and will complete with a completion message. Otherwise this property can be one of the following values:
invalidMessage- The JSON in the message is invalid and can't be parsed.invalidRequestID- The request ID on the command is invalid. This could be because the value is not an integer, has a zero value, or because a command with the same request ID from the same client is already queued or is executing.tooManyRequests- The service has currently received and queued more requests than it can process.
Default: null
2.3.2.7 - completionCode Property
This property is only applicable to completion messages.
If null the command completed successfully. Otherwise, the property will contain one of the following values:
commandErrorCode- Check the errorCode property for the command specific error code.canceled- Canceled using the Common.Cancel command.timeOut- Timed out after the client specified timeout.deviceNotReady- The device is not ready or timed out.hardwareError- An error occurred on the device.internalError- An internal inconsistency or other unexpected error occurred.invalidCommand- The command is not supported by the service.invalidRequestID- The requestId is invalid.unsupportedCommand- The command is valid for the interface, but is not supported by the service or device.invalidData- The command message contains invalid data.userError- The user is preventing proper operation of the device.unsupportedData- The command message contains data that is valid for the interface command, but is not supported by the service or device.fraudAttempt- The user is attempting a fraudulent act on the device.sequenceError- The command request is not valid at this time or in the device's current state.authorizationRequired- The command request cannot be performed because it requires authorization.noCommandNonce- The value of the nonce stored in the hardware was cleared, for example by a power failure.invalidToken- The security token is invalid.invalidTokenNonce- The value of the nonce in the security token does not match the stored value.invalidTokenHMAC- The value of the HMAC in the security token is incorrect.invalidTokenFormat- The token format version value is not recognized, or the token format is somehow invalid.invalidTokenKeyNoValue- The key used for the HMAC for a token has not been loaded and the token cannot be validated.notEnoughSpace- There is not enough space on the storage.
If the value is commandErrorCode, the payload errorCode property contains the command specific completion error code.
Default: null
2.3.2.8 - errorDescription Property
This property is only applicable to completion messages for which the completionCode value is neither canceled or timeOut.
If not null, this contains additional vendor dependent information to assist with problem resolution. The format of this string should not be relied on.
Default: null
2.3.3 - Payload Definition
The XFS4IoT interface specifications detail the payload content for the command, event, completion and unsolicited messages.
If not null, the payload cannot be empty. It must contain at least one property.
2.3.3.1 - Additional Properties
It is possible to include additional properties not defined by the specification. This can be useful in some cases and is allowed as long as those additional properties do not impact the proper functioning of the service or client.
For example, it may be useful to include properties with extra debugging information such as human readable error messages or hardware specific error codes.
Any additional property not defined by this specification and not recognized by the Service or the Client will be ignored.
Ignoring an unknown property will have no effect on the standard behavior of the service or client. There will be no requirement to use undefined additional properties.
The service or client may use undefined additional properties for whatever purpose they require. Dependance on undefined additional properties will mean the client or service is non-standard and may impact interoperability.
When non-standard properties are used there is a risk that the same name could be used by different implementations, causing unexpected behaviors. Implementors should reduce the risk of this name clash by using a company name or code as a prefix for the property name. For example, a company called "Acme" might add the "acmeHardwareError" and "acmeLogMessage" properties.
2.4 - Message Types
XFS4IoT supports the following message types.
| type | Direction | Description |
|---|---|---|
| command | client to Service | Message sent to the Service to perform a command. |
| acknowledge | Service to client | Message from the Service indicating if the command is valid and queued. |
| event | Service to client | Intermediate message from the Service indicating progress of the command. |
| completion | Service to client | Message from the Service indicating the command is complete. |
| unsolicited | Service to client | Message from the Service unrelated to a command. |
2.4.1 - Command Messages
The start of a command will be initiated by the client with a command message, requesting the service performs the specified action. The message uses the standard header properties with type set to command.
The requestId is given by the client and allows the client to link messages sent in response to the command back to the original command. For example, the completion message for this command will contain the same requestId.
The requestId must be greater than or equal to 1 and incremented between each command, 0 is reserved for unsolicited events. The client is responsible for ensuring that each requestId is unique for a single connection. They do not have to be unique across connections. The request is identified by a combination of the requestId and the connection.
The Service will remember the last requestId and reject any requestId for a new command which is lower or equal to the previous requestId. Other than that the service will not track the requestId.
Examples of commands with payloads are shown in the example sequence.
2.4.2 - Acknowledge Messages
As soon as the service has received and parsed the command message it will send an acknowledge message to indicate that the command message has been received and queued. This will normally include the requestId so that the client can identify which command it relates to (unless an error occurs which prevents the requestId being included). The message uses the standard header properties with type set to acknowledge.
Sending the acknowledge message immediately allows the client to handle network errors and lost messages more quickly. It can set a short timeout and expect to receive the acknowledge within that timeout, and continue with error handling if it does not.
Receiving the acknowledge message does not give any guarantees about what the service will do with the command, or even that it can be executed. Any errors will be reported in the completion message for the command, not in the acknowledge.
If for any reason the service does not accept and queue the command request, the acknowledge message header status property will indicate the reason. When this occurs, the acknowledge message is the final message related to the command request.
Examples of acknowledge messages are shown in the example sequence.
2.4.3 - Event Messages
During the processing of the command the service can send multiple solicited events, as defined in the interface chapters. This is used to inform the client when something significant happens that it may need to react to, like a card being inserted or a key being pressed.
Each solicited event will contain the original requestId in the header, and will only be sent on the connection that the original command was received on, so that individual solicited events can be linked to the original command by the client.
For compatibility with future specification changes, and to permit custom extensions by service implementors, the client should ignore any events that it does not recognize.
Examples of event messages are shown in the example sequence.
2.4.4 - Completion Messages
If a command is accepted, there will be one completion message. If an acknowledge message with an error code is returned to the command message then the command will not be executed, and no completion message will be sent.
The message uses the standard header properties with type set to completion. The completion message will contain the requestId from the original command message, so that the client can link the message back to the command. After the completion message for a command has been sent with a particular requestId, no more messages will be sent with that requestId.
Each completion message will contain as much information as possible to avoid requiring extra events. For example, when a command is used to fetch information from the Service then the information will be included in the completion message. When a command results in particular information, like reading a card, then that information is included in the completion message. The exact information included in each completion message is defined in the interface document that defines that completion message.
Examples of completion messages are shown in the example sequence.
After a command message has been received and associated acknowledge sent, the completion code, either success or an error code, will be included in the completion message for that command. The interface chapter may define command specific error codes that are valid for each completion message. No other error codes will be returned by the service for the completion message.
The completion message payload completionCode property contains one of the values defined in Completion Codes.
When an error occurs, optional vendor specific information may be included in the errorDescription property.
2.4.5 - Unsolicited Event Messages
The Service will also send unsolicited events to the client to signal events that can happen at any time, independent of command handling. These can happen before, during, or after any command handling. The message uses the standard header properties with type set to unsolicited.
To allow clients to react to events quickly, unsolicited messages should be sent as soon as possible. For example, it should avoid queuing events until after the current command has been processed if it does not have to.
Since unsolicited events are not linked to command handling, they do not have a matching requestId. The event header will contain a requestId of 0. Unsolicited events are also broadcast to all clients, on all open connections.
Each interface chapter defines the unsolicited events relevant to the interface.
For compatibility with future specification changes, and to permit custom extensions by service implementors, the client should ignore any events that it does not recognize.
Examples of unsolicited messages are shown in the example sequence.
2.5 - Command Processing
Once a service has been discovered (see Service Endpoint Discovery) and a connection created the client can send command messages to the service. Commands may cause the service to perform actions that are entirely software based, such as returning the current status, or they may cause actions to be performed by hardware, such as opening a shutter.
The sequence of messages passed between the service and the client is the same for all commands, independent of the command or interface being used.
Services may also send unsolicited events directly to the client. This can happen at any time that the service connection is open. This could be during the processing of a command, or between commands.
The following sections provide information on various topics related to command processing:
- Standard command processing flow
- Command queuing
- Commands cancellation
- Example flow
2.5.1 - Standard Sequence
The normal command message sequence will be as follows, note this example has multiple solicited and unsolicited events:
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 a new version of a command message has a property which has an associated capability property, the service must implement, at a minimum, the version of the Common.Capabilities command that includes the associated capability property. This will allow the client to decide whether to use the command message property and the value it should be set to.
Each release of the specification defines the message version numbers of the command, acknowledge, event, completion and unsolicited messages included in that release of the specification. The specification number is different from the message version numbers. If a message definition does not change from one release of the specification to the next, the message version number will remain the same.
2.6.1 - Version Numbers
Message version numbers have the form X.Y where X and Y are non-negative integers, and do not contain leading zeroes. X is the major version and Y is the minor version. The major and minor version numbers are incremented according to the scope of change described in the following sections.
The major version must be greater than 0. If a minor change is made, the minor version is incremented and the major version remains the same. If a major change is made, the major version is incremented and the minor version is reset to 0. For example, 1.1 -> 1.2 -> ... -> 1.10 -> 2.0.
2.6.1.1 - Major Version Numbers
Major version X (X.y) numbers will be incremented in the specification if any backwards incompatible changes are introduced to the command, event, unsolicited or completion messages. It may also include minor level changes.
Major version increments represent a new command, event or unsolicited message. While there will likely be similarities with the previous major version, this is not guaranteed. It is anticipated that given the flexibility of JSON, major version increments will rarely be required.
Major version increments allow:
- Removal of command message properties.
- Change of definition of command message properties.
- Change of definition of completion message properties.
- Change of definition of event message properties.
- New event messages which cannot be ignored by the client.
2.6.1.2 - Minor Version Numbers
Minor version Y (x.Y) numbers will be incremented in the specification if new, backwards compatible functionality is introduced to the command, event, completion or unsolicited message. It will also be incremented if any message property is marked as deprecated. It may be incremented if substantial new functionality or improvements are introduced where backwards compatibility is maintained.
Minor version increments allow:
- Additional command message properties.
- Additional completion, event and unsolicited message properties.
- New event messages which can be ignored by the client.
Additional command message properties must be optional. If omitted, the command behavior must be as defined in minor version 0 of the major version of the command message. If included, additional properties may change the behavior of the command. Clients that included additional command message properties that change behavior should therefore handle these behavioral changes.
For additional completion, event and unsolicited message properties, clients should expect that new properties may be added and if not required, ignored. That is, clients should not break because they do not recognize additional properties.
2.6.2 - Version Number Selection
Version number selection occurs after a client connection has been established with the service. By default, the service will for each client connection, use the lowest available major version of each message it supports.
The client is responsible for determining version compatibility. If compatible, the client must inform the service of its version requirements. If incompatible, the client must handle the incompatibilities, possibly by not using incompatible commands. If the client cannot handle the incompatibilities then it should close the connection and not use the service.
The following sequence demonstrates use of the Common.Capabilities command to identify the command and event (both event and unsolicited) versions supported by the service, and the client use of the Common.SetVersions command to inform the service of the versions that should be used for the connection on which the command is sent.
2.6.3 - Version Evolution Example
The following table depicts an example evolution of a command, an event and an unsolicited event.
| Evolution | command | event | completion | unsolicited |
|---|---|---|---|---|
| Initial | 1.0 propA |
1.0 propA |
1.0 propA |
1.0 propA |
| Minor update - command property added - completion unchanged |
1.1 propA propB |
1.0 propA |
1.0 propA |
1.0 propA |
| Minor update - event property added |
1.1 propA propB |
1.1 propA propB |
1.0 propA |
1.0 propA |
| Major update - completion property removed - command unchanged - unsolicited property removed - unsolicited property added |
2.0 propA propB |
1.1 propA propB |
2.0 propB |
2.0 propB |
2.6.4 - Extending Enumeration Values
Extending an enumeration value is a breaking change as existing clients will not be coded to handle the new enumeration value. A breaking change to a message requires the message major version number be incremented.
Where possible the specification will avoid breaking changes. To support this, if the additional enumeration value is related to an existing enumeration value:
-
An additional property with name originalNameX will be added to the message definition, where originalName is the original name of the property and X is the next available index. Indices will be non-negative integers and start at 2.
-
The message minor version number will be incremented. This indicates the change is backwards compatible.
-
The original property definition will be set as deprecated indicating it may be removed in a subsequent major revision of the message.
-
Service implementations which implement the message version that defines the additional property will, if the original property is required, always include both originalName and originalNameX properties.
Existing clients will be unaffected by the additional property as the original property will still be included in the message. New or updated clients can be written to use any of the previous related properties. If a client does not have a use for a new enumeration value, it can continue to use one of the previously defined related properties.
For example, if version 1.0 of a message defines a device property with enumeration values:
- online, offline, hardwareError, userError
And a new enumeration value:
- fraudAttempt
Is added which relates to the existing, less specific, userError value, the new enumeration value could be added to the device2 property in minor increment version 1.1 of the message. In this case when reporting the new enumeration value, version 1.1 of the message will include both:
{
"device": "userError",
"device2": "fraudAttempt"
}
2.7 - End to End Security
A key priority for XFS4IoT is to improve security of the entire environment where XFS is used. This means securing not only the interface between the service and the device, or the interface between the client and the service, but providing security all the way from one end of an operation to the other.
For example, during a cash dispense operation, the transaction will first be authorized by an authorizing host which represents the owner of the cash in the device. That host will communicate through various other systems to the client application, the client application will communicate with the XFS4IoT service and the service will finally communicate with the device. Any part of that process is vulnerable to an attack which could lead to the wrong amount of cash being dispensed. XFS4IoT has been designed to block attacks at any point between the authorizing host and the dispenser hardware.
Details of end-to-end (E2E) security are covered in the generic E2E security specification [Ref. api-2] shared between XFS3.x and XFS4IoT. Generic and specific E2E tokens are defined in that specification. The tokens are passed to commands and returned in events which are documented in this specification, such as with CashDispenser.Dispense
There are specific commands to support E2E security which are covered by this specification, including Common.GetCommandNonce and Common.ClearCommandNonce
Not all commands that could require E2E security are currently covered. When E2E security is being enforced by a device, sensitive commands with no token defined will be blocked from executing. This is required to avoid any way of bypassing security. For example, the cash CashDispenser.Dispense command has a token format defined but the CashDispenser.TestCashUnits command does not. For security, CashDispenser. TestCashUnits must be blocked from dispensing cash, otherwise an attacker could simply replace the CashDispenser. Dispense with calls to CashDispenser.TestCashUnits. Restrictions are documented for each affected command.
3 - Service Publisher Interface
This chapter defines the Service Publisher interface functionality and messages.
3.1 - Command Messages
3.1.1 - ServicePublisher.GetServices
Command sent to the service discovery port to identify services exposed by this publisher.
This command can be used while in Vendor Mode.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
4 - Common Interface
This chapter defines the Common interface functionality and messages.
4.1 - Command Messages
4.1.1 - Common.Status
This command is used to obtain the overall status of the Service. The status includes common status information and can include zero or more interface specific status objects, depending on the interfaces the Service supports. It may also return vendor-specific status information.
This command can be used while in Vendor Mode.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None4.1.2 - Common.Capabilities
This command retrieves the capabilities of the service. It may also return vendor specific capability information.
This command can be used while in Vendor Mode.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None4.1.3 - Common.SetVersions
This command sets the major versions of the command, event and unsolicited message types for the client connection. The completion message version will match the command message version.
Versions are set only for the client connection on which the command is received. It does not modify the versions other client connections expect to use.
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.4 - 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.5 - Common.PowerSaveControl
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.6 - 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.7 - 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.8 - 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.9 - 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.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
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 taken into account 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 are able to 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.
If the card unit is a latched dip unit then the device will latch the card when the chip card will be read, i.e. chip is specified (see below). The card will remain latched until a call to CardReader.Move is made.
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 reader. That is, the card will not physically move but will be accessible to the user.
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
This command is used by the client to perform a hardware reset which will attempt to return the card reader device to a known good state.
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).
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 in order 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 shutterControl is false.
This command terminates a running cash-in transaction. The cash-in transaction is terminated even if this command does not complete successfully.
Command Message
Completion Message
Event Messages
6.2.10 - CashManagement.Reset
This command is used by the application to perform a hardware reset which will attempt to return the device to a known good state. This command does not override a lock obtained on another application or connection.
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.
If items are found inside the device one or more CashManagement.MediaDetectedEvents will be generated to inform the application where the items have actually 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 or not 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.
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 of the 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 presented to the user 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
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.
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 in order 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 CashDispenser, 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.
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.
When this command successfully completes the items are in customer access.
If the previous CashDispenser.Dispense command specified that the amount has to 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.
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 of 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.
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 has the ability to 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 CashDispenser 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.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
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 or not 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.
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 or not 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.
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 or not 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 4 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 "ok" with 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 still 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 of 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 of 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 principal 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 | codeline reported in XFS4IoT |
|---|---|
| ABCD1234 |
aABCDb1234c |
9.2 - Command Messages
9.2.1 - Check.GetTransactionStatus
This command is used to request the status of the current or last media-in transaction as well as current status values outside a transaction. A media-in transaction consists of one or more Check.MediaIn commands. A media-in transaction is initiated by the MediaIn command and remains active until the transaction is either confirmed through the Check.MediaInEnd command, or cancelled by the Check.MediaInRollback, the Check.RetractMedia or the Check.Reset command. Multiple calls to the Check.MediaIn command can be made while a transaction is active to obtain additional items from the customer.
The following values returned by this command can change after the media-in transaction has ended if items are later moved in the device:
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None9.2.2 - Check.MediaIn
This command accepts media into the device from the input position.
A media-in transaction consists of one or more Check.MediaIn commands. A media-in transaction is initiated by the first Check.MediaIn command and remains active until the transaction is either confirmed through the Check.MediaInEnd command, or cancelled by the Check.MediaInRollBack, the Check.RetractMedia or the Check.Reset command. Multiple calls to the Check.MediaIn command can be made while a transaction is active to obtain additional items from the customer. If a media-in transaction is active (i.e. mediaInTransaction is active) when a Check.MediaIn command is successfully cancelled or times out, then the transaction remains active.
When the command is executed, if there is no media in the input slot then the device is enabled for media entry and the Check.NoMediaEvent event is generated when the device is ready to accept media. When the customer inserts the media a Check.MediaInsertedEvent event is generated and media processing begins. If media is already present at the input slot then a Check.MediaInsertedEvent event is generated and media processing begins immediately.
The Check.MediaDataEvent event delivers the code line and all requested image data during execution of this command. One event is generated for each media item scanned by this command. The Check.MediaDataEvent event is not generated for refused media items.
A failure during processing a single media item does not mean that the command has failed even if some or all of the media are refused by the media reader. In this case the command will return success and one or more Check.MediaRefusedEvent events will be sent to report the reasons why the items have been refused.
Refused items are not presented back to the customer with this command. The Check.MediaRefusedEvent event indicates whether or not media must be returned to the customer before further media movement commands can be executed. If the Check.MediaRefusedEvent event indicates that the media must be returned then the application must use the Check.PresentMedia command to return the refused items. If the event does not indicate that the application must return the media items then the application can still elect to return the media items using the Check.PresentMedia command or instead allow the refused items to be returned during the Check.MediaInEnd or Check.MediaInRollBack commands.
If there is no stacker on the device or applicationRefuse is true then just one of the media items inserted are processed by this command, and therefore the command completes as soon as the last image for the first item is produced or when the first item is automatically refused. If there is a stacker on the device then the command completes when the last image for the last item is produced or when the last item is refused.
Command Message
Completion Message
Event Messages
9.2.3 - Check.MediaInEnd
This command ends a media-in transaction. If media items are on the stacker as a result of a Check.MediaIn command, they are moved to the destination specified by Check.SetMediaParameters. Any additional actions specified for the items by Check.SetMediaParameters such as printing, stamping and rescanning are also executed. If the destination has not been set for a media item then the Service will decide which storage unit to put the item into. If no items are in the device the command will complete with the noMediaPresent error and mediaInTransaction will be set to ok.
The way in which media is returned to the customer as a result of this command is defined by presentControl. If false, the application must call Check.PresentMedia to present the media items to be returned as a result of this command. If true the Service presents any returned items implicitly and the application does not need to call Check.PresentMedia.
If items have been refused and the Check.MediaRefusedEvent message has indicated that the items must be returned (i.e. presentRequired is true) then these items must be returned using the Check.PresentMedia command before the Check.MediaInEnd command is issued, otherwise a refusedItems error will be returned. If items have been refused and the Check.MediaRefusedEvent event has indicated that the items do not need to be returned (i.e. presentRequired is false) then the Check.MediaInEnd command causes any refused items which have not yet been returned to the customer (via the Check.PresentMedia command) to be returned along with any items that the application has selected to return to the customer (via the Check.SetMediaParameters command). Even if all items are being deposited, previously refused items will be returned to the customer by this command. The Check.MediaPresentedEvent event(s) inform the application of the position where the media has been presented to.
This command completes when all the media items have been put into their specified storage units and in the case where media is returned to the customer as a result of this command, after the last bunch of media items to be returned to the customer has been presented, but before the last bunch is taken.
The media-in transaction is ended even if this command does not complete successfully.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
9.2.4 - Check.MediaInRollback
This command ends a media-in transaction. All media that is in the device as a result of Check.MediaIn commands is returned to the customer. Nothing is printed on the media. If no items are in the device the command will complete with the noMediaPresent error and mediaInTransaction will be set to rollback.
The way in which media is returned to the customer as a result of this command is defined by presentControl. If false, the application must call Check.PresentMedia to present the media items to be returned as a result of this command. If true the Service presents any returned items implicitly and the application does not need to call Check.PresentMedia.
If items have been refused and the Check.MediaRefusedEvent message has indicated that the items must be returned (i.e. presentRequired is true) then these items must be returned using the Check.PresentMedia command before the Check.MediaInRollBack command is issued, otherwise a refusedItems error will be returned. If items have been refused and the Check.MediaRefusedEvent has indicated that the items do not need to be returned (i.e. presentRequired is false) then the Check.MediaInRollBack command causes any refused items which have not yet been returned to the customer (via the Check.PresentMedia command) to be returned along with any items that are returned as a result of the rollback. The Check.MediaPresentedEvent event(s) inform the application of the position where the media has been presented to.
In the case where media is returned to the customer as a result of this command, this command completes when the last bunch of media items to be returned to the customer has been presented, but before the last bunch is taken.
The media-in transaction is ended even if this command does not complete successfully.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
9.2.5 - Check.ReadImage
On devices where items can be physically rescanned or all the supported image formats can be generated during this command (regardless of the images requested during the Check.MediaIn command), i.e. where rescan is true, then this command is used to obtain additional images and/or reread the code line for media already in the device.
If rescan is false, this command is used to retrieve an image or code line that was initially obtained when the media was initially processed (e.g. during the Check.MediaIn or Check.GetNextItem command). In this case, all images required must have been previously been requested during the Check.MediaIn command.
The media has to be inserted using the command Check.MediaIn. If no media is present the command returns the error code noMediaPresent.
Command Message
Completion Message
Event Messages
None9.2.6 - Check.PresentMedia
This command is used to present media items to the customer.
Applications can use this command to return refused items without terminating the media-in transaction. This allows customers to correct the problem with the media item and reinsert during execution of a subsequent Check.MediaIn command.
This command is also used to return items after a Check.MediaInEnd or Check.MediaInRollBack command when presentControl is false.
A Check.MediaPresentedEvent event is generated when media is presented and a Check.MediaTakenEvent event is generated when the media is taken (if the position has a taken sensor itemsTakenSensor is true.
This command completes when the last bunch of media items to be returned to the customer has been presented, but before the last bunch is taken.
Command Message
Completion Message
Event Messages
9.2.7 - Check.RetractMedia
The media is removed from its present position (media present in device, media entering, unknown position) and stored in the area specified in the input parameters.
A Storage.StorageThresholdEvent event is sent if a high or full condition is reached as a result of this command. If the storage unit is already full and the command cannot be executed, an error is returned and the media remains in its present position.
If media items are to be endorsed/stamped during this operation, then the SetMediaParameters command must be called prior to the Check.RetractMedia command. Where endorsing is specified, the same text will be printed on all media items that are detected.
This command ends the current media-in transaction.
If no items are in the device the command will complete with the noMediaPresent error and the mediaInTransaction will be set to retract.
Command Message
Completion Message
Event Messages
9.2.8 - Check.Reset
This command is used by the application to perform a hardware reset which will attempt to return the device to a known good state. This command does not override a lock obtained on another application or service handle.
The device will attempt to retract or eject any items found anywhere within the device. This may not always be possible because of hardware problems. One or more Check.MediaDetectedEvent events will inform the application where items were actually moved to.
If media items are to be endorsed/stamped during this operation, then the SetMediaParameters must be called prior to the Check.Reset command. Where endorsing is specified, the same text will be printed on all media items that are detected.
This command ends a media-in transaction started by the Check.MediaIn command.
Command Message
Completion Message
Event Messages
9.2.9 - Check.GetNextItem
This command is used to get the next item from the multi-item feed unit and capture the item data. The data and the format of the data that is generated by this command are defined by the input parameters of the Check.MediaIn command. The media data is reported via the Check.MediaDataEvent event.
This command must be supported by all Services where the hardware does not have a stacker or where the Service supports the application making the accept/refuse decision. On single item feed devices this command simply returns the error code noMediaPresent. This allows a single application flow to be used on all devices without a stacker.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
9.2.10 - Check.ActionItem
This command is used to cause the predefined actions (move item to destination, stamping, endorsing, re-imaging) to be executed on the current media item. This command only applies to devices without stackers and on devices with stackers this command is not supported.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
9.2.11 - Check.ExpelMedia
The media that has been presented to the customer will be expelled out of the device.
This command completes after the bunch has been expelled from the device.
This command does not end the current media-in transaction. The application must deal with any media remaining within the device, e.g., by using the Check.MediaInRollBack, Check.MediaInEnd, or Check.RetractMedia command.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None9.2.12 - Check.AcceptItem
This command is used by applications to indicate if the current media item should be accepted or refused. Applications only use this command when the Check.MediaIn command is used in the mode where the application can decide if each physically acceptable media item should be accepted or refused, i.e. applicationRefuse is true.
Command Message
Completion Message
Event Messages
None9.2.13 - Check.SupplyReplenish
After the supplies have been replenished, this command is used to indicate that one or more supplies have been replenished and are expected to be in a healthy state.
Hardware that cannot detect the level of a supply and reports on the supply's status using metrics (or some other means), must assume the supply has been fully replenished after this command is issued. A Common.StatusChangedEvent event must be broadcast to report that the state has changed.
Hardware that can detect the level of a supply must update its status based on its sensors, generate a Common.StatusChangedEvent event if appropriate, and succeed the command even if the supply has not been replenished. If it has already detected the level and reported the new status before this command was issued, the command must succeed and no event is required.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None9.2.14 - Check.SetMediaParameters
This command is used to predefine parameters for the specified media item or all items. The command can be called multiple times to specify individual parameters for each required media item. Any parameter specified replaces any parameters specified for the same media item (or items) on previous commands.
The parameters which can be specified include:
- Destination
- Endorsements, i.e., text to be printed on the media or whether the media is to be stamped
- Images of the media after it has been printed on or stamped
The media is not moved immediately by this command. The requested actions are performed during subsequent commands which move the media:
- On devices with stackers, Check.MediaInEnd
- On devices without stackers, Check.ActionItem
If the bunch is returned with Check.MediaInRollback, none of the requested actions will be performed.
If the media is to be returned to the customer using Check.MediaInEnd or Check.ActionItem, the media can still be endorsed if endorse is true or imaged if endorseImage is true.
The Service will determine which storage unit to use for any items that have not had a destination set by the application.
Command Message
Completion Message
Event Messages
None9.3 - Event Messages
9.3.1 - Check.NoMediaEvent
This reports that the physical media must be inserted into the device in order for the command to proceed.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
9.3.2 - Check.MediaInsertedEvent
This specifies that the physical media has been inserted into the device.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
9.3.3 - Check.MediaRefusedEvent
This is sent when a media item is refused. One message is sent for every media item or bunch of media items that has been refused.
Event Message
9.3.4 - Check.MediaDataEvent
This message returns the code line and all the images requested for each item processed. This can be generated during the Check.MediaIn, Check.MediaInEnd, Check.GetNextItem and Check.ActionItem commands. One message is generated for each item processed, no message is generated for refused items.
Event Message
9.3.5 - Check.MediaRejectedEvent
This reports that an attempt to insert media into the device has been rejected before the media was fully inside the device, i.e. no Check.MediaInsertedEvent event has been generated. Rejection of the media will cause the Check.MediaIn command to complete with a mediaRejected error, at which point the media should be removed.
Event Message
9.3.6 - Check.MediaPresentedEvent
This indicates that media has been presented to the customer for removal.
Event Message
9.4 - Unsolicited Messages
9.4.1 - Check.MediaTakenEvent
This is sent when the media is taken by the customer.
Unsolicited Message
9.4.2 - Check.MediaDetectedEvent
This service event is generated when media is detected in the device during a Check.Reset.
Unsolicited Message
9.4.3 - Check.ShutterStatusChangedEvent
Within the limitations of the hardware sensors this service 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.
Unsolicited Message
10 - Mixed Media
This chapter provides information on how to perform MixedMedia transactions. A Mixed Media transaction is defined as a single transaction on a single device which can accept different kinds of media, specifically cash and checks.
It is possible that the device may process items in mixed bunches within one operation, or require that the different media types are processed in separate operations. The MixedMedia interface defines what type of mixed media transactions the device is capable of and configured for and methods to choose which type of transaction should be performed.
This interface would only be supported by devices which support MixedMedia functionality. A device which can accept cash and checks but not in one transaction would not support this interface.
10.1 - General Information
10.1.1 - Introduction
The MixedMedia service is defined to support hardware devices exists which are able to accept cash and checks in the same transaction either in a single or multiple bunches. The service provides a simple way to report the device's capability to perform such a transaction as well as the methods required to perform such a transaction.
If mixed media is enabled (both cashAccept and checkAccept are true), then moving the media can be performed using either CashAcceptor or Check commands. While equivalent commands such as CashAcceptor.CashInEnd and Check.MediaInEnd perform the same function and could therefore be used interchangeably, it is recommended to use one or other to move the media as this allows existing non mixed media transaction flows to be re-used. The only real advantage to either is that check image parameters can be specified using Check.MediaIn and no such parameters exist in the CashAcceptor service, therefore default or pre-configured check image parameters have to apply.
The interface follows these principles:
- A transaction is not mixed unless the device is capable of performing such an operation and configured to do so.
- If the transaction is accepted and media is deposited to storage units, the same storage units are used regardless of whether the transaction was performed using CashAcceptor or Check commands.
- Media acceptance is based on the current configuration appropriate to the media, for example if EUR 500 has been disabled for acceptance using CashAcceptor.ConfigureNoteTypes, then it is also disabled during a mixed media transaction.
- Events appropriate to the media detected are sent, so for example a Check.MediaDataEvent is sent if a check is detected, while cash events such as CashManagement.InfoAvailableEvent are posted if cash items are detected. If a given item is not detected as either media type (for example, not cash and no codeline detected), it can be reported using either interface.
- If supported, the type of transaction can be changed using the MixedMedia.SetMode command. Example usage may be that customers of the financial institution may be permitted to perform mixed media transactions while customers of other financial institution may only be permitted to deposit cash. Another example may be that mixed media transactions could be disabled if there is no storage unit available to store checks, allowing check only transactions to return all the media after imaging and endorsement.
- If the media is to be cleared to a single storage unit using a retract or reset command, the storage unit should be capable of accepting all such media. If media is to be sorted to appropriate units, for example by specifying itemCassette in CashManagement.Reset, then media are sorted to storage units which support the media types detected.
10.1.2 - Example Transaction flows
This section describes some example mixed media transaction flows. In all cases, equivalent functionality can be achieved using CashAcceptor or Check commands, while events appropriate to the items are sent as they are processed. Some of the example flows are implemented using both using interfaces to illustrate this.
10.1.2.1 - Successful CashAcceptor Mixed Media Transaction
This flow describes a successful MixedMedia transaction flow using CashAcceptor commands to move the media. Successful Check Mixed Media Transaction shows the equivalent flow using Check commands to move the media. The service supports the MixedMedia interface and a mixed media transction can be offered to this customer.
10.1.2.2 - Successful Check Mixed Media Transaction
This flow describes a successful MixedMedia transaction flow using Check commands to move the media. Successful CashAcceptor Mixed Media Transaction shows the equivalent flow using CashAcceptor commands to move the media. The service supports the MixedMedia interface and a mixed media transction can be offered to this customer.
10.1.2.3 - Canceled CashAcceptor Mixed Media Transaction
This flow describes a MixedMedia transaction flow using CashAcceptor commands to move the media, where the transaction is canceled by the application or customer and the media is therefore rolled back. The flow is identical to Successful CashAcceptor Mixed Media Transaction up to Display amount inserted.
10.1.2.4 - Canceled Check Mixed Media Transaction
This flow describes a MixedMedia transaction flow using Check commands to move the media, where the transaction is canceled by the application or customer and the media is therefore rolled back. The flow is identical to Successful Check Mixed Media Transaction up to Display amount inserted.
10.1.2.5 - Successful CashAcceptor Mixed Media Transaction with item(s) refused
This flow describes a successful MixedMedia transaction flow using CashAcceptor commands to move the media. One item is refused and taken by the customer. The flow is identical to Successful CashAcceptor Mixed Media Transaction up to Accept Items. The transaction can also be performed using equivalent Check commands.
10.1.2.6 - CashAcceptor Mixed Media Transaction with item(s) retracted
This flow describes a MixedMedia transaction flow using CashAcceptor commands to move the media, where the transaction is canceled by the application or customer and the media is therefore rolled back, but the media is not taken by the customer and is therefore retracted after a timeout expires. The same media which was rolled back is retracted. The flow is identical to Successful CashAcceptor Mixed Media Transaction up to Prompt Customer.
10.1.2.7 - CashAcceptor Mixed Media Transaction with items returned, some taken and others retracted
This flow describes a MixedMedia transaction flow using CashAcceptor commands to move the media, where the transaction is canceled by the application or customer and the media is therefore rolled back. The customer takes one of the items rolled back but not all, therefore the remaining item is retracted after a timeout expires. The flow is identical to Successful CashAcceptor Mixed Media Transaction up to Prompt Customer.
10.1.2.8 - Check Mixed Media Transaction where items jam during Rollback
This flow describes a MixedMedia transaction flow using Check commands to move the media. A hardware error occurs during the transaction therefore Check.Reset is used to recover and in this case the media was successfully returned to the customer and taken. The same flow can be performed using equivalent CashAcceptor commands. The flow is identical to Successful Check Mixed Media Transaction up to Display amount inserted.
10.2 - Command Messages
10.2.1 - MixedMedia.SetMode
This command is used to set the transaction mode for the device and is only applicable for MixedMedia processing. The mode determines which type of item the device will process in subsequent transactions.
An example of how this can be used is on a device which can accept cash and checks. The decision whether to allow acceptance of either or both types of media could be based on the individual customer, or switched dynamically based on bank or local requirements.
The mode:
- Applies to all subsequent transactions on this device
- Is persistent
- Is unaffected by a device reset by for example a Check.Reset or reset on another interface
- Fails if a transaction is in progress on the device if the dynamic property is false
- Fails with the invalidData error where an attempt is made to set a mode that is not supported.
The current mode is reported by mixedMedia status. If the command is successful, status is updated.
Command Message
Completion Message
Event Messages
None11 - Key Management Interface
This chapter defines the Key Management interface functionality and messages.
This section describes the general interface for the following functions:
- Loading of encryption keys.
- EMV 4.0 PIN blocks, EMV 4.0 public key loading, static and dynamic data verification.
Important Notes:
- This revision of this specification does not define all key management procedures; some key management is still vendor-specific.
- Key space management is customer-specific, and is therefore handled by vendor-specific mechanisms.
Key values are passed to the API as binary hexadecimal values, for example: 0123456789ABCDEF = 0x01 0x23 0x45 0x67 0x89 0xAB 0xCD 0xEF. When hex values are passed to the API within strings, the hex digits 0xA to 0xF can be represented by characters in the ranges 'a' to 'f' or 'A' to 'F'.
Certain levels of the PCI security standards specify that if a Key Encryption Key (KEK) is deleted or replaced, then all keys in the hierarchy under that KEK are also removed. When a key is deleted, clients should check the loaded state of other keys using KeyManagement.GetKeyDetail.
11.1 - General Information
11.1.1 - References
11.1.2 - RKL Terminology
This section provides extended explanation of concepts and functionality needing further clarification. The terminology as described below is used within the following sections.
| Definitions and Abbreviations | Description |
|---|---|
| ATM | Automated Teller Machine, used here for any type of self-service terminal, regardless whether it actually dispenses cash. |
| CA | Certificate Authority. |
| Certificate | A data structure that contains a public key and a name that allows certification of a public key belonging to a specific individual. This is certified using digital signatures. |
| HOST | The remote system that a device communicates with. |
| KTK | Key Transport Key. |
| PKI | Public Key Infrastructure. |
| Private Key | The key of an entity's key pair that should only be used by that entity. |
| Public Key | The key of an entity's key pair that can be made public. |
| Symmetric Key | A key used with symmetric cryptography. |
| Verification Key | A key that is used to verify the validity of a certificate. |
| SignatureIssuer | An entity that signs the device's public key at production time which could be for instance, the device manufacturer. |
| Notation of Cryptographic Items and Functions | Description |
|---|---|
| SKE | The private key belonging to entity E. |
| PKE | The public belonging to entity E. |
| SKDEVICE | The private key belonging to the device. |
| PKDEVICE | The public key belonging to the device. |
| SKHOST | The private key belonging to the Host. |
| PKHOST | The public key belonging to the Host. |
| SKSI | The private key belonging to Signature Issuer. |
| PKSI | The public key belonging to Signature Issuer. |
| SKROOT | The root private key belonging to the Host. |
| PKROOT | The root public key belonging to the Host. |
| KNAME | A symmetric key. |
| CertHOST | A Certificate that contains the public verification of the host and is signed by a trusted Certificate Authority. |
| CertDEVICE | A Certificate that contains the device public verification or encipherment key, which is signed by a trusted Certificate Authority. |
| CertCA | The Certificate of a new Certificate Authority. |
| RDEVICE | Random Number of the device. |
| IHOST | Identifier of the Host. |
| KKTK | Key Transport Key. |
| RHOST | Random number of the Host. |
| IDEVICE | Identifier of the device. |
| TPDEVICE | Thumb Print of the device. |
| Sign ( SKE )[ D ] | The signing of data block D, using the private key SKE. |
| Recover ( PKE )[ S ] | The recovery of the data block D from the signature S, using the private key PKE. |
| RSACrypt ( PKE )[ D ] | RSA Encryption of the data block D using the public key PKE. |
| Hash [ M ] | Hashing of a message M of arbitrary length to a 20 Byte hash value. |
| Des ( K )[ D ] | DES encipherment of an 8 byte data block D using the secret key K. |
| Des-1 ( K )[ D ] | DES decipherment of an 8 byte data block D using the 8 byte secret key K. |
| Des3 ( K )[ D ] | Triple DES encipherment of an 8 byte data block D using the 16 byte secret key K = ( KL || KR ), equivalent to Des ( KL ) [ Des-1 ( KR ) [ Des ( KL ) [ D ] ] ]. |
| Des3-1 ( K )[ D ] | Triple DES decipherment of an 8 byte data block D using the 16 byte secret key K = ( KL || KR ), equivalent to Des-1 ( KL ) [ Des ( KR ) [ Des-1 ( KL ) [ D ] ] ]. |
| RndE | A random number created by entity E. |
| UIE | Unique Identifier for entity E. |
| ( A || B ) | Concatenation of A and B. |
11.1.3 - Remote Key Loading Using Signatures
11.1.3.1 - RSA Data Authentication and Digital Signatures
Digital signatures rely on a public key infrastructure (PKI). The PKI model involves an entity, such as a Host, having a pair of encryption keys – one private, one public. These keys work in consort to encrypt, decrypt and authenticate data. One way authentication occurs is through the application of a digital signature. For example:
- The Host creates some data that it would like to digitally sign;
- The Host runs the data through a hashing algorithm to produce a hash or digest of the data. The digest is unique to every block of data – a digital fingerprint of the data, much smaller and therefore more economical to encrypt than the data itself.
- The digest is encrypted with the Host's private key.
This is the digital signature – a data block digest encrypted with the private key. The Host then sends the following to the device:
- The data block.
- The digital signature.
- The host's public key.
To validate the signature, the device performs the following:
- The device runs data through the standard hashing algorithm – the same one used by the Host – to produce a digest of the data received. Consider this digest2;
- The device uses the Host's public key to decrypt the digital signature. The digital signature was produced using the Host's private key to encrypt the data digest; therefore, when decrypted with the Host's public key it produces the same digest. Consider this digest1. Incidentally, no other public key in the world would work to decrypt digest1 – only the public key corresponding to the signing private key.
- The device compares digest1 with digest2.
If digest1 matches digest2 exactly, the device has confirmed the following:
-
The data was not tampered with in transit. Changing a single bit in the data sent from the Host to the Key Management Device would cause digest2 to be different from digest1. Every data block has a unique digest; therefore, an altered data block is detected by the device.
-
The Public key used to decrypt the digital signature corresponds to the private key used to create it. No other public key could possibly work to decrypt the digital signature, so the device was not handed someone else's public key.
This gives an overview of how Digital Signatures can be used in Data Authentication. In particular, Signatures can be used to validate and securely install Encryption Keys. The following section describes Key Exchange and the use of Digital signatures.
11.1.3.2 - RSA Secure Key Exchange using Digital Signatures
In summary, both end points, the Host and Device, inform each other of their Public Keys. This information is then used to securely send the Master Key to the Device. A trusted third party, the Signature Issuer, is used to generate the signatures for the Public keys of each end point, ensuring their validity.
The detail of this is as follows:
Purpose: The Host wishes to install a new Master Key ( KM ) on the device securely.
Assumptions:
-
The Host has obtained the Public Key ( PKSI ) from the Signature Issuer.
-
The Host has provided the Signature Issuer with its Public Key ( PKHOST ), and receives the corresponding signature Sign( SKSI )[ PKHOST ]. The Signature Issuer uses its own Private Key ( SKSI ) to create this signature.
-
In the case where Enhanced Remote Key Loading is used, the Host has provided the Signature Issuer with its Public Key ( PKROOT ), and receives the corresponding signature Sign ( SKSI )[ PKROOT ]. The Host has generated another key pair PKHOST and SKHOST and signs the PKHOST with the SKROOT.
-
( Optional ) The Host obtains a list of the valid device Unique Identifiers. The Signature Issuer installs a Signature Sign( SKSI )[ UIDEVICE ] for the Unique ID ( UIDEVICE ) on the Device. The Signature Issuer uses SKSI to do this.
-
The Signature Issuer installs its Public Key ( PKSI ) on the Device. It also derives and installs the Signature Sign( SKSI )[ PKDEVICE ] of the Device's Public Key ( PKDEVICE ) on the Device. The Signature Issuer uses SKSI to do this.
-
The Device additionally contains its own Public ( PKDEVICE ) and Private Key ( SKDEVICE ).
Step 1
The Device sends its Public Key to the Host in a secure structure:
The Device sends its Public Key with its associated Signature. When the Host receives this information it will use the Signature Issuer's Public Key to validate the signature and obtain the Device Public Key.
The command used to export the device's public key securely as described above is:
Step 2 (Optional)
The Host verifies that the key it has just received is from a valid sender:
It does this by obtaining the Device Unique Identifier. The Device sends its Unique Identifier with its associated Signature. When the Host receives this information it will use the Signature Issuer's Public Key to validate the signature and retrieve the Device Unique ID. It can then check this against the list it received from the Signature Issuer.
The command used to export the Device Unique Identifier is:
Step 3 ( Enhanced Remote Key Loading only )
The Host sends its root public key to the Device:
The Host sends its Root Public Key ( PKROOT ) and associated Signature. The Device verifies the signature using PKSI and stores the key.
The command used to import the Host root public key securely as described above is:
Step 4
The Host sends its public key to the Device:
The Host sends its Public Key ( PKHOST ) and associated Signature. The Device verifies the signature using PKSI ( or PKROOT in the Enhanced Remote Key Loading Scheme ) and stores the key.
The command used to import the Host public key securely as described above is:
Step 5
The Device receives its Master Key from the Host:
The Host encrypts the Master Key ( KM ) with PKDEVICE. A signature for this is then created using SKHOST. The Device will then validate the signature using PKHOST and then obtain the master key by decrypting using SKDEVICE.
The commands used to exchange master symmetric keys as described above are:
Step 6 — Alternative including random number
The Host requests the Device to begin the DES key transfer process and generate a random number.
The Host encrypts the Master Key ( KM ) with PKDEVICE. A signature for the random number and encrypted key is then created using SKHOST.
The Device will then validate the signature using PKHOST, verify the random number and then obtain the master key by decrypting using SKDEVICE.
The commands used to exchange master symmetric keys as described above are:
11.1.3.3 - Initialization Phase – Signature Issuer and ATM PIN
This would typically occur in a secure manufacturing environment.
11.1.3.4 - Initialization Phase – Signature Issuer and Host
This would typically occur in a secure offline environment.
11.1.3.5 - Key Exchange – Host and ATM PIN
This following is a typical interaction for the exchange of the initial symmetric master key between host and device.
The following is the recommended sequence of interchanges.
11.1.3.6 - Key Exchange (with random number) – Host and ATM PIN
This following is a typical interaction for the exchange of the initial symmetric master key when the device supports the KeyManagement.StartKeyExchange command.
11.1.3.7 - Enhanced RKL, Key Exchange (with random number) – Host and ATM PIN
This following is a typical interaction for the exchange of the initial symmetric master key when the host and device supports the Enhanced Signature Remote Key Loading scheme.
11.1.3.8 - Default Keys and Security Item loaded during manufacture
Several keys and a security item which are mandatory for the 2 party/Signature authentication scheme are installed during manufacture. These items are given fixed names so multi-vendor applications can be developed without the need for vendor specific configuration tools.
| Item Name | Item Type | Signed by | Description |
|---|---|---|---|
| "_SigIssuerVendor" | Public Key | N/A | The public key of the signature issuer, i.e. PKSI |
| "_DeviceCryptKey" | Public/Private key-pair | The private key associated with _SigIssuerVendor | The key-pair used to encrypt and encrypt the symmetric. key, i.e SKDEVICE and PKDEVICE. The public key is used for encryption by the host and the private for decryption by the Device. |
| "_DeviceCryptCert" | Public/Private key-pair | CA | This key is used for certificate based remote key loading when transporting symmetric key. The private key is used for decryption by the device. i.e. CertDEVICE |
| "_HostCert" | Public Key | CA | The certificate issued by the host, which contains a public key to verify the certificate. i.e. CertHOST |
In addition, the following optional keys can be loaded during manufacture.
| Item Name | Item Type | Signed by | Description |
|---|---|---|---|
| "_DeviceSignKey" | Public/Private key-pair | The private key associated with _SigIssuerVendor | A key-pair where the private key is used to sign data, e.g. other generated key pairs. |
11.1.4 - Remote Key Loading Using Certificates
The following sections demonstrate the proper usage of the KeyManagement interface to accomplish Remote Key Loading using Certificates. There are sequence diagrams to demonstrate how the KeyManagement interface can be used to complete each of the TR-34 operations.
11.1.4.1 - Certificate Exchange and Authentication
In summary, both end points, the device and the Host, inform each other of their Public Keys. This information is then used to securely send the Master Key to the device. A trusted third party, Certificate Authority (or a HOST if it becomes the new CA), is used to generate the certificates for the Public Keys of each end point, ensuring their validity. NOTE: The KeyManagement.LoadCertificate and KeyManagement.GetCertificate commands do not necessarily need to be called in the order below. This way though is the recommended way.
The following flow is how the exchange authentication takes place:
- KeyManagement.LoadCertificate is called. In this message contains the host certificate, which has been signed by the trusted CA. The device uses the Public Key of the CA (loaded at the time of production) to verify the validity of the certificate. If the certificate is valid, the device stores the HOST’s Public Verification Key.
- Next, KeyManagement.GetCertificate is called. The device then sends a message that contains a certificate, which is signed by the CA and is sent to the HOST. The HOST uses the Public Key from the CA to verify the certificate. If valid then the HOST stores the device’s verification or encryption key (primary or secondary this depends on the state of the device).
The following diagram shows how the Host and ATM Load and Get each other’s information to make Remote Key Loading possible:
11.1.4.2 - Remote Key Exchange
After the above has been completed, the host is ready to load the key into the device. The following is done to complete this and the application must complete the Remote Key Exchange in this order:
-
First, the KeyManagement.StartKeyExchange is called. This returns RDEVICE from the device to be used in the authenticating the KeyManagement.ImportKey message.
-
The Host obtains a Key Transport Key and wants to transfer it to the device. The Host constructs a key block containing an identifier of the host, IHOST, and the key, KKTK, and enciphers the block, using the device's Public Encryption Key from the KeyManagement.GetCertificate command.
-
The host generates random data and builds the outer message containing the random number of the host, RHOST, the random number of the device returned in the KeyManagement.StartKeyExchange command, RDEVICE, the identifier of the encryptor, IENC, and the enciphered key block. The host signs the whole block using its private signature key and sends the message to the device using KeyManagement.ImportKey.
The device then verifies the host's signature on the message by using the host's Public Verification Key. Then the device checks the identifier and the random number of the device passed in the message to make sure that the device is talking to the right host. The device then deciphers the enciphered block using its private verification key. After the message has been deciphered, the device checks the Identifier of the host. Finally, if everything checks out to this point the device will load the Key Transport Key.
NOTE: If one step of this verification occurs the device will return the proper error to the host.
-
After the Key Transport Key has been accepted, the device constructs a message that contains the random number of the host, the random number of the device and the host identifier all signed by the private signature key of the device. This message is sent to the host.
-
The host verifies the message sent from the device by using the device's public verification key. The host then checks the identifier of the host and then compares the identifier in the message with the one stored in the host. The host then checks the random number sent in the message and to the one stored in the host. The host finally checks the device's random number with the one received in the KeyManagement.StartKeyExchange command.
The following diagram below shows how the host and device transmit the Key Transport Key.
11.1.4.3 - Replace Certificate
After the key has been loaded into the device, the following can be completed:
- (Optional) KeyManagement.ReplaceCertificate. This is called by entity that would like to take over the job of being the CA. The new CA requests a Certificate from the previous Certificate Authority. The host must over-sign the message to take over the role of the CA to ensure that the device accepts the new Certificate Authority. The host sends the message to the device. The device uses the host's Public Verification Key to verify the host's signature. The device uses the previous CA's Public Verification Key to verify the signature on the new Certificate sent in the message. If valid, the device stores the new CA's certificate and uses the new CA's Public Verification Key as its new CA verification key. The diagram below shows how the host and the Device communicate to load the new CA.
11.1.4.4 - Primary and Secondary Certificate
Primary and Secondary Certificates for both the Public Verification Key and Public Encipherment Key are pre-loaded into the device. Primary Certificates will be used until told otherwise by the host via the KeyManagement.LoadCertificate or KeyManagement.ReplaceCertificate commands. This change in state will be specified in the PKCS#7 (See [Ref. keymanagement-1]) message of the KeyManagement.LoadCertificate or KeyManagement.ReplaceCertificate commands. The reason why the host would want to change states is because the host thinks that the Primary Certificates have been compromised.
After the host tells the device to shift to the secondary certificate state, only Secondary Certificates can be used. The device will no longer be able to go back to the Primary State and any attempts from the host to get or load a Primary Certificate will return an error. When either Primary or Secondary certificates are compromised it is up to the vendor on how the device should be handled with the manufacturer.
11.1.5 - Remote Key Loading Using TR34
11.1.5.1 - TR34 BIND To Host
This section defines the commands to use when transferring a TR34 BIND token as defined in X9 TR34-2019 [Ref. keymanagement-9].
This step is a pre-requisite for all other TR34 operations. The device must be bound to a host before any other TR34 operation will succeed.
NB: While the device encryption certificate is not required to build the BIND token, it is recommended that the encryption certificate is retrieved during this process and is stored for future use. Otherwise, if not stored, it will need to be requested prior to all other TR34 token transfer requests.
11.1.5.2 - TR34 Key Transport
There are two protocols that can be used to transport symmetric keys under TR34; these are the One Pass and Two Pass protocols. The use of XFS4IoT commands for these two protocols are shown in the following sections.
- NOTE: The crklLoadOptions capability indicates which protocol the device supports.*
11.1.5.2.1 - One Pass
This section defines the command to use when transferring a TR34 KEY token (1-pass) as defined in X9 TR34-2019 [Ref. keymanagement-9].
Pre-condition: A successful BIND command has completed such that the device is bound to the host.
11.1.5.2.2 - Two Pass
This section defines the command to use when transferring a TR34 KEY token (2-pass) as defined in X9 TR34-2019 [Ref. keymanagement-9].
Pre-condition: A successful BIND command has completed such that the device is bound to the host.
NB: Dotted lines represent commands that are only required if the device encryption certificate has not been previously stored by the host.
11.1.5.3 - TR34 REBIND To New Host
This section defines the command to use when transferring a TR34 REBIND token as defined in X9 TR34-2019 [Ref. keymanagement-9].
Pre-condition: A successful BIND command has completed such that the device is bound to the host.
NB: Dotted lines represent commands that are only required if the device encryption certificate has not been previously stored by the host.
11.1.5.4 - TR34 Force REBIND To New Host
This section defines the command to use when transferring a TR34 Force REBIND token as defined in X9 TR34-2019 [Ref. keymanagement-9].
Pre-condition: A successful BIND command has completed such that the device is bound to the host.
NB: Dotted lines represent commands that are only required if the device encryption certificate has not been previously stored by the host.
Although the random number token is requested as part of this operation, it is discarded by the host and is not actually used in the Force Rebind token.
11.1.5.5 - TR34 UNBIND From Host
This section defines the command to use when transferring a TR34 UNBIND token as defined in X9 TR34-2019 [Ref. keymanagement-9].
Pre-condition: A successful BIND command has completed such that the device is bound to the host.
NB: Dotted lines represent commands that are only required if the device encryption certificate has not been previously stored by the host.
11.1.5.6 - TR34 Force UNBIND From Host
This section defines the command to use when transferring a TR34 Force UNBIND token as defined in X9 TR34-2019 [Ref. keymanagement-9].
Pre-condition: A successful BIND command has completed such that the device is bound to the host.
NB: Dotted lines represent commands that are only required if the device encryption certificate has not been previously stored by the host.
Although the random number token is requested as part of this operation, it is discarded by the host and is not actually used in the Force Unbind token.
11.1.6 - EMV Support
EMV supported consists of the following:
- Import of the Certification Authority and Chip Card Public Keys
- Creating the PIN blocks for offline PIN verification and verifying static and dynamic data.
This section is used to further explain concepts and functionality that needs further clarification.
The service is able to manage the EMV chip card regarding the card authentication and the RSA local PIN verification. Two steps are mandatory in order to reach these two functions: The loading of the keys which come from the Certification Authorities or from the card itself, and the EMV PIN block management.
The service is responsible for all key validation during the import process. The application is responsible for management of the key lifetime and expiry after the key is successfully imported.
11.1.6.1 - Key Loading
The final goal of an application is to retrieve the keys located on card to perform the operations of authentication or local PIN check (RSA encrypted). These keys are provided by the card using EMV certificates and can be retrieved using a Public Key provided by a Certification Authority. The application should first load the keys issued by the Certification Authority. At transaction time the application will use these keys to load the keys that the application has retrieved from the chip card.
Certification Authority keys
These keys are provided in the following formats:
- Plain text.
- Plain Text with EMV 2000 Verification Data (See [Ref. keymanagement-3]).
- EPI CA (or self signed) format as specified in the Europay International, EPI CA Module Technical – Interface specification Version 1.4 (See [Ref. keymanagement-4]).
- pkcsV15 encrypted (as used by GIECB in France) (See [Ref. keymanagement-5]).
EPI CA format
The following table corresponds to table 4 of the Europay International, EPI CA Module Technical – Interface specification Version 1.4 (See [Ref. keymanagement-4]) and identifies the Europay Public Key (self-certified) and the associated data:
| Field Name | Length | Description | Format |
|---|---|---|---|
| ID of Certificate Subject | 5 | RID for Europay | Binary |
| Europay public key Index | 1 | Europay public key Index | Binary |
| Subject public key Algorithm Indicator | 1 | Algorithm to be used with the Europay public key Index, set to 0x01 | Binary |
| Subject public key Length | 1 | Length of the Europay public key Modulus (equal to Nca) | Binary |
| Subject public key Exponent Length | 1 | Length of the Europay public key Exponent | Binary |
| Leftmost Digits of Subject public key | Nca-37 | Nca-37 most significant bytes of the Europay public key Modulus | Binary |
| Subject public key Remainder | 37 | 37 least significant bytes of the Europay public key Modulus | Binary |
| Subject public key Exponent | 1 | Exponent for Europay public key | Binary |
| Subject public key Certificate | Nca | Output of signature algorithm | Binary |
Table 1
The following table corresponds to table 13 of the Europay International, EPI CA Module Technical – Interface specification Version 1.4 and identifies the Europay Public Key Hash code and associated data.
| Field Name | Length | Description | Format |
|---|---|---|---|
| ID of Certificate Subject | 5 | RID for Europay | Binary |
| Europay public key Index | 1 | Europay public key Index | Binary |
| Subject public key Algorithm Indicator | 1 | Algorithm to be used with the Europay public key Index, set to 0x01 | Binary |
| Certification Authority public key Check Sum | 20 | Hash-code for Europay public key | Binary |
Table 2
Table 2 corresponds to table 13 of the Europay International, EPI CA Module Technical – Interface specification Version 1.4 (See [Ref. keymanagement-4]).
Chip card keys
These keys are provided as EMV certificates which come from the chip card in a multiple layer structure (issuer key first, then the ICC keys). Two kinds of algorithm are used with these certificates in order to retrieve the keys: One for the issuer key and the other for the ICC keys (ICC Public Key and ICC PIN encipherment key). The associated data with these algorithms – The PAN (Primary Account Number) and the SDA (Static Data to be Authenticated) - come also from the chip card.
11.1.6.2 - PIN Block Management
The PIN block is generated using PinPad.GetPinBlock. The format formEmv is used indicate to the service that the PIN block must follow the requirements of the EMVCo, Book2 – Security & Key management Version 4.0 document. The property customerData is used in this case to transfer to the PIN service the challenge number coming from the chip card. The final encryption must be done using a RSA Public Key. Please note that the application is responsible to send the PIN block to the chip card inside the right APDU.
11.1.6.3 - SHA-1 Digest
The SHA-1 Digest is a hash algorithm used by EMV in validating ICC static and dynamic data item. The SHA-1 Digest is supported through the digest command. The application will pass the data to be hashed to the Service Provider. Once the device completes the SHA-1 hash code, the Service Provider will return the 20-byte hash value back to the application.
11.1.7 - KeyManagement.ImportKey command Input-Output Parameters
This section describes the input/output parameters for various scenarios in which the KeyManagement.ImportKey command is used.
11.1.7.1 - Importing a 3DES 16-byte Terminal Master Key using Signature-based Remote Key Loading
KeyManagement.ImportKey command payload
{
"header": {
"type": "command",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"key": "testKey","
"keyAttributes": {
"keyUsage": "K0",
"algorithm": "T",
"modeOfUse": "D"
},
"value": "<encrypted key value>",
"decryptKey": "deviceCryptKey",
"decryptKey": "rsaesOaep",
"verificationData": "<signature generated by the host>",
"verifyKey": "hostKey",
"verifyAttributes": {
"cryptoMethod": "rsassaPss",
"hashAlgorithm": "sha256"
}
}
}
KeyManagement.ImportKey completion payload
{
"header": {
"type": "completion",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"verificationData": "<key check value>",
"verifyAttributes": {
"keyUsage": "00",
"algorithm": "T",
"modeOfUse": "V",
"cryptoMethod": "kcvZero"
},
"keyLength": 128
}
}
11.1.7.2 - Importing a 3DES 16-byte Pin Encryption Key with a Key Check Value in the Input
KeyManagement.ImportKey command payload
{
"header": {
"type": "command",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"key": "testKey",
"keyAttributes": {
"keyUsage": "P0",
"algorithm": "T",
"modeOfUse": "E"
},
"value": "<encrypted key value>",
"decryptKey": "masterKey",
"decryptMethod": "ecb",
"verificationData": "<key check value encoded>",
"verifyKey": "verifyKey",
"verifyAttributes": {
"cryptoMethod": "kcvZero"
}
}
}
KeyManagement.ImportKey completion payload
{
"header": {
"type": "completion",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"keyLength": 128
}
}
11.1.7.3 - Importing a 3DES 16-byte MAC (Algorithm 3) Key
KeyManagement.ImportKey command payload
{
"header": {
"type": "command",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"key": "testKey","
"keyAttributes": {
"keyUsage": "M3",
"algorithm": "T",
"modeOfUse": "G"
}
"value": "<encrypted key value encoded>",
"decryptKey": "masterKey",
"decryptMethod": "ecb"
}
KeyManagement.ImportKey completion payload
{
"header": {
"type": "completion",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"verificationData": "<key check value>",
"verifyAttributes": {
"keyUsage": "00",
"algorithm": "T",
"modeOfUse": "V",
"cryptoMethod": "kcvZero"
},
"keyLength": 128
}
}
11.1.7.4 - Importing a 2048-bit Host RSA public key
KeyManagement.ImportKey command payload
{
"header": {
"type": "command",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"key": "hostKey","
"keyAttributes": {
"keyUsage": "S0",
"algorithm": "R",
"modeOfUse": "V"
},
"value": "<key value>",
"verificationData": "<signature generated by the vendor signature issuer>",
"verifyKey": "sigIssuerVendor",
"verifyAttributes": {
"cryptoMethod": "rsassaPss",
"hashAlgorithm": "sha256"
}
}
}
KeyManagement.ImportKey completion payload
{
"header": {
"type": "completion",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"verificationData": "<sha256 digest>",
"verifyAttributes": {
"keyUsage": "S0",
"algorithm": "R",
"modeOfUse": "V",
"hashAlgorithm": "sha256"
},
"keyLength": 2048
}
}
11.1.7.5 - Importing a 3DES 24-byte Data Encryption Key via an X9.143 Keyblock
KeyManagement.ImportKey command payload
{
"header": {
"type": "command",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"key": "testKey","
"keyAttributes": {
"keyUsage": "D0",
"algorithm": "T",
"modeOfUse": "E"
},
"value": "<key block>",
"decryptKey": "masterKey"
}
}
KeyManagement.ImportKey completion payload
{
"header": {
"type": "completion",
"name": "KeyManagement.ImportKey",
"requestId": 12345
},
"payload" : {
"keyLength": 192
}
}
11.1.8 - DUKPT
| Definitions and Abbreviations | Description |
|---|---|
| DUKPT | Derived Unique Key Per Transaction |
| BDK | Base Derivation Key |
| IPEK | Initial PIN Encryption Key |
| KSN | Key Serial Number. |
| TRSM | Tamper Resistant Security Module. |
For additional information see [Ref. keymanagement-10].
The IPEK key is given a fixed name so multi-vendor applications can be developed without the need for vendor specific configuration tools.
The BDK is used to derive the IPEK. When a IPEK is loaded, derived future keys are stored and the IPEK deleted. Therefore, while the IPEK is no longer loaded, future keys directly related to it are. Therefore, the IPEK will be reported as loaded.
The primary use of an IPEK future key is to create a variant for PIN encryption. If the optional variant data encryption and MAC keys are supported, to use those keys in the Crypto.CryptoData and Crypto.GenerateAuthentication commands, the IPEK key name must be used as the key name and the algorithm must be cryptTriDesCbc and cryptTriDesMac respectively.
The optional variant response data encryption and MAC keys are not supported.
If DUKPT is supported, this key must be included in the KeyManagement.GetKeyDetail output.
| Item Name | Description |
|---|---|
| _DUKPTIPEK | This key represents the IPEK, the derived future keys stored during import of the IPEK and the variant per transaction keys (PIN and optionally data and MAC). |
11.1.9 - Restricted Encryption Key Command Usage
This example command flow sequence shows how encryption keys can be derived/not derived if the master key has a restricted use.
In this example the master keys are loaded using the secure key entry. Loading with RKL works in the same way.
Master key restriction prevents import of keys with incorrect usage:
11.1.10 - Secure Key Entry Command Usage
This section provides an example of the sequence of commands required to enter an encryption key securely. In the following sequence, the client application retrieves the keyboard secure key entry mode and associated keyboard layout and displays an image of the keyboard for the user. It then gets the first key part, verifies the KCV for the key part and stores it. The sequence is repeated for the second key part and then finally the key part is activated.
11.2 - Command Messages
11.2.1 - KeyManagement.GetKeyDetail
This command returns extended detailed information about the keys in the encryption module, including DES, DUKPT, AES, RSA private and public keys.
This command will also return information on all keys loaded during manufacture that can be used by applications. Details relating to the keys loaded using OPT (via the ZKA ProtIsoPs protocol) are retrieved using the ZKA hsmLdi protocol. These keys are not reported by this command.
Command Message
Completion Message
Event Messages
None11.2.2 - KeyManagement.Initialization
The encryption module must be initialized before any encryption function can be used. Every call to KeyManagement.Initialization destroys all application keys that have been loaded or imported; it does not affect those keys loaded during manufacturing.
Usually this command is called by an operator task and not by the application program.
Public keys imported under the RSA Signature based remote key loading scheme when public key deletion authentication is required will not be affected. However, if this command is requested in authenticated mode, public keys that require authentication for deletion will be deleted. This includes public keys imported under either the RSA Signature based remote key loading scheme or the TR34 RSA Certificate based remote key loading scheme.
Initialization also involves loading 'initial' application keys and local vendor dependent keys. These can be supplied, for example, by an operator through a keyboard, a local configuration file, remote RSA key management or possibly by means of some secure hardware that can be attached to the device. The application 'initial' keys would normally get updated by the application during a KeyManagement.ImportKey command as soon as possible. Local vendor dependent static keys (e.g. storage, firmware and offset keys) would normally be transparent to the application and by definition cannot be dynamically changed.
Where initial keys are not available immediately when this command is issued (i.e. when operator intervention is required), the Service returns accessDenied and the application must await the KeyManagement.InitializedEvent.
This function also resets the HSM terminal data, except session key index and trace number.
This function resets all certificate data and authentication public/private keys back to their initial states at the time of production (except for those public keys imported under the RSA Signature based remote key loading scheme when public key deletion authentication is required). Key-pairs created with KeyManagement.GenerateRSAKeyPair are deleted.
Any keys installed during production, which have been permanently replaced, will not be reset.
Any Verification certificates that may have been loaded must be reloaded. The Certificate state will remain the same, but the KeyManagement.LoadCertificate or KeyManagement.ReplaceCertificate commands must be called again.
When multiple ZKA HSMs are present, this command deletes all keys loaded within all ZKA logical HSMs.
Command Message
Completion Message
Event Messages
None11.2.3 - KeyManagement.DeriveKey
A key is derived from input data using a key generating key and an initialization vector.
The input data can be expanded with a fill-character to the necessary length (mandated by the encryption algorithm being used). The derived key is imported into the encryption module and can then be used for further operations.
Command Message
Completion Message
Event Messages
None11.2.4 - KeyManagement.Reset
Sends a service reset to the Service.
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
None11.2.5 - KeyManagement.ImportKey
The encryption key passed by the application is loaded in the encryption module.
For secret keys, the key must be passed encrypted with an accompanying "key encrypting key" or "key block protection key".
For public keys, they key is not required to be encrypted but is required to have verification data in order to be loaded.
Command Message
Completion Message
Event Messages
None11.2.6 - KeyManagement.DeleteKey
This command deletes a key. If authentication data is required the KeyManagement.StartAuthenticate command should be used to obtain the data to sign.
Deletion of the key may cause other keys to be deleted. On successful completion of this command, it is recommended that clients use the KeyManagement.GetKeyDetail command to check which keys remain loaded.
Command Message
Completion Message
Event Messages
None11.2.7 - KeyManagement.ExportRSAIssuerSignedItem
This command is used to export data elements from the device, which have been signed by an offline Signature Issuer. This command is used when the default keys and Signature Issuer signatures, installed during manufacture, are to be used for remote key loading.
This command allows the following data items are to be exported:
- The Security Item which uniquely identifies the device. This value may be used to uniquely identify a device and therefore confer trust upon any key or data obtained from this device.
- The RSA public key component of a public/private key pair that exists within the device. These public/private key pairs are installed during manufacture. Typically, an exported public key is used by the host to encipher the symmetric key.
See section Default Keys and Security Item loaded during manufacture for the default names and the description of the keys installed during manufacture. These names are defined to ensure multi-vendor applications can be developed.
The KeyManagement.GetKeyDetail command can be used to determine the valid uses for the exported public key.
Command Message
Completion Message
Event Messages
None11.2.8 - KeyManagement.GenerateRSAKeyPair
This command will generate a new RSA key pair. The public key generated as a result of this command can subsequently be obtained by calling KeyManagement.ExportRSADeviceSignedItem. The newly generated key pair can only be used for the use defined in the use flag. This flag defines the use of the private key; its public key can only be used for the inverse function.
Command Message
Completion Message
Event Messages
None11.2.9 - KeyManagement.ExportRSADeviceSignedItem
This command is used to export data elements from the device that have been signed by a private key within the device. This command allows an application to define which of the following data items are to be exported.
- The Security Item which uniquely identifies the device. This value may be used to uniquely identify a device and therefore confer trust upon any key or data obtained from this device.
- The RSA public key component of a public/private key pair that exists within the device.
Command Message
Completion Message
Event Messages
None11.2.10 - KeyManagement.GetCertificate
This command is used to read out the encryptor's certificate, which has been signed by the trusted Certificate Authority and is sent to the host. This command only needs to be called once if no new Certificate Authority has taken over. The output of this command will specify in the PKCS#7 (See [Ref. keymanagement-1]) message the resulting Primary or Secondary certificate.
Command Message
Completion Message
Event Messages
None11.2.11 - KeyManagement.ReplaceCertificate
This command is used to replace the existing primary or secondary Certificate Authority certificate already loaded into the KeyManagement. This operation must be done by an Initial Certificate Authority or by a Sub-Certificate Authority. These operations will replace either the primary or secondary Certificate Authority public verification key inside of the KeyManagement. After this command is complete, the application should send the KeyManagement.LoadCertificate and KeyManagement.GetCertificate commands to ensure that the new HOST and the encryptor have all the information required to perform the remote key loading process.
Command Message
Completion Message
Event Messages
None11.2.12 - KeyManagement.StartKeyExchange
This command is used to start communication with the host, including transferring the host's Key Transport Key, replacing the Host certificate, and requesting initialization remotely. This output value is returned to the host and is used in the
to verify that the encryptor is talking to the proper host.
The KeyManagement.ImportKey command end the key exchange process.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None11.2.13 - KeyManagement.GenerateKCV
This command returns the Key Check Value (KCV) for the specified key.
Command Message
Completion Message
Event Messages
None11.2.14 - KeyManagement.LoadCertificate
This command is used to load a host certificate to make remote key loading possible. This command can be used to load a host certificate when there is not already one present in the encryptor as well as replace the existing host certificate with a new host certificate. The type of certificate (Primary or Secondary) to be loaded will be embedded within the actual certificate structure.
Command Message
Completion Message
Event Messages
None11.2.15 - KeyManagement.StartAuthenticate
For commands which may require authentication data, this command retrieves the data to be signed. If this command returns data to be signed the signed data must be included in the authenticate property of the command.
If authentication data is required but not provided, the command will complete with completionCode authorizationRequired.
Command Message
Completion Message
Event Messages
None11.2.16 - KeyManagement.ImportKeyToken
This command is used to load a DES (56, 112, 168) or AES (128, 192, 256) key included in a key transport token. The Key Transport Key should be destroyed if the entire process is not completed. In addition, a new Key Transport Key should be generated each time this protocol is executed. This command ends the Key Exchange process.
Command Message
Completion Message
Event Messages
None11.2.17 - KeyManagement.ImportEmvPublicKey
The Certification Authority and the Chip Card RSA public keys needed for EMV are loaded or deleted in/from the encryption module. This command is similar to the KeyManagement.ImportKey, but it is specifically designed to address the key formats and security features defined by EMV. Mainly the extensive use of "signed certificate" or "EMV certificate" (which is a compromise between signature and a pure certificate) to provide the public key is taken in account. The Service is responsible for all EMV public key import validation. Once loaded, the Service is not responsible for key/certificate expiry, this is an application responsibility.
Command Message
Completion Message
Event Messages
None11.3 - Event Messages
11.3.1 - KeyManagement.DUKPTKSNEvent
This event sends the DUKPT KSN of the key used in the command. The receiving TRSM uses this to derive the key from the BDK.
Event Message
11.4 - Unsolicited Messages
11.4.1 - KeyManagement.InitializedEvent
This is generated when a KeyManagement.Initialization command completed successfully.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
11.4.2 - KeyManagement.IllegalKeyAccessEvent
This event specifies that an error occurred accessing an encryption key. Possible situations for generating this event are listed in the description of the errorCode property.
Unsolicited Message
11.4.3 - KeyManagement.CertificateChangeEvent
This event indicates that the certificate module state has changed from Primary to Secondary.
Unsolicited Message
12 - Crypto Interface
This chapter defines the Crypto interface functionality and messages.
12.1 - General Information
12.1.1 - References
12.2 - Command Messages
12.2.1 - Crypto.GenerateRandom
This command is used to generate a random number.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None12.2.2 - Crypto.CryptoData
This command is used to encrypt or decrypt data. The key Mode of Use and optional modeOfUse property determines whether encryption or decryption will be performed.
If padding is required, the service will add it using the padding parameter. Clients can use an alternative padding method by pre-formatting the data and combining this with the standard padding method.
For symmetric key encryption using the CBC or CFB cryptoMethod, the Initialization Vector (iv) can be provided as input to this command, or a pre-imported IV referenced by name can be used. The ivKey and iv are both optional properties.
Command Message
Completion Message
Event Messages
12.2.3 - Crypto.GenerateAuthentication
This command is used to generate a Message Authentication Code (MAC) or Signature.
If padding is required, the service will add it using the padding parameter. Clients can use an alternative padding method by pre-formatting the data and combining this with the standard padding method.
For MAC generation using the CBC or CFB cryptoMethod, the Initialization Vector (iv) can be provided as input to this command, or a pre-imported IV referenced by name can be used. The ivKey and iv are both optional properties.
Command Message
Completion Message
Event Messages
12.2.4 - Crypto.VerifyAuthentication
This command is used for Message Authentication Code (MAC) and signature verification.
The authentication data is verified using the specified verification attributes. The supported verification attributes are defined in verifyAttributes.
If padding is required, the service will add it using the padding parameter. Clients can use an alternative padding method by pre-formatting the data and combining this with the standard padding method.
For MAC verification using the CBC or CFB cryptoMethod, the Initialization Vector (iv) can be provided as input to this command, or a pre-imported IV referenced by name can be used. The ivKey and iv are both optional properties.
Command Message
Completion Message
Event Messages
13 - Keyboard Interface
This chapter defines the Keyboard interface functionality and messages.
This section describes the general interface for the following functions:
-
Entering Personal Identification Numbers (PINs)
-
Clear text data handling
-
Function key handling
If the device has local display capability, display handling should be handled using the TextTerminal interface. The adoption of this specification does not imply the adoption of a specific security standard.
-
Only numeric PIN pads are handled in this specification.
13.1 - General Information
13.1.1 - Encrypting Touch Screen (ETS)
An encrypting touch screen device is a touch screen securely attached to a cryptographic device. It can be used as an alternative to an encrypting pin pad (EPP). It supports key management, encryption and decryption.
It is assumed that the ETS is a combined device. It overlays a display monitor which is used to display lead-through for a transaction. It is assumed that the display monitor is part of the operating system desktop, and can be the primary monitor or any other monitor on the desktop. E.g. the following diagram shows 2 monitors extended across the desktop, with monitor 1 being the primary monitor and the ETS being overlaid on monitor 2 whose origin is (-1680.0).
The touch screen can optionally be used as a “mouse” for application purposes, while PIN operations are not in progress or optionally when non-secure PIN commands are in progress.
The CEN interface supports two types of ETS:
- Those which activate touch areas defined by the application.
- Those which activate a random variation of touch areas defined by the application.
The Service Provider, when reporting its capabilities, reports the absolute position of the ETS in desktop coordinates. This allows the application to locate the ETS device in a multi-monitor system and relate it to a monitor on the desktop.
At any point in time, a single touch area of the ETS can operate in one of 4 modes:
-
Mouse mode - a "touch" simulates a mouse click. This mode is optional. This may not be supported by some ETS devices. Configuration of the click is vendor specific. This is also the mode that, if supported, is active when none of the other modes are active.
-
Data mode - a "touch" maps to a key and the value of the key is returned in an event (as in clear numeric entry using Keyboard.DataEntry).
-
PIN mode - a "touch" maps to a key and the value of the key is returned in an event only if the key pressed is not zero through nine (as in PIN entry using Keyboard.PinEntry).
-
Secure mode - a "touch" maps to a key and the value of the key is returned in an event only if the key pressed is not zero through nine and not a through f (as in key entry using Keyboard.SecureKeyEntry).
The following concepts are introduced to define the relationship between the monitor and the ETS:
-
Touch Key – an area of the monitor which reacts to touch in Data, PIN and Secure modes.
-
Touch Frame – an area of the monitor onto which Touch Keys can be placed. There can be one or more Touch Frames. There may be just one Touch Frame which covers the whole monitor. Areas within a Touch Frame, not defined as a Touch Key, do not react to touch. Generally in PIN and Secure modes, there would be only one Touch Frame covering the whole monitor. An empty Touch Frame disables that part of the monitor.
-
Mouse area – an area outside of all Touch Frames in which touches behave like a mouse.
-
Thus Data, PIN and Secure modes operate in a single Touch Frame or multiple Touch Frames. Mouse mode operates outside a Touch Frame, and is optional.
Note that there is a perceived risk in separating the drawing functionality from the touch functionality, but this type of risk is present in today’s keyboard based systems. e.g. An application can draw on a monitor to prompt the user to enter a PIN and then enables the EPP for clear data entry. So the risk is no different than with an EPP – the application has to be trusted.
Depending upon the type of device, the application must then either inform the Service Provider as to the active key positions in the form of Touch Frames and Touch Keys using the Keyboard.DefineLayout command, or obtain them from the Service Provider using the Keyboard.GetLayout command. This collection is now referred to as a "Touch Keyboard definition".
The application then uses the following commands to enable the touch keyboard definition on the ETS device:
These commands are referred to as "keyboard entry commands" throughout the remainder of this document.
PCI compliance means that Keyboard.PinEntry and Keyboard.SecureKeyEntry can only be used with a single Touch Frame that covers the entire monitor. i.e. Mouse mode cannot be mixed with either PIN or Secure mode. If a Touch Key (or areas) is defined for a key value and that key value is not subsequently specified as active in a Keyboard.PinEntry, Keyboard.DataEntry or Keyboard.SecureKeyEntry command, then the Touch Key is made inactive.
Layouts defined with the Keyboard.DefineLayout command are persistent.
Example 1 – this screen only uses Data mode – the entire screen is a Touch Frame. Mouse mode is not used.
Example 2 – this shows a monitor with two Touch Frames and 14 Touch Keys. The space within the Touch Frames not defined by a Touch Key are inactive (do not respond to touch). All areas outside a Touch Frame operate in Mouse mode. This example shows two Mouse mode "keys". e.g. "Button", HTML "BUTTON" or a custom control. Other touches in Mouse mode are normally dealt with by the application event engine. However, this can be restricted – see example 3.
Example 3 - this screen uses Mouse and Data modes – Mouse mode is used only in a restricted area. The touch keyboard definition has 3 frames. Frame 1 has no Touch Keys. Frame 2 has 2 Touch Keys; Frame 3 has 12 Touch Keys.
13.1.2 - Layout
A Physical Frame can only contain Physical Keys. It can contain Physical Keys positioned on the edge of the screen (for example, FDKs) or Physical Keys not positioned on the edge of the screen (for example EPP) but cannot contain both. An ETS can only contain Touch Keys. To determine the frame type, frame xSize and frame ySize should be checked.
The following tables define the possible size and position values that apply to each frame type.
Frame size and position:
| Frame Type | Frame xSize | Frame ySize | Frame xPos | Frame yPos |
|---|---|---|---|---|
| Physical Keys on EPP | 0 | 0 | 0 | 0 |
| Touch Keys on ETS | > 0 | > 0 | >= 0 | >= 0 |
| Physical Keys on Left Boundary of Screen | 0 | > 0 | 0 | 0 |
| Physical Keys on Right Boundary of Screen | 0 | > 0 | > 0 | 0 |
| Physical Keys on Top Boundary of Screen | > 0 | 0 | 0 | 0 |
| Physical Keys on Bottom Boundary of Screen | > 0 | 0 | 0 | > 0 |
Key size and position:
| Frame Type | Key xSize | Key ySize | Key xPos | Key yPos |
|---|---|---|---|---|
| Physical Keys on EPP | 1 to 10001 | 1 to 10002 | 0 to 9993 | 0 to 9994 |
| Touch Keys on ETS | 0 to (Frame xSize - Key xPos) | 0 to (Frame ySize - Key yPos) | 0 to Frame xSize | 0 to Frame ySize |
| Physical Keys on Left Boundary of Screen | 0 | 0 to (Frame ySize - Key yPos) | 0 | 0 to Frame ySize |
| Physical Keys on Right Boundary of Screen | 0 | 0 to (Frame ySize - Key yPos) | Frame xSize | 0 to Frame ySize |
| Physical Keys on Top Boundary of Screen | 0 to (Frame xSize - Key xPos) | 0 | 0 to Frame xSize | 0 |
| Physical Keys on Bottom Boundary of Screen | 0 to (Frame xSize - Key xPos) | 0 | 0 to Frame xSize | Frame ySize |
1: 1 is the smallest possible size and 1000 is the full width of the frame
2: 1 is the smallest possible size and 1000 is the full height of the frame
3: 0 is the left edge and 999 is the right edge of the frame
4: 0 is the top edge and 999 is the bottom edge of the frame
The following diagram shows an example configuration consisting of an EPP and Physical FDKs to the left and right of the screen. 3 frames contain the Physical Keys.
13.2 - Command Messages
13.2.1 - Keyboard.GetLayout
This command allows an application to retrieve layout information for any device. Either one layout or all defined layouts can be retrieved with a single request of this command.
There can be a layout for each of the different types of keyboard entry modes, if the vendor and the hardware support these different methods. The types of keyboard entry modes are:
- Data Entry mode which corresponds to the Keyboard.DataEntry command.
- PIN Entry mode which corresponds to the Keyboard.PinEntry command.
- Secure Key Entry mode which corresponds to the Keyboard.SecureKeyEntry command.
The layouts can be preloaded into the device, if the device supports this, or a single layout can be loaded into the device immediately prior to the keyboard command being requested.
Command Message
Completion Message
Event Messages
None13.2.2 - Keyboard.PinEntry
This function stores the PIN entry via the device. From the point this function is invoked, PIN digit entries are not passed to the application. For each PIN digit, or any other active key entered, a notification Keyboard.KeyEvent is sent in order to allow an application to perform the appropriate display action (i.e. when the PIN pad has no integrated display). The application is not informed of the value entered. The event only informs that a key has been depressed.
The Keyboard.EnterDataEvent will be generated when the Keyboard is ready for the user to start entering data.
Some devices do not inform the application as each PIN digit is entered, but locally process the PIN entry based upon minimum PIN length and maximum PIN length input parameters.
When the maximum number of PIN digits is entered and the flag autoEnd is true, or a terminating key is pressed
after the minimum number of PIN digits is entered, the command completes. If the
Terminating Function Descriptor Keys (FDKs) can have the functionality of
If maxLen is zero, the Service Provider does not terminate the command unless the application sets terminate property. In the event that terminate property is set to false all active keys and maxLen is zero, the command will not terminate and the application must issue a Common.Cancel command.
If active the 'cancel' and 'clear' keys will cause the PIN buffer to be cleared. The backspace key will cause the last key in the PIN buffer to be removed.
Terminating keys have to be active keys to operate.
If this command is cancelled by a Common.Cancel command the PIN buffer is not cleared.
If maxLen has been met and autoEnd is set to false, then all numeric keys will automatically be disabled. If the 'clear' or 'backspace' key is pressed to reduce the number of entered keys, the numeric keys will be re-enabled.
If the 'enter' key (or FDK representing the 'enter' key - note that the association of an FDK to enter functionality is vendor specific) is pressed prior to minLen being met, then the enter key or FDK is ignored. In some cases the device cannot ignore the enter key then the command will complete normally. To handle these types of devices the application should use the output parameter digits property to check that sufficient digits have been entered. The application should then get the user to re-enter their PIN with the correct number of digits.
If the application makes a call to PinPad.GetPinblock or a local verification command without the minimum PIN digits having been entered, either the command will fail or the PIN verification will fail.
It is the responsibility of the application to identify the mapping between the FDK code and the physical location of the FDK.
Command Message
Completion Message
Event Messages
13.2.3 - Keyboard.DataEntry
This function is used to return keystrokes entered by the user. It will automatically set the PIN pad to echo characters on the display if there is a display. For each keystroke a notification Keyboard.KeyEvent is sent in order to allow an application to perform the appropriate display action (i.e. when the PIN pad has no integrated display).
The Keyboard.EnterDataEvent will be generated when the PIN pad is ready for the user to start entering data.
When the maximum number of digits is entered and the autoEnd property is true, or a terminate key is pressed
after the minimum number of digits is entered, the command completes. If the
Terminating Function Descriptor Keys(FDKs) can have the functionality of
If maxLen is zero, the Service Provider does not terminate the command unless the application sets terminate property. In the event that terminate property is set to false all active keys and maxLen is zero, the command will not terminate and the application must issue a Common.Cancel command.
If maxLen has been met and autoEnd is set to False, then all keys or FDKs that add data to the contents of the output parameter will automatically be disabled. If the CLEAR or BACKSPACE key is pressed to reduce the number of entered keys below maxLen, the same keys will be re-enabled.
Where applications want direct control of the data entry and the key interpretation, maxLen can be set to zero allowing the application to provide tracking and counting of key presses until a terminate key is pressed or Common.Cancel has been issued.
The following keys may affect the contents of the output parameter but are not returned in it:
- 'enter'
- 'cancel'
- 'clear'
- 'backspace'
The 'cancel' and 'clear' keys will cause the output buffer to be cleared. The 'backspace' key will cause the last key in the buffer to be removed.
Terminating keys have to be active keys to operate.
It is the responsibility of the application to identify the mapping between the FDK code and the physical location of the FDK.
Command Message
Completion Message
Event Messages
13.2.4 - Keyboard.Reset
Sends a service reset to the Service Provider.
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
None13.2.5 - Keyboard.SecureKeyEntry
This command allows a full length symmetric encryption key part to be entered directly into the device without being exposed outside of the device. From the point this function is invoked, encryption key digits ('zero' to 'nine' and 'a' to 'f') are not passed to the application. For each encryption key digit, or any other active key entered (except for 'shift'), a notification Keyboard.KeyEvent is sent in order to allow an application to perform the appropriate display action (i.e. when the device has no integrated display). When an encryption key digit is entered the application is not informed of the value entered, instead zero is returned.
The Keyboard.EnterDataEvent will be generated when the device is ready for the user to start entering data.
The keys that can be enabled by this command are defined by the Keyboard.GetLayout command. Function keys which are not associated with an encryption key digit may be enabled but will not contribute to the secure entry buffer (unless they are Cancel, Clear or Backspace) and will not count towards the length of the key entry. The Cancel and Clear keys will cause the encryption key buffer to be cleared. The Backspace key will cause the last encryption key digit in the encryption key buffer to be removed.
If autoEnd is true the command will automatically complete when the required number of encryption key digits have been added to the buffer.
If autoEnd is false then the command will not automatically complete and Enter, Cancel or any terminating key must be pressed. When keyLen hex encryption key digits have been entered then all encryption key digits keys are disabled. If the Clear or Backspace key is pressed to reduce the number of entered encryption key digits below keyLen, the same keys will be reenabled.
Terminating keys have to be active keys to operate.
If a Function Descriptor Key (FDK) is associated with Enter, Cancel, Clear or Backspace then the FDK must be activated to operate. The Enter and Cancel FDKs must also be marked as a terminator if they are to terminate entry. These FDKs are reported as normal FDKs within the Keyboard.KeyEvent, applications must be aware of those FDKs associated with Cancel, Clear, Backspace and Enter and handle any user interaction as required. For example, if the 'fdk01' is associated with Clear, then the application must include the 'fdk01' FDK code in the activeKeys parameter (if the clear functionality is required). In addition when this FDK is pressed the Keyboard.KeyEvent will contain the 'fdk01' mask value in the digit property. The application must update the user interface to reflect the effect of the clear on the encryption key digits entered so far.
On some devices that are configured as all the function keys on the device will be associated with hex digits and there may be no FDKs available either. On these devices there may be no way to correct mistakes or cancel the key encryption entry before all the encryption key digits are entered, so the application must set the autoEnd flag to true and wait for the command to auto-complete. Applications should check the KCV to avoid storing an incorrect key component.
Encryption key parts entered with this command are stored through either the KeyManagement.ImportKey. Each key part can only be stored once after which the secure key buffer will be cleared automatically.
Command Message
Completion Message
Event Messages
13.2.6 - Keyboard.KeypressBeep
This command is used to enable or disable the device from emitting a beep tone on subsequent key presses of active or inactive keys. This command is valid only on devices which have the capability to support application control of automatic beeping. See autoBeep capability for information.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None13.2.7 - Keyboard.DefineLayout
This command allows an application to configure a layout for any device. One or more layouts can be defined with a single request of this command.
There can be a layout for each of the different types of keyboard entry modes, if the vendor and the hardware supports these different methods.
The types of keyboard entry modes are:
- Mouse mode.
- Data mode which corresponds to the Keyboard.DataEntry command.
- PIN mode which corresponds to the Keyboard.PinEntry command.
- Secure mode which corresponds to the Keyboard.SecureKeyEntry command.
One or more layouts can be preloaded into the device, if the device supports this, or a single layout can be loaded into the device immediately prior to the keyboard command being requested.
If a Keyboard.DataEntry, Keyboard.PinEntry, or Keyboard.SecureKeyEntry command is already in progress (or queued), then this command is rejected with a command result of sequenceError.
It is recommended that the Keyboard.GetLayout command is used before this command to check for the presence of frames containing Physical Keys (FKs or FDKs). If a layout includes one or more frames containing Physical Keys, the number of frames containing Physical Keys, the size and position of the frame, and the size, position and order of the keys contained in the frame, cannot be changed.
Layouts defined with this command are persistent.
Command Message
Completion Message
Event Messages
None13.3 - Event Messages
13.3.1 - Keyboard.KeyEvent
This event specifies that any active key has been pressed at the PIN pad. It is used if the device has no internal display unit and the application has to manage the display of the entered digits. It is the responsibility of the application to identify the mapping between the FDK code and the physical location of the FDK.
Event Message
13.3.2 - Keyboard.EnterDataEvent
This mandatory event notifies the application when the device is ready for the user to start entering data.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
13.3.3 - Keyboard.LayoutEvent
This event sends the layout for a specific keyboard entry mode if the layout has changed since it was loaded (i.e. if a float action is being used).
Event Message
14 - PinPad Interface
This chapter defines the PinPad interface functionality and messages.
This section describes the general interface for the following functions:
- Administration of encryption devices
- PIN verification
- PIN block generation (encrypted PIN)
- PIN presentation to chipcard
- EMV 4.0 PIN blocks, EMV 4.0 public key loading, static and dynamic data verification
14.1 - General Information
14.1.1 - References
14.2 - Command Messages
14.2.1 - PinPad.GetQueryPCIPTSDeviceId
This command is used to report information in order to verify the PCI Security Standards Council PIN transaction security (PTS) certification held by the PIN device. The command provides detailed information in order to verify the certification level of the device. Support of this command by the Service does not imply in anyway the certification level achieved by the device.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None14.2.2 - PinPad.LocalDES
The PIN, which was entered with the GetPin command, is combined with the requisite data specified by the DES validation algorithm and locally verified for correctness. The result of the verification is returned to the application. This command will clear the PIN unless the application has requested that the PIN be maintained through the PinPad.MaintainPin command.
Command Message
Completion Message
Event Messages
None14.2.3 - PinPad.LocalVisa
The PIN, which was entered with the GetPin command, is combined with the requisite data specified by the VISA validation algorithm and locally verified for correctness. The result of the verification is returned to the application. This command will clear the PIN unless the application has requested that the PIN be maintained using the PinPad.MaintainPin command.
Command Message
Completion Message
Event Messages
None14.2.4 - PinPad.PresentIDC
The PIN, which was entered with the GetPin command, is combined with the requisite data specified by the IDC presentation algorithm and presented to the smartcard contained in the ID card unit. The result of the presentation is returned to the application.
This command will clear the PIN unless the application has requested that the PIN be maintained using the PinPad.MaintainPin command.
Command Message
Completion Message
Event Messages
None14.2.5 - PinPad.Reset
Sends a service reset to the Service.
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
None14.2.6 - PinPad.MaintainPin
This command is used to control if the PIN is maintained after a PIN processing command for subsequent use by other PIN processing commands. This command is also used to clear the PIN buffer when the PIN is no longer required.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None14.2.7 - PinPad.SetPinBlockData
This function should be used for devices which need to know the data for the PIN block before the PIN is entered by the user. Keyboard.GetPin and PinPad.GetPinBlock should be called after this command. For all other devices unsupportedCommand will be returned
If this command is required and it is not called, the Keyboard.GetPin command will fail with the generic error sequenceError.
If the input parameters passed to this command and PinPad.GetPinBlock are not identical, the PinPad.GetPinBlock command will fail with the generic error invalidData.
The data associated with this command will be cleared on a PinPad.GetPinBlock command.
Command Message
Completion Message
Event Messages
None14.2.8 - PinPad.GetPinBlock
This function takes the account information and a PIN entered by the user to build a formatted PIN. Encrypting this formatted PIN once or twice returns a PIN block which can be written on a magnetic card or sent to a host. The PIN block can be calculated using one of the algorithms specified in the pinBlockAttributes capability. This command will clear the PIN unless the application has requested that the PIN be maintained through the PinPad.MaintainPin command.
Command Message
Completion Message
Event Messages
15 - Printer Interface
This chapter defines the Printer interface functionality and messages.
This specification describes the functionality of the services provided by banking printers and scanning devices under XFS4IoT, focusing on the following areas:
- application programming for printing
- print document definition
- scanning images
The XFS4IoT Printer interface is implemented around a forms model which also standardizes the basic document definition.
15.1 - General Information
15.1.1 - Banking Printer Types
The XFS4IoT Printer service defines and supports five types of banking printers through a common interface:
-
Receipt Printer
The receipt printer is used to print cut sheet documents. It may or may not require insert or eject operations, and often includes an operator identification device, e.g. Teller A and Teller B lights, for shared operation. -
Journal Printer
The journal is a continuous form device used to record a hardcopy audit trail of transactions, and for certain report printing requirements. -
Passbook Printer
The passbook device is physically and functionally the most complex printer. The XFS4IoT definition supports automatic positioning of the book, as well as read/write capability for an optional integrated magnetic stripe. The implementation also manages the book geometry - i.e. the margins and centerfolds - presenting the simplest possible application interface while delivering the full range of functionality.Some passbook devices also support the dispensing of new passbooks from up to four passbook paper sources (upper, aux, aux2, lower). Some passbook devices may also be able to place a full passbook in a parking station, print the new passbook and return both to the customer. Passbooks can only be dispensed or moved from the parking station if there is no other media in the print position or in the entry/exit slot.
-
Document Printer
Document printing is similar to receipt printing - a set of fields are positioned on one or more inserted sheets of paper - but the focus is on full-size forms. It should be noted that the XFS environment supports the printing of text and graphic fields from the application. The electronic printing of the form image (the template portion of the form which is usually pre-printed with dot-matrix style printers) may also be printed by the application. -
Scanner Printer
The scanner printer is a device incorporating both the capabilities to scan inserted documents and optionally to print on them. These devices may have more than one area where documents may be retained.
Additional hardware components, like scanners, stripe readers, OCR readers, and stamps, normally attached directly to the printer are also controlled through this interface. Additionally, the Printer class interface can also be used for devices that are capable of scanning without necessarily printing.
The specification refers to the terms paper and media. When the term paper is used this refers to paper that is situated in a paper supply attached to the device. The term media is used for media that is inserted by the customer (e.g., material that is scanned) or that is issued to the customer (e.g., a receipt or statement). Receipt, document and passbook printers with white passbook dispensing capability have both. As soon as the paper gets printed it becomes media. Scanners only have media. The term media does not apply to journal printers. When paper is in the print position it is classified as media, on some printers that maintain paper under the print head there will always be both media and paper.
15.1.2 - Forms Model
The XFS4IoT printing service functionality is based on a “forms” model for printing. Banking documents are represented as a series of text and/or graphic fields output from the application and positioned on the document by the XFS4IoT printing system.
The form is an object which includes the positioning and presentation information for each of the fields in the document. The application selects a form and supplies only the field data and the control parameters to fully define the print document.
The form objects are owned and managed by the XFS4IoT printing service. To optimize maintainability of the system, the application can query the service for the list of fields required to print a given form. Through this mechanism, it is not necessary to duplicate the field contents of forms in application authoring data. The figure below outlines the printing process from the application's view.
The XFS4IoT implementation recognizes that the form object must be supported by job-specific data to fully address printing requirements. As an example, a form defining a passbook print line will need to have its origin defined externally in order to be reused for different passbook lines. These job specific parameters are supplied on the Printer.PrintForm command.
In some cases, the application wants to print a block of data without considering it as a series of separate fields. One example is a line of journal data, fully formatted by the application. This can be handled by defining a one field form, or by use of the Printer.PrintRaw command.
The document definition under XFS4IoT printing is standardized to provide portability across vendor implementations. The standard has been defined at the source language level for the document definition, allowing vendor differences at the runtime level to manage implementation specific dependencies, providing several areas where vendors can provide value-added extensions. As an example, a vendor providing a graphical form definition tool can produce the field definition object format directly. The XFS4IoT requirements for portability are:
- A vendor must be able to export print format in the standardized field definition source format for portability to other systems.
- A vendor must be able to import document formats produced on other systems in the standardized field definition source format.
- A vendor can extend the field definition source language, but any verbs included in the standard must be implemented strictly as defined by the standard. Import and export facilities must be tolerant of source language extensions, reporting but ignoring the exceptions.
15.1.3 - Command Overview
The basic operation of the print devices is managed using the two primary commands:
- Printer.GetQueryForm
This command retrieves the form header information, and the list of fields. - Printer.PrintForm
This command includes as parameter data the name of the form to select and the required field data values.
This approach combines in the most efficient manner the four logical steps required to print a form:
- Selecting a document form object.
- Querying the service for the list of fields.
- Supplying the data for each field.
- Issuing the print command.
By using Printer.GetQueryForm to retrieve the list of field names, it is possible for an application to assemble the required set of fields for a form before locking the service. This minimizes the time that each application request ties up the service. Using Printer.GetQueryForm, it is also possible to query the attributes of a field. This command is generally not required for most applications.
The combination of form selection, field value presentation and the print action make it possible to express a complete print operation with Printer.PrintForm command. Where these multiple print functions represent a series of passbook lines (using the INDEX capability in the field definition), the Printer.PrintForm command provides support for management of the print line number. Note that if a form contains a tabular field (i.e. one with a non-zero INDEX value), and data is not supplied for some of the lines in the “table”, then those lines are left blank.
For printers with the capability to read from a passbook (OCR, MICR and/or magnetic stripe), the data is read with the Printer.ReadForm command. The data is written using the Printer.PrintForm command. Since these devices are usable only for passbook operations, they are not defined as separate logical devices.
Finally, the Printer.PrintNative command can be used to print data that contains a complete print job in the native printer language. This data will have been created using the native Operating System API (for example, Windows GDI).
15.1.4 - Form, Sub-Form, Field, Frame, Table and Media Definitions
This section outlines the format of the definitions of forms, the fields within them, optional tables and fields within the form, and the media on which they are printed.
15.1.4.1 - Definition Syntax
The syntactic rules for form, field and media definitions are as follows:
- White space
Space, Tab - Line continuation
Backslash (\) - Line termination
CR, LF, CR/LF; line termination ends a "keyword section" (a keyword and its value[s]). - Keywords
Must be all upper case. - Names
Field, media and font names are case sensitive. - Strings
All strings must be enclosed in double quote characters ("). Standard C escape sequences are allowed. - Comments
Start with two forward slashes (//), end at line termination
Other Notes:
- The values of a keyword are separated by commas.
- If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.
- Values that are character strings are marked with * in the definitions below and must be quoted as specified above.
- The order of attributes within the forms is not mandatory and the attributes may be defined in any order.
- A form and its optional subforms that have multiple XFSFIELDs with the same fieldname are invalid. The formInvalid error will be returned if specified in the input to the command.
- A form that has multiple XFSSUBFORMs with the same subform name is invalid. The formInvalid error will be returned if specified in the input to the command.
- A form and its optional subforms that have multiple XFSFRAMEs with the same frame name are invalid. The formInvalid error will be returned if specified in the input to the command.
- All definitions must be encoded in UTF-8. Keywords are restricted to an internal representation of ISO 646 (ANSI) characters. Values for the INITIALVALUE and FORMAT keywords can have UNICODE values.
15.1.4.2 - Form and Media Measurements
The UNIT keyword sections of the form and media definitions specify the base horizontal and vertical resolution as follows:
- The base value specifies the base unit of measurement.
- The x and y values specify the horizontal and vertical resolution as fractions of the base value (e.g. an x value of 10 and a base value of MM means that the base horizontal resolution is 0.1 mm).
The base resolutions thus defined by the UNIT keyword section of the XFSFORM definition are used as the units of the form definition keyword sections:
- SIZE (width and height values)
- ALIGNMENT (xoffset and yoffset values)
and of the sub-form definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
and of the field definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
- INDEX (xoffset and yoffset values)
and of the frame definition keyword sections:
- POSITION (x and y values)
- SIZE (width and height values)
- REPEATONX (xoffset value)
- REPEATONY (yoffset value)
The base resolutions thus defined by the UNIT keyword section of the XFSMEDIA definition are used as the units of the media definition keyword sections:
- SIZE (width and height values)
- PRINTAREA (x, y, width and height values)
- RESTRICTED (x, y, width and height values)
NOTE: The origin for coordinate based systems is (0,0). The origin for row/column based systems can be (0,0) or (1,1) and must be configurable within the service.
15.1.4.3 - Form Definition
Attributes are not required in any mandatory order within a Form definition.
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| XFSFORM | 🗸 | formname* | ||
| BEGIN | 🗸 | |||
| UNIT | 🗸 | base,x,y | base - Base resolution unit for form definition: MM, INCH or ROWCOLUMN x - Horizontal base unit fraction y - Vertical base unit fraction |
|
| SIZE | 🗸 | width,height | width - Width of form height - Height of form |
|
| ALIGNMENT | alignment,xoffset,yoffset | alignment - Alignment of the form on the physical media (TOPLEFT (default), TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT). This option allows the positioning of a form onto a physical page relative to any combination of the edges of the physical media, to support the variations in how devices sense the edge of page for positioning purposes. xoffset - Horizontal offset relative to the horizontal alignment specified by alignment. Always specified as a positive value (i.e. if aligned to the right side of the media, means offset the form to the left). (default = 0) yoffset - Vertical offset relative to the vertical alignment specified by alignment. Always specified as a positive value (i.e. if aligned to the bottom of the media, means offset the form upward). (default = 0) |
||
| ORIENTATION | type | Orientation of the form: PORTRAIT (default) or LANDSCAPE | ||
| SKEW | skewfactor | Maximum skew factor in degrees (default = 0) | ||
| VERSION | major,minor,date*,author* | major - Major version number minor - Minor version number date - Creation/modification date author - Author of the form |
||
| CPI | cpi | Characters per inch. This value specifies the default CPI within the form. When the ROWCOLUMN unit is used, the form CPI and LPI are used to calculate the position and size of all fields within a form, irrespective of the CPI and LPI of the fields themselves. | ||
| LPI | lpi | Lines per inch. This value specifies the default LPI within the form. When the ROWCOLUMN unit is used, the form CPI and LPI are used to calculate the position and size of all fields within a form, irrespective of the CPI and LPI of the fields themselves. | ||
| POINTSIZE | pointsize | This value specifies the default POINTSIZE within the form. | ||
| COPYRIGHT | copyright* | Copyright entry | ||
| TITLE | title* | Title of form | ||
| COMMENT | comment* | Comment section | ||
| USERPROMPT | prompt* | Prompt string for user interaction | ||
| [XFSFIELD BEGIN ... END] |
fieldname* | One field definition for each field in the form. The fieldname within a form and its optional subforms must be unique. | ||
| [XFSFRAME BEGIN ... END] |
framename* | One frame definition for each frame in the form. The framename within a form and its optional subforms must be unique. | ||
| [XFSSUBFORM BEGIN ... END] |
subformname* | One subform definition for each subform in the form. The subformname within a form must be unique. | ||
| END | 🗸 |
15.1.4.4 - SubForm Definition
Attributes are not required in any mandatory order within a SubForm definition.
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| XFSSUBFORM | 🗸 | subformname* | ||
| BEGIN | 🗸 | |||
| POSITION | 🗸 | X,Y or X,Y,Z | X - Horizontal position (relative to left side of form) Y or Y,Z - Vertical position (relative to top of form). Format Y,Z is used to indicate vertical positioning relative to top of form when top of form is other than 1st page of form, where Z indicates page number (relative to 0) and Y indicates base resolution units relative to top of the form page number (as indicated by Z). Format Y is used to indicate vertical positioning relative to top of the 1st form page. |
|
| SIZE | 🗸 | width,height | width - Width of subform. Width must not exceed width of form. height - Height of subform. Height must not exceed height of form. |
|
| [XFSFIELD BEGIN ... END] |
fieldname* | One field definition for each field in the form. The fieldname within a form and its optional subforms must be unique. | ||
| [XFSFRAME BEGIN ... END] |
framename* | One frame definition for each frame in the form. The framename within a form and its optional subforms must be unique. | ||
| END | 🗸 |
The XFSSUBFORM definition provides a means to isolate a selected area of a form where the user may want to have a select group of fields, frames, and/or running headers and footers. All field and frame definitions within a subform are relative to the POSITION of the subform. A form definition with an imbedded subform will have a series of statements illustrated as follows:
XFSFORM
BEGIN
*
*
XFSSUBFORM
BEGIN
XFSFIELD
BEGIN
*
*
END
XFSFIELD
BEGIN
*
*
END
END
END
15.1.4.5 - Field Definition
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| XFSFIELD | 🗸 | fieldname* | The fieldname within a form and its optional subforms must be unique. | |
| BEGIN | 🗸 | |||
| POSITION | 🗸 | X,Y or X,Y,Z | X - Horizontal position (relative to left side of form/subform). Y or Y,Z - Vertical position (relative to top of form/subform). Format Y,Z is used to indicate vertical positioning relative to top of form/subform when top of form/subform is other than 1st page of form/subform, where Z indicates page number (relative to 0) and Y indicates base resolution units relative to top of the form/subform page number (as indicated by Z). Format Y is used to indicate vertical positioning relative to top of the 1st form/subform. |
|
| FOLLOWS | fieldname* | Print this field directly following the field with the name fieldname; positioning information is ignored. See the description of Printer.PrintForm. If FOLLOWS is omitted, then fields are printed in the order that they appear in the form definition. | ||
| HEADER | N, N-N or ALL | This field is either a form or subform header field. N represents a form/subform page number (relative to 0) the header field is to print within. N-N represents a form/subform page number range the header field is to print within. Combinations of N and N-N may exist separated by commas. ALL indicates that header field is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the header field is to print on relative form/subform pages 0, 2, 3, 4, and 6. |
||
| FOOTER | N, N-N or ALL | This field is either a form or subform footer field. N represents a form/subform page number (relative to 0) the footer field is to print within. N-N represents a form/subform page number range the footer field is to print within. Combinations of N and N-N may exist separated by commas. ALL indicates that footer field is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the footer field is to print on relative form/subform pages 0, 2, 3, 4, and 6. |
||
| SIDE | side | Side of form where field is positioned: FRONT (default) or BACK | ||
| SIZE | 🗸 | width,height | width - Field width. height - Field height. |
|
| INDEX | repeatcount,xoffset,yoffset | repeatcount - Count how often this field is repeated in the form, INDEX fields are fixed length (default is no INDEX field). xoffset - Horizontal offset for next field. yoffset - Vertical offset for next field. |
||
| TYPE | fieldtype | Type of field: TEXT (default) MICR OCR MSF BARCODE GRAPHIC PAGEMARK |
||
| SCALING | scalingtype | Information on how to size the GRAPHIC within GRAPHIC field types: BESTFIT (default): Scale to size indicated. ASIS: Render at native size. MAINTAINASPECT: scale as close as possible to size indicated while maintaining the aspect ratio and not losing graphic information. |
||
| BARCODE | hriposition | Position of the HRI (Human Readable Interpretation) characters: NONE (default) ABOVE BELOW BOTH The type of barcode to print is defined in the FONT field. |
||
| COERCIVITY | coercivity | Coercivity to be used for writing to the magnetic stripe of MSF field types: AUTO (default): Coercivity is decided by the service or hardware. LOW: Low coercivity. HIGH: High coercivity. |
||
| CLASS | class | Field class: OPTIONAL (default) STATIC REQUIRED |
||
| ACCESS | access | Access rights of field: WRITE (default) READ READWRITE |
||
| OVERFLOW | overflow | Action of field overflow: TERMINATE (default) TRUNCATE BESTFIT (The service fits the data into the field as well as it can) OVERWRITE (a contiguous write) WORDWRAP |
||
| STYLE | style | Display attributes as a combination, using the | operator, of the following: NORMAL (default) BOLD ITALIC UNDER (single underline) DOUBLEUNDER (double underline) DOUBLE (double width) TRIPLE (triple width) QUADRUPLE (quadruple width) STRIKETHROUGH ROTATE90 (rotate 90 degrees clockwise) ROTATE270 (rotate 270 degrees clockwise) UPSIDEDOWN (upside down) PROPORTIONAL (proportional spacing) DOUBLEHIGH TRIPLEHIGH QUADRUPELHIGH CONDENSED SUPERSCRIPT OVERSCORE LETTERQUALITY NEARLETTERQUALITY DOUBLESTRIKE OPAQUE (If omitted then the default attribute is transparent) Some of these styles may be mutually exclusive or may combine to provide unexpected results. |
||
| CASE | case | Convert field contents to: NOCHANGE (default) UPPER LOWER |
||
| HORIZONTAL | justify | Horizontal alignment of field contents: LEFT (default) RIGHT CENTER JUSTIFY |
||
| VERTICAL | justify | Vertical alignment of field contents: BOTTOM (default) CENTER TOP |
||
| COLOR | color | Color name: BLACK (default) WHITE GRAY RED BLUE GREEN YELLOW |
||
| RGBCOLOR | R, G, B | Color in RGB 8 bits per color format: R - Red portion of the RGB value 0-255. G - Green portion of the RGB value 0-255. B - Blue portion of the RGB value 0-255. RGBCOLOR overrides the COLOR attribute. |
||
| FONT | fontname* | Font name: This attribute is interpreted by the service. In some cases, it may indicate printer resident fonts, and in others it may indicate the name of a downloadable font. For BARCODE fields it represents the barcode font name. In some cases, this pre-defines the following parameters: | ||
| POINTSIZE | pointsize | Point size. If unspecified, the point size defaults to the POINTSIZE defined for the form. | ||
| CPI | cpi | Characters per inch. If unspecified, the CPI defaults to the CPI defined for the form. | ||
| LPI | lpi | Lines per inch. If unspecified, the LPI defaults to the LPI defined for the form. | ||
| FORMAT | formatstring* | This is an application defined input field describing how the application should format the data. This may be interpreted by the service. For GRAPHIC fields, this defines the type of the graphic, for example, "BMP", "PNG" etc. | ||
| INITIALVALUE | value* | Initial value. For GRAPHIC type fields, this value may contain Base64 encoded image data. The type of this graphic will be determined by the FORMAT field. | ||
| END | 🗸 |
The following diagrams illustrate the positioning and sizing of text fields on a form, and the vertical alignment of text within a field using VERTICAL=TOP and VERTICAL=BOTTOM values in the field definition.
Definition of the character drawing box:
When more than one line of text is to be printed in a field, and the definition includes VERTICAL=BOTTOM, the vertical position of the first line is calculated using the specified (or implied) LPI value.
15.1.4.6 - Frame Definition
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| XFSFRAME | 🗸 | framename* | ||
| BEGIN | 🗸 | |||
| POSITION | 🗸 | X,Y or X,Y,Z | X - Horizontal position of top left corner of the frame (relative to left side of form/subform). Y or Y,Z - Vertical position of top left corner of frame (relative to top of form/subform). Format Y,Z is used to indicate vertical positioning of the top left corner of the frame relative to top of form/subform when top of form/subform is other than 1st page of form/subform, where Z indicates page number (relative to 0) and Y indicates base resolution units relative to top of the form/subform page number (as indicated by Z). Format Y is used to indicate vertical positioning of the left corner of frame relative to top of the 1st form/subform. |
|
| FRAMES | fieldname* | Frames the field with the name fieldname, positioning and size information are ignored. The frame surrounds the complete field, not just the printed data. If the field is repeated, the frame surrounds the first and last fields that are printed. | ||
| HEADER | N, N-N or ALL | This frame is either a form/subform header frame. N represents a form/subform page number (relative to 0) the header frame is to print within. N-N represents a form/subform page number range the header frame is to print within. Combinations of N and N-N may exist separated by commas. ALL indicates that header frame is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the header frame is to print on relative form/subform pages 0, 2, 3, 4, and 6. |
||
| FOOTER | N, N-N or ALL | This frame is either a form/subform footer frame. N represents a form/subform page number (relative to 0) the footer frame is to print within. N-N represents a form/subform page number range the footer frame is to print within. Combinations of N and N-N may exist separated by commas. ALL indicates that footer frame is to be printed on all pages of form/subform. The form/subform page number is intended to supplement the Z parameter of the POSITION keyword. For example, 0,2-4,6 indicates that the footer frame is to print on relative form/subform pages 0, 2, 3, 4, and 6. |
||
| SIDE | side | Side of form where this frame is positioned: FRONT (default) BACK |
||
| SIZE | 🗸 | width,height | width - Frame width in base horizontal units for the form. height - Frame height in base vertical units for the form. |
|
| REPEATONX | repeatcount,xoffset | repeatcount - Count how often this frame is repeated horizontally in the form. xoffset - Horizontal offset for next frame in base horizontal units. |
||
| REPEATONY | repeatcount,yoffset | repeatcount - Count how often this frame is repeated vertically in the form. yoffset - Vertical offset for next frame in base vertical units. |
||
| TYPE | frametype | Type of frame: RECTANGLE (default) ROUNDED_CORNER ELLIPSE |
||
| CLASS | class | Frame class: STATIC (default) OPTIONAL (The frame is printed only if its name appears in the list of field names given as parameter to the Printer.PrintForm command. In this case, the name of the frame must be different from all the names of the fields.) |
||
| OVERFLOW | overflow | Action on frame overflowing the form: TERMINATE (default) TRUNCATE BESTFIT (the service fits the frame into the media as well as it can) |
||
| STYLE | style | Frame line attributes: SINGLE_THIN (default) DOUBLE_THIN SINGLE_THICK DOUBLE_THICK DOTTED |
||
| COLOR | color | Color name for frame lines: BLACK (default) WHITE GRAY RED BLUE GREEN YELLOW |
||
| RGBCOLOR | R, G, B | Color in RGB 8 bits per color format: R - Red portion of the RGB value 0-255. G - Green portion of the RGB value 0-255. B - Blue portion of the RGB value 0-255. RGBCOLOR overrides the COLOR attribute. |
||
| FILLCOLOR | color | Color name for interior of frame: BLACK WHITE (default) GRAY RED BLUE GREEN YELLOW |
||
| RGBFILLCOLOR | R, G, B | Color in RGB 8 bits per color format: R - Red portion of the RGB value 0-255. G - Green portion of the RGB value 0-255. B - Blue portion of the RGB value 0-255. RGBFILLCOLOR overrides the FILLCOLOR attribute. |
||
| FILLSTYLE | style | Style for filling the interior of frame: NONE (default): No fill SOLID: Solid color BDIAGONAL: Downward hatch (left to right) at 45 degrees CROSS: Horizontal and vertical crosshatch DIAGCROSS: Crosshatch at 45 degrees FDIAGONAL: Upward hatch (left to right) at 45 degrees HORIZONTAL: Horizontal hatch VERTICAL: Vertical hatch |
||
| SUBSTSIGN | substitute sign | Character that is used as substitute sign when a character in a read field cannot be read | ||
| TITLE | fieldname* | Uses the field with the name |
||
| HORIZONTAL | justify | Horizontal alignment of the frame title: LEFT (default) CENTER RIGHT |
||
| VERTICAL | justify | Vertical alignment of the frame title: TOP (default) BOTTOM |
||
| END | 🗸 |
The XFSFRAME definition provides a means for framing a XFSFIELD text field. The basic concept of a XFSFRAME definition and corresponding XFSFIELD definition is illustrated as follows:
When the XFSFRAME frames a field, its positioning and size information are ignored. Instead, Services should position the top left corner of the frame one horizontal base unit to the left and one vertical base unit to the top of the top left corner of the field. Similarly, Services should size the frame so that it bottom right corner is one base unit below and to the right to the field. For instance, if the form units are ROWCOLUMN, and a XFSFRAME “A” is said to frame the XFSFIELD “B” which is positioned at row 1, column 1 with a size of 1 row and 20 columns, the frame will be drawn from row 0, column 0 to row 3, column 22.
The horizontal and vertical positioning of a frame title overrides the position of the named XFSFIELD. For instance, if a XFSFRAME “A” is said to have the XFSFIELD “B” as its title, with the default horizontal and vertical title justification, it is just as if XFSFIELD “B” had been positioned at the top left corner of the frame. Note that the SIZE information for the title field still is meaningful; it gives the starting and/or ending positions of the frame lines.
The SIDE attributes of the XFSFRAME and the XFSFIELDs it refers to must agree.
The width of the lines and the interval between the lines of doubled frames are vendor specific. Whether the lines are drawn using graphics printing or using pseudo-graphic is vendor specific. However, Services are responsible for rendering intersecting frames.
Depending on the printer technology, framing of fields can substantially slow down the print process.
Support of framing by a Service or the device it controls is not mandatory to be XFS4IoT compliant.
15.1.4.6.1 - Sample 1 - Simple Framing
The form:
XFSFORM "Multiple Balances"
BEGIN
UNIT INCH, 16, 16
SIZE 91, 64
VERSION 1, 0, "13/09/96", "XFS"
XFSFIELD "Account Title"
BEGIN
POSITION 15, 4
SIZE 30, 4
CLASS STATIC
HORIZONTAL CENTER
INITIALVALUE "Account"
END
XFSFIELD "Balance Title"
BEGIN
POSITION 45, 4
SIZE 30, 4
CLASS STATIC
HORIZONTAL CENTER
INITIALVALUE "Balance"
END
XFSFIELD "Account"
BEGIN
POSITION 15, 8
SIZE 30, 4
INDEX 10, 0, 3
END //"Account"
XFSFIELD "Balance"
BEGIN
POSITION 45, 8
SIZE 30, 4
INDEX 10, 0, 3
HORIZONTAL RIGHT
END //"Balance"
XFSFRAME "Account Title"
BEGIN
POSITION 15, 4
FRAMES "Account Title"
SIZE 30, 4
STYLE DOUBLE_THIN
END
XFSFRAME "Balance Title"
BEGIN
POSITION 45, 4
FRAMES "Balance Title"
SIZE 30, 4
STYLE DOUBLE_THIN
END
XFSFRAME "Account"
BEGIN
POSITION 15, 8
FRAMES "Account"
SIZE 30, 34
STYLE DOUBLE_THIN
END
XFSFRAME "Balance"
BEGIN
POSITION 45, 8
FRAMES "Balance"
SIZE 30, 34
STYLE DOUBLE_THIN
END
END
When printed with the following field list:
Account[0]=0123456789123001
Account[1]=0123456789123002
Account[2]=0123456789123003
Balance[0]=$17465.12
Balance[1]=$2458.23
Balance[2]=$6542.78
Will print:
15.1.4.6.2 - Sample 2 - Framing With Title
The form:
XFSFORM "Bank Details"
BEGIN
UNIT INCH, 16, 16
SIZE 121, 64
VERSION 1, 0, "13/09/96", "XFS Editor"
XFSFIELD "Owner Frame Title"
BEGIN
POSITION 24, 9
SIZE 27, 3
CLASS STATIC
HORIZONTAL CENTER
VERTICAL CENTER
INITIALVALUE "Account Owner"
END
XFSFIELD "Owner"
BEGIN
POSITION 20, 11
SIZE 35, 9
CLASS REQUIRED
VERTICAL TOP
END //"Owner"
XFSFRAME "Owner Frame"
BEGIN
POSITION 19, 10
FRAMES "Owner"
SIZE 37, 11
TITLE "Owner Frame Title"
HORIZONTAL CENTER
END
END
When printed with the following field list:
Owner = Mr./Mrs. Jean Leroy
21560 Hagerty Road
Troy, MI.
Will print:
15.1.4.6.3 - Sample 3 - Framing With Filled Interior
The form:
XFSFORM "Bank Details"
BEGIN
UNIT INCH, 16, 16
SIZE 121, 64
VERSION 1, 0, "13/09/96", "XFS Editor"
XFSFIELD "Owner"
BEGIN
POSITION 20, 11
SIZE 35, 9
CLASS REQUIRED
VERTICAL TOP
END
XFSFRAME "Owner Frame"
BEGIN
POSITION 19, 10
FRAMES "Owner"
SIZE 37, 11
FILLCOLOR GRAY
FILLSTYLE CROSS
END
END
When printed with the following field list:
Owner = Mr./Mrs. Jean Leroy
21560 Hagerty Road
Troy, MI.
Will print:
15.1.4.6.4 - Sample 4 - Repeated Framing
The form:
XFSFORM "Smart Account Number"
BEGIN
UNIT INCH, 16, 16
SIZE 121, 64
VERSION 1, 0, "13/09/96", "XFS Editor"
XFSFIELD "Account Number"
BEGIN
POSITION 20, 8
SIZE 4, 4
INDEX 12, 4, 0
HORIZONTAL CENTER
VERTICAL CENTER
END
XFSFRAME "A/N Frame"
BEGIN
POSITION 20, 8
SIZE 4, 4
REPEATONX 12, 4
END
END
When printed with the following field list:
Account Number[0]=0
Account Number[1]=1
Account Number[2]=2
Account Number[3]=3
Account Number[4]=4
Account Number[5]=5
Account Number[6]=6
Account Number[7]=7
Account Number[8]=8
Account Number[9]=9
Account Number[10]=0
Account Number[11]=1
Will print:
15.1.4.7 - Media Definition
The media definition determines those characteristics that result from the combination of a particular media type together with a particular vendor's printer. The aim is to make it easy to move forms between different vendors' printers which might have different constraints on how they handle a specific media type. It is the services responsibility to ensure that the form definition does not specify the printing of any fields that conflict with the media definition. An example of such a conflict might be that the form definition asks for a field to be printed in an area that the media definition defines as an unprintable area.
The media definition is also intended to provide the capability of defining media types that are specific to the financial industry. An example is a passbook as shown below.
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| XFSMEDIA | 🗸 | medianame* | ||
| BEGIN | 🗸 | |||
| TYPE | type | Predefined media types are: GENERIC (default) MULTIPART PASSBOOK |
||
| SOURCE | source | Paper source: ANY (default) UPPER LOWER EXTERNAL (envelope tray or single sheet feed tray) AUX AUX2 PARK |
||
| UNIT | 🗸 | base,x,y | base - Base resolution unit for form definition: MM, INCH or ROWCOLUMN x - Horizontal base unit fraction y - Vertical base unit fraction |
|
| SIZE | 🗸 | width,height | width - Width of physical media height - Height of physical media (0 = unlimited, i.e., roll paper) |
|
| PRINTAREA | x,y,width,height | Printable area relative to top left corner of physical media (default = physical size of media) | ||
| RESTRICTED | x,y,width,height | Restricted area relative to top left corner of physical media (default = no restricted area) | ||
| FOLD | fold | Type of passbook: HORIZONTAL (default) or VERTICAL | ||
| STAGGERING | staggering | Staggering of passbook from top (default = 0) | ||
| PAGE | count | Number of pages in passbook (default = 0) | ||
| LINES | count | Number of printable lines (default = 0) | ||
| END | 🗸 |
15.1.4.8 - Form and Media Definitions in Multi-Vendor Environments
In a multi-vendor environment, the capabilities of the service and hardware may be different, therefore the following should be considered.
-
Physical print area dimensions of printers are not identical.
-
Graphic printout may not be supported, which may limit the use of the FONT, CPI and LPI keywords.
-
Some printers may have a resolution of dots/mm rather than dots/inch, which may result in printouts with a specific CPI/LPI font resolution to be slightly off size.
-
Some form/media definition keywords may not be supported due to limitations of the hardware or software.
15.1.5 - Command and Event Flows during Single and Multi-Page / Wad Printing
It is possible to print a number of pages or bunches of pages (wads) through the Service. The following sections describe how this is achieved.
15.1.5.1 - Single Page / Single Wad Printing With Immediate Media Control
This illustrates the command and event flows in a successful print command, i.e., Printer.PrintNative, Printer.PrintForm and Printer.PrintRaw where the following conditions apply. Printer.PrintNative is used as the example:
-
A single page or single wad of pages is presented.
-
The mediaPresented capability is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl in the command data is set to eject.
15.1.5.2 - Single Page / Single Wad Printing With Separate Media Control
This illustrates the command and event flows in a successful print command, i.e., Printer.PrintNative, Printer.PrintForm and Printer.PrintRaw where the following conditions apply. The Printer.PrintNative command is used as an example:
-
A single page or single wad of pages is presented.
-
The mediaPresented is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl is null.
-
The media is presented to the user through a Printer.ControlMedia command, with the mediaControl property set to eject.
15.1.5.3 - Multi Page / Multi Wad Printing With Immediate Media Control
This illustrates the command and event flows in a successful print command, i.e., Printer.PrintNative, Printer.PrintForm and Printer.PrintRaw where the following conditions apply. Printer.PrintNative is used as the example:
-
Multiple pages or multiple wads of pages are presented.
-
The mediaPresented capability is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl in the command data is set to eject.
-
The previous page/wad must be removed before subsequent pages/wads can be presented.
15.1.5.4 - Multi Page / Multi Wad Printing With Separate Media Control
This illustrates the command and event flows in a successful print command, i.e., Printer.PrintNative, Printer.PrintForm and Printer.PrintRaw where the following conditions apply. Printer.PrintForm is used as the example:
-
Multiple pages or multiple wads of pages are presented.
-
The mediaPresented capability is true (indicates that the Printer.MediaPresentedEvent event can be generated).
-
The mediaControl property is null.
-
The media is presented to the user through a Printer.ControlMedia command, with the mediaControl property set to eject.
-
The previous page/wad must be removed before subsequent pages/wads can be presented.
15.2 - Command Messages
15.2.1 - Printer.GetFormList
This command is used to retrieve the list of forms available on the device.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None15.2.2 - Printer.GetMediaList
This command is used to retrieve the list of media definitions available on the device.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None15.2.3 - Printer.GetQueryForm
This command is used to retrieve details of the definition of a specified form.
Command Message
Completion Message
Event Messages
None15.2.4 - Printer.GetQueryMedia
This command is used to retrieve details of the definition of a specified media.
Command Message
Completion Message
Event Messages
None15.2.5 - Printer.GetQueryField
This command is used to retrieve details of the definition of a single or all fields on a specified form.
Command Message
Completion Message
Event Messages
None15.2.6 - Printer.ControlMedia
This command is used to control media.
If an eject operation is specified, it completes when the media is moved to the exit slot. An unsolicited event is generated when the media has been taken by the user (only if the mediaTaken capability is true).
Command Message
Completion Message
Event Messages
15.2.7 - Printer.PrintForm
This command is used to print a form by merging the supplied variable field data with the defined form and field data specified in the form. If no media is present, the device waits for the period of time specified by the timeout parameter for media to be inserted from the external paper source.
All error codes (except noMediaPresent) and events listed under the Printer.ControlMedia command description can also occur on this command.
- An invalid field name is treated as a Printer.FieldWarningEvent event with failure notFound.
- If the data overflows the field and the field definition OVERFLOW value is TRUNCATE, BESTFIT, OVERWRITE or WORDWRAP, a Printer.FieldWarningEvent is posted with failure overflow.
- Other field-related problems generate a fieldError error code and a Printer.FieldErrorEvent.
Command Message
Completion Message
Event Messages
15.2.8 - Printer.PrintRaw
This command is used to send raw data (a byte string of device dependent data) to the physical device.
Applications which send raw data to a device will typically not be device or vendor independent. Problems with the use of this command include:
- The data sent to the device can include commands that change the state of the device in unpredictable ways (in particular, in ways that the service may not be aware of).
- Usage of this command will not be portable.
- This command violates the XFS4IoT forms model that is the basis of XFS4IoT printer access.
Thus usage of this command should be avoided whenever possible.
Command Message
Completion Message
Event Messages
15.2.9 - Printer.PrintNative
This command is used to print data using the native printer language. The creation and content of this data are both Operating System and printer specific and outwith the scope of this specification.
If no media is present, the device waits, for the timeout specified, for media to be inserted from the external paper source.
This command must not complete until all pages have been presented to the customer.
Printing of multiple pages is handled as described in Command and Event Flows during Single and Multi-Page / Wad Printing.
Command Message
Completion Message
Event Messages
15.2.10 - Printer.ReadForm
This command is used to read data from input fields on the specified form. These input fields may consist of MICR, OCR, MSF, BARCODE, or PAGEMARK input fields. These input fields may also consist of TEXT fields for purposes of detecting available passbook print lines with passbook printers supporting such capability. If no media is present, the device waits, for the timeout specified, for media to be inserted.
All error codes (except noMediaPresent) and events listed under the Printer.ControlMedia command description can also occur on this command.
The following applies to the usage of fields for passbook:
If the media type is PASSBOOK, and the field(s) type is TEXT, and the service and the underlying passbook
printer are capable of detecting available passbook print lines, then the field(s) will be returned without a
value, in the format "
To illustrate when media type is PASSBOOK, if a form named PSBKTST1 contains 24 fields, one field per line, and the field names are LINE1 through LINE24 (same order as printing), and after execution of this command fields contains fields LINE13 through LINE24, then the first print line available for passbook printing is line 13.
To illustrate another example when media type is PASSBOOK, if a form named PSBKTST2 contains 24 fields, one field per line, and the field names are LINE1 through LINE24 (same order as printing), and after execution of this command fields contains fields LINE13, and LINE20 through LINE24 then the first print line available for passbook printing is line 13, however lines 14-19 are not also available, so if the application is attempting to determine the first available print line after which all subsequent print lines are also available then line 20 is a better choice.
Command Message
Completion Message
Event Messages
15.2.11 - Printer.ReadImage
This function returns image data from the current media. If no media is present, the device waits for the timeout specified for media to be inserted.
If the returned image data is in Windows bitmap format (BMP), the first byte of data will be the start of the Bitmap Info Header (this bitmap format is known as DIB, Device Independent Bitmap). The Bitmap File Info Header, which is only present in file versions of bitmaps, will NOT be returned.
Command Message
Completion Message
Event Messages
15.2.12 - Printer.MediaExtents
This command is used to get the extents of the media inserted in the physical device. The input parameter specifies the base unit and fractions in which the media extent values will be returned. If no media is present, the device waits, for the timeout specified, for media to be inserted.
Command Message
Completion Message
Event Messages
15.2.13 - Printer.ResetCount
This function resets the present value for number of media items retracted to 0. The function is possible only for printers with retractBins.
The number of media items retracted is controlled by the service and can be requested before resetting using the Common.Status command.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None15.2.14 - Printer.Reset
This command is used by the application to perform a hardware reset which will attempt to return the device to a known good state.
The device will attempt to retract or eject any items found anywhere within the device. This may not always be possible because of hardware problems. The Printer.MediaDetectedEvent event will inform the application where items were actually moved to.
Command Message
Completion Message
Event Messages
15.2.15 - Printer.RetractMedia
The media is removed from its present position (media inserted into device, media entering, unknown position) and stored in one of the retract bins. An event is sent if the storage capacity of the specified retract bin is reached. If the bin is already full and the command cannot be executed, an error is returned and the media remains in its present position.
If a retract request is received for a device with no retract capability, the unsupportedCommand error is returned.
Command Message
Completion Message
Event Messages
None15.2.16 - Printer.DispensePaper
This command is used to move paper (which can also be a new passbook) from a paper source into the print position.
Command Message
Completion Message
Event Messages
15.2.17 - Printer.LoadDefinition
This command is used to load a form (including sub-forms and frames) or media definition into the list of available forms. Once a form or media definition has been loaded through this command it can be used by any of the other form/media definition processing commands. Forms and media definitions loaded through this command are persistent. When a form or media definition is loaded a Printer.DefinitionLoadedEvent event is generated to inform applications that a form or media definition has been added or replaced.
Command Message
Completion Message
Event Messages
None15.2.18 - Printer.SupplyReplenish
After the supplies have been replenished, this command is used to indicate that one or more supplies have been replenished and are expected to be in a healthy state.
Hardware that cannot detect the level of a supply and reports on the supply's status using metrics (or some other means), must assume the supply has been fully replenished after this command is issued. The appropriate threshold event must be broadcast.
Hardware that can detect the level of a supply must update its status based on its sensors, generate a threshold event if appropriate, and succeed the command even if the supply has not been replenished. If it has already detected the level and reported the threshold before this command was issued, the command must succeed and no threshold event is required.
If any one of the specified supplies is not supported by the Service, unsupportedData should be returned, and no replenishment actions will be taken by the Service.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None15.2.19 - Printer.ControlPassbook
This command can turn the pages of a passbook inserted in the printer by a specified number of pages in a specified direction and it can close the passbook. The controlPassbook property returned by Common.Capabilities specifies which functionality is supported. This command flushes the data before the pages are turned or the passbook is closed.
Command Message
Completion Message
Event Messages
None15.2.20 - Printer.SetBlackMarkMode
This command switches the black mark detection mode and associated functionality on or off. The black mark detection mode is persistent. If the selected mode is already active this command will complete with success.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None15.3 - Event Messages
15.3.1 - Printer.MediaPresentedEvent
This event is used to indicate when media has been presented to the customer for removal.
Event Message
15.3.2 - Printer.NoMediaEvent
This event specifies that the physical media must be inserted into the device in order for the command to proceed.
Event Message
15.3.3 - Printer.MediaInsertedEvent
This event specifies that the physical media has been inserted into the device.
The application may use this event to, for example, remove a prompt from the screen telling the user to insert media.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
15.3.4 - Printer.FieldErrorEvent
This event specifies that a fatal error has occurred while processing a field.
Event Message
15.3.5 - Printer.FieldWarningEvent
This event specifies that a non-fatal error has occurred while processing a field.
Event Message
15.3.6 - Printer.MediaRejectedEvent
This event is generated as a result of physical media that is rejected whenever an attempt is made to insert media into the physical device. Rejection of the media will cause the command currently executing to complete with an error, at which point the media should be removed.
The application may use this event to (for example) display a message box on the screen indicating why the media was rejected, and telling the user to remove and reinsert the media.
Event Message
15.4 - Unsolicited Messages
15.4.1 - Printer.MediaTakenEvent
This event is sent when the media is taken from the exit slot following the completion of a successful eject operation or following a Printer.MediaRejectedEvent. For devices that do not physically move media, this event may also be generated when the media is taken from the device.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
15.4.2 - Printer.MediaInsertedUnsolicitedEvent
This event specifies that the physical media has been inserted into the device without any read or print commands being executed. This event is only generated when media is entered in an unsolicited manner.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
15.4.3 - Printer.MediaPresentedUnsolicitedEvent
This event is used to indicate when media has been presented to the customer for removal as a result of a print operation through some non XFS4IoT interface.
Unsolicited Message
15.4.4 - Printer.MediaDetectedEvent
This event is generated when a media is detected in the device during a reset operation.
Unsolicited Message
15.4.5 - Printer.RetractBinStatusEvent
This event specifies that the status of the retract bin holding the retracted media has changed.
Unsolicited Message
15.4.6 - Printer.DefinitionLoadedEvent
This event is used to indicate when a form or media definition has successfully been loaded via the Printer.LoadDefinition command.
Unsolicited Message
15.4.7 - Printer.MediaAutoRetractedEvent
This event indicates when media has been automatically retracted by the device. Support for this event is indicated when autoRetractPeriod is non-zero. The event can be generated as the result of any command that presents media to the customer.
Unsolicited Message
15.4.8 - Printer.RetractBinThresholdEvent
This event specifies that the status of the retract bin holding the retracted media has changed.
Unsolicited Message
15.4.9 - Printer.PaperThresholdEvent
This event is used to specify that the state of the paper reached a threshold. There is no threshold defined for the parking station as this can contain only one paper item.
Unsolicited Message
15.4.10 - Printer.TonerThresholdEvent
This event is used to specify that the state of the toner (or ink) reached a threshold.
Unsolicited Message
15.4.11 - Printer.LampThresholdEvent
This event is used to specify that the state of the imaging lamp reached a threshold.
Unsolicited Message
15.4.12 - Printer.InkThresholdEvent
This event is used to specify that the state of the stamping ink reached a threshold.
Unsolicited Message
16 - Text Terminal Interface
This chapter defines the Text Terminal interface functionality and messages.
This section describes the functions provided by a generic Text Terminal Unit interface. A Text Terminal Unit is a text i/o device, which applies both to ATM operator panels and to displays incorporated in devices such as pads and printers. This service allows for the following categories of functions:
- Forms oriented input and output
- Direct display output
- Keyboard input
If the device has no shift key, the TextTerminal.ReadForm and TextTerminal.Read commands will return only upper case letters. If the device has a shift key, these commands return upper and lower case letters as governed by the user's use of the shift key.
16.1 - General Information
16.1.2 - Form and Field Definitions
This section outlines the format of the definitions of forms, the fields within them, and the media on which they are printed.
16.1.2.1 - Definition Syntax
The syntactic rules for form, field and media definitions are as follows:
- White space
Space, tab - Line continuation
Backslash (\) - Line termination
CR, LF, CR/LF; line termination ends a "keyword section" (a keyword and its value[s]). - Keywords
Must be all upper case - Names
Field, media and font names are case sensitive. - Strings
All strings must be enclosed in double quote characters ("). Standard C escape sequences are allowed. - Comments
Start with two forward slashes (//); end at line termination.
Other notes:
- If a keyword is present, all its values must be specified; default values are used only if the keyword is absent.
- Values that are character strings are marked with * in the definitions and must be quoted as specified above.
- Fields are processed in the sequence they are defined in the form.
- The order of attributes within a form is not mandatory; the attributes may be defined in any order.
- All definitions must be encoded in UTF-8. Keywords are restricted to an internal representation of ISO 646 [Ref. textterminal-1]] (ANSI) characters.
16.1.2.2 - XFS form/media definition in multi-vendor environments
In a multi-vendor environment, the capabilities of the service and hardware may be different, therefore the following should be considered.
- Physical display area dimensions may vary from one text terminal to another.
- Some form/media definition keywords may not be supported due to limitations of the hardware or software.
16.1.2.3 - Form Definition
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| FORM | 🗸 | formname* | ||
| BEGIN | 🗸 | |||
| SIZE | 🗸 | width height |
Width of form Height of form |
|
| VERSION | major, minor, date*, author* |
Major version number (default 0) Minor version number (default 0) Creation/modification date Author of form |
||
| COPYRIGHT | copyright* | Copyright entry | ||
| TITLE | title* | Title of form | ||
| COMMENT | comment* | Comment section | ||
| [XFSFIELD BEGIN ... END] |
fieldname* | One field definition for each field in the form | ||
| END | 🗸 |
16.1.2.4 - Field Definition
| Keyword | Nested Keyword | Required | Names | Notes |
|---|---|---|---|---|
| FIELD | 🗸 | fieldname* | ||
| BEGIN | 🗸 | |||
| POSITION | 🗸 | x, y |
Horizontal position (relative to left side of form) Vertical position (relative to top of form) The initial left upper position is referenced as (0,0) |
|
| SIZE | 🗸 | width, height |
Field width Field height |
|
| TYPE | fieldtype | Type of field: - TEXT (default) - INVISIBLE - PASSWORD (contents is echoed with '*') - GRAPHIC (ignored for TextTerminal.ReadForm commands) |
||
| SCALING | scalingtype | Information on how to size the Graphic within the field: - BESTFIT (default) scale to size indicated - ASIS render at native size - MAINTAINASPECT scale as close as possible to size indicated while maintaining the aspect ratio and not losing Graphic information. SCALING is only relevant for Graphics field types |
||
| CLASS | class | Field class: - OPTIONAL (default) - STATIC - REQUIRED |
||
| KEYS | keys | Accepted input key types: - NUMERIC - HEXADECIMAL - ALPHANUMERIC This is an optional field where the default value is vendor dependent. |
||
| ACCESS | access | Access rights of field: - WRITE (default) - READ - READWRITE |
||
| OVERFLOW | overflow | Action on field overflow: - TERMINATE (default) - TRUNCATE - OVERWRITE |
||
| STYLE | style | Display attributes as a combination of the following, ORed together using the '|' operator: - NORMAL (default) - UNDER (single underline) - INVERTED - FLASHING |
||
| HORIZONTAL | justify | Horizontal alignment of field contents: - LEFT (default) - RIGHT - CENTER |
||
| FORMAT | formatstring* | This is an application defined input field describing how the application should format the data. This may be interpreted by the Service. For GRAPHIC fields, this defines the type of the graphic, for example, "BMP", "PNG" etc. |
||
| INITIALVALUE | value* | Initial value. For GRAPHIC fields, this value may contain Base64 encoded image data The type of this graphic will be determined by the FORMAT field. |
||
| END | 🗸 |
16.2 - Command Messages
16.2.1 - TextTerminal.GetFormList
This command is used to retrieve the list of forms available on the device.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None16.2.2 - TextTerminal.GetQueryForm
This command is used to retrieve details of the definition of a specified form.
Command Message
Completion Message
Event Messages
None16.2.3 - TextTerminal.GetQueryField
This command is used to retrieve details of the definition of a single or all fields on a specified form.
Command Message
Completion Message
Event Messages
None16.2.4 - TextTerminal.GetKeyDetail
This command returns information about the keys (buttons) supported by the device. This command should be issued to determine which keys are available.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None16.2.5 - TextTerminal.Beep
This command is used to beep at the text terminal unit.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None16.2.6 - TextTerminal.ClearScreen
This command clears the specified area of the text terminal unit screen. The cursor is positioned to the upper left corner of the cleared area.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None16.2.7 - TextTerminal.SetResolution
This command is used to set the resolution of the display. The screen is cleared and the cursor is positioned at the upper left position.
Command Message
Completion Message
Event Messages
None16.2.8 - TextTerminal.WriteForm
This command is used to display a form by merging the supplied variable field data with the defined form and field data specified in the form.
Command Message
Completion Message
Event Messages
16.2.9 - TextTerminal.ReadForm
This command is used to read data from input fields on the specified form.
The 'enter' key only acts as terminate key when it is pressed in the last read field. When the 'enter' key is pressed in an intermediate field, the cursor moves to the next field and the data entry finishes for the current field. Any other key that terminates input (except cancel), will cause all the fields to be returned in their present state. If cancel terminates input then the command will return the keyCanceled error.
The following keys will not be returned in the output property fields, but they may affect the field content (note in the following the term field content is used to refer to the data buffer and the display field):
| Command key | Meaning |
|---|---|
| clear | Will clear the field content. |
| backspace | Will cause the character before the Current Edit Position to be removed from the field content. If 'backspace' is the first key pressed after a field is activated (for any reason other than when the 'backspace' key causes the field to be activated), then the last character in the field content is deleted. If 'backspace' is pressed when the Current Edit Position is at the start of a field, then the previous field is activated. If 'backspace' is the first key pressed after the field is activated as a result of an earlier 'backspace' then no characters are deleted from the field content and the previous field will be activated. It is not possible to navigate backwards past the first field; in this case 'backspace' will have no effect. |
| doubleZero | Will add a double zero '00' string to the field content. If there is not enough space for all the digits to be added to the field content when the fields's OVERFLOW definition is TERMINATE or TRUNCATE then the excess '0's will be ignored. If the field's OVERFLOW definition is OVERWRITE then all the '0's are added to the field content. |
| tripleZero | Will add a triple zero '000' string to the field content. If there is not enough space for all the digits to be added to the field content when the field's OVERFLOW definition is TERMINATE or TRUNCATE then the excess '0's will be ignored. If the field's OVERFLOW definition is OVERWRITE then all the '0's are added to the field content. |
Command Message
Completion Message
Event Messages
16.2.10 - TextTerminal.Write
This command displays the specified text on the display of the text terminal unit. The specified text may include the control characters CR (Carriage Return) and LF (Line Feed). The control characters can be included in the text as CR, or LF, or CR LF, or LF CR and all combinations will perform the function of relocating the cursor position to the left hand side of the display on the next line down. If the text will overwrite the display area then the display will scroll.
Command Message
Completion Message
Event Messages
None16.2.11 - TextTerminal.Read
This command activates the keyboard of the text terminal unit for input of the specified number of characters. Depending on the specified flush mode the input buffer is cleared. During this command, pressing an active key results in a TextTerminal.KeyEvent event containing the key details. On completion of the command (when the maximum number of keys have been pressed or a terminator key is pressed), the entered string, as interpreted by the Service, is returned. The Service takes command keys into account when interpreting the data.
Command Message
Completion Message
Event Messages
16.2.12 - TextTerminal.Reset
Sends a service reset to the Service. This command clears the screen, clears the keyboard buffer, sets the default resolution and sets the cursor position to the upper left.
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
None16.2.13 - TextTerminal.DefineKeys
This command defines the keys that will be active during the next TextTerminal.ReadForm command. The configured set will be active until the next TextTerminal.ReadForm command ends, at which point the default values are restored.
Command Message
Completion Message
Event Messages
None16.2.14 - TextTerminal.LoadForm
This command is used to load a form definition into the list of available forms. Once a form definition has been loaded through this command it can be used by any of the other form definition processing commands. Form definitions loaded through this command are persistent. When a form definition is loaded a TextTerminal.FormLoadedEvent event is generated to inform applications that a form definition has been added or replaced.
Command Message
Completion Message
Event Messages
16.3 - Event Messages
16.3.1 - TextTerminal.FieldErrorEvent
This event specifies that a fatal error has occurred while processing a field.
Event Message
16.3.2 - TextTerminal.FieldWarningEvent
This event is used to specify that a non-fatal error has occurred while processing a field.
Event Message
16.3.3 - TextTerminal.KeyEvent
This event specifies that any active key has been pressed at the Text Terminal device during TextTerminal.Read. In addition to giving the application more details about individual key presses this information may also be used if the device has no internal display unit and the application has to manage the display of the entered digits.
Event Message
16.3.4 - TextTerminal.FormLoadedEvent
This event is used to indicate when a form definition has successfully been loaded via the TextTerminal.LoadForm command.
Event Message
17 - Barcode Reader Interface
This chapter defines the Barcode Reader interface functionality and messages.
A Barcode Reader scans barcodes using any scanning technology. The device logic converts light signals or image recognition into application data and transmits it to the host system.
17.1 - Command Messages
17.1.1 - BarcodeReader.Read
This command enables the barcode reader. The barcode reader will scan for barcodes and when it successfully manages to read one or more barcodes the command will complete. The completion event for this command contains the scanned barcode data.
The device waits for the period of time specified by timeout for one of the enabled symbologies to be presented, unless the hardware has a fixed timeout period that is less than the value passed in the command.
Command Message
Completion Message
Event Messages
None17.1.2 - BarcodeReader.Reset
This command is used to reset the device. The scanner returns to power-on initial status and remains disabled for any barcode label reading.
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
None18 - Biometric Interface
This chapter defines the Biometric interface functionality and messages.
Biometrics refers to metrics related to human characteristics and biology. Biometrics authentication can be used as a form of identification and/or access control. This is an overview of biometrics, as well as an introduction to the terminology used in this document. It introduces the concept of scanning a person’s biometric data in raw image form (raw biometric data), then processing it into a smaller more concise form that is easier to manage (biometric template data). The first scan of a user is called ENROLLMENT as the user is effectively being enrolled into a scheme by recording their biometric data. Thereafter subsequent scans of the user can be compared to the original data in order to verify who they say they are (VERIFICATION), or alternatively used to identify them as a specific individual (IDENTIFICATION).
18.1 - General Information
18.1.1 - References
18.1.2 - Enrollment
The first time an individual uses a biometric device it is called Enrollment. During enrollment, biometric data from an individual is captured and stored somewhere, for example on a smart card or in a server/host database. Normally the raw biometric data captured will be processed and converted to a smaller format that is used for subsequent comparison. This format is referred to in this document as a template. A template is a synthesis of the relevant characteristics extracted from the original raw data. Elements of the biometric data that are not used in the matching algorithm are discarded in the template to reduce the file size and to protect the identity of the enrollee.
18.1.3 - Biometric Matching
During the matching phase, the obtained template is passed to a matcher which compares it to other existing templates and a probable match is calculated, either as a Boolean true or false or as a threshold indicating the likelihood of a match. With regard to matching, biometric systems commonly have two different basic modes of operation: Verification and Identification:
Verification: performs a one-to-one comparison of captured biometric data with a specific template in order to verify that an individual is the person they claim to be.
Identification: the system performs a one-to-many comparison of captured biometric data in order to establish a person’s identity.
Note: The above diagram does not make any assumptions about where the actual matching takes place. The interface provided is versatile enough to be able to support three basic Biometric systems:
Match on server: The biometric template data is stored on a server or host. When scanning takes place biometric data is sent to the server, which does the actual identification or verification.
Match on card: The biometric enrollment data for an individual is stored on a smart card/personal device. The device scans a user then returns the biometric template information to the client. This data is then sent to the card, and a client on the smart card chip does the comparison, returning the result to the client.
Match on device: The biometric enrollment data for an individual is stored on a smart card or host. The enrollment data is read from the card or host and into the device, which then compares it to scanned information, returning the result to the client.
18.1.4 - Biometric Device Types
There are many different varieties of biometric hardware, this biometrics specification supports three main different types of devices:
-
Devices which only support scanning and returning biometric data
In this case the device is a simple biometric scanning device, User data is scanned using the Biometric.Read, but matching is performed externally, for example on a smart card or on a server. In this case the Biometric.Match and Biometric.SetMatch are not supported. -
Devices which support a separate scan and match functionality
These devices scan and perform a comparison as separate operations. Existing biometric data is first imported using the Biometric.Import. When the Biometric.Read is then called the scanned user data is temporarily stored. The Biometric.Match is then called to perform the comparison and return the result. -
Devices which support a combined scan and match functionality
These devices scan and perform a comparison as a single operation. Existing biometric data is first imported using the Biometric.Import. In this case the Biometric.SetMatch must be called first, either as a one time call or before each Biometric.Read. The purpose of the Biometric.SetMatch is to set the criteria for matching. When the Biometric.Read is then called it scans the user’s biometric data and also performs the comparison as a single operation. The Biometric.Match is then called to return the result of the comparison.
18.1.5 - Biometric Data Security
It is recommended that biometric data should be treated with the same strict caution as any other identifying and sensitive information. A well-designed biometric data handling architecture should always be designed to protect against internal tampering, external attacks and other malicious threats. There are various ways of implementing good security of which two are listed below:
-
Multi Modal Biometrics
A Uni-Modal biometric system relies on data taken from a single source of information for authentication, for example a single fingerprint reading device. In contrast, Multi-Modal biometric systems work on the premise that it is more secure to accept information from two or more biometric inputs. As an example a user could provide a fingerprint in addition to facial recognition, a positive match from two physical characteristics improves the chances of a positive identification and mitigates the possibility that biometric data has been cloned. -
Data Encryption
Biometric data should be encrypted where possible. The Biometric specification provides for this by allowing an encryption key to be specified whenever data is exchanged between a client and the Service. In addition, the KeyManagement interface commands can be used for key management. In this case the Service would implement the biometric methods necessary to read and return data using the Biometric interface, while the key loading, reporting etc, the KeyManagement interface would be implemented in order to provide key management.
18.1.6 - Biometric Device Command Flows
18.1.6.1 - Biometric Enrollment Command Flow
The following diagram describes the flow of enrolling a user using the Biometric.Read. Two attempts at scanning are necessary.
18.1.6.2 - Biometric Match Command Flow – Separate Scan and Match
The following diagram describes the flow of successfully identifying a customer whose biometric template data was previously enrolled and stored on a server/smart card/host system. This template data is first imported using the Biometric.Import, which assigns it a unique identifying number. This identifier number can then be retrieved using the Biometric.GetStorageInfo.
The Biometric.Read and Biometric.Match are then used to scan data and then compare it with the template identified by identifier. In this use case the device can perform a separate scan and match operation, therefore the Biometric.Read is called to scan the subject’s biometric data then the Biometric.Match is called to perform the match and return the result to the client.
In this case the capability matchSupported is reported as storedMatch.
18.1.6.3 - Biometric Match Command Flow – Combined Scan and Match
The following diagram describes the flow of successfully identifying a customer whose biometric template data was previously enrolled and stored on a server/smart card/host system. This template data is first imported using the Biometric.Import, which assigns it a unique identifying number. This identifier number can then be retrieved using the Biometric.GetStorageInfo.
The Biometric.Read, Biometric.SetMatch and Biometric.Match are then used to scan data and compare it with the template identified by identifier. In this use case the device performs a combined scan and match operation, therefore the Biometric.SetMatch must be used to set the criteria to be used for matching, including the imported template to be identified by identifier. When the Biometric.Read is then called the device scans the user and performs the comparison as a combined operation. Finally the Biometric.Match is called to return the result of the comparison to the client.
In this case the capability matchSupported is reported as combinedMatch.
18.1.6.4 - Biometric Scan-Only Command Flow
The following diagram describes the flow for a simple biometric scanning device which does not support any matching at all. User data is scanned using the Biometric.Read but matching is performed externally, for example on a smart card or on a server. In this case the capability matchSupported is reported as none.
18.2 - Command Messages
18.2.1 - Biometric.GetStorageInfo
This command is used to obtain information regarding the number and format of biometric templates that have been imported using the Biometric.Import command.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None18.2.2 - Biometric.Read
This command enables the device for biometric scanning, then captures and optionally returns biometric data. A Biometric.PresentSubjectEvent will be sent to notify the client when it is ready to begin scanning and a Biometric.SubjectDetectedEvent sent for each scanning attempt. The numCaptures input parameter specifies how many captures should be attempted, unless it is zero in which case the device itself will determine this. Once this command has successfully captured biometric raw data it will complete with Success.
The Biometric.Read command has two purposes:
Scanning: The biometric data that is captured into the device can be processed into biometric template data and returned as an output parameter for enrollment or storage elsewhere, e.g. on a server or smart card.
Matching: The biometric data that is captured into the device can be used for subsequent matching. Once data has been scanned into the device it can be compared to existing biometric templates that have been imported using the Biometric.Import in order to allow verification or identification of an individual. The matchSupported capability indicates if the Biometric.Match can be used for matching, otherwise the matching must be done externally, e.g. on a server or smart card.
In either case the data that has been scanned into the device will be persistent according to the current persistence mode as reported by the dataPersistence status property.
Command Message
Completion Message
Event Messages
18.2.3 - Biometric.Import
This command imports a list of biometric template data structures into the device for later comparison with biometric data scanned using the Biometric.Read. Normally this data is read from the chip on a customer’s card or provided by the host system. Data that has been imported is available until a Biometric.Clear is called. If template data has been previously imported using a call to Biometric.Import, then it is overwritten. This data is not persistent across power fails.
Command Message
Completion Message
Event Messages
None18.2.4 - Biometric.Match
This command returns the result of a comparison between data that has been scanned using the Biometric.Read and template data that has been imported using the Biometric.Import. The comparison may be performed by this command or the Biometric.Read, this command is responsible for returning the result. Success is returned if the device has been able to successfully compare the data, however this does not necessarily mean that the data matched.
If the capability matchSupported value supports combinedMatch then the device performs a combined scan and match operation, and the Biometric.SetMatch must be called before this command in order to set the matching criteria. In this case if Biometric.SetMatch has not been called then this command will fail with sequenceError.
If the capability matchSupported supports storedMatch then the device will scan data using the Biometric.Read and store it, then the data can be compared with imported biometric data using the Biometric.Match.
This command can be used in two modes of operation: Verification or Identification, as indicated by the compareMode input parameter. The two modes of operation are described below:
Verification (compareMode is verify) :
In this case a one to one comparison is performed and the maximum input parameter is ignored.
The data that has been scanned previously using the Biometric.Read is compared with
a single template that has been imported using the Biometric.Import.
If there is a successful match then the confidenceLevel output parameter can be used to determine
the quality of the match and will be in the range 0 – 100, where 100 represents an exact match and 0 represents no match.
Identification (compareMode is identify) :
In this case a one to many comparison is performed.
The data that has been scanned previously using the Biometric.Read is compared with
multiple templates that have been imported using the Biometric.Import.
The input parameter maximum is used to specify the maximum number of matches to return:
a smaller number can make execution faster.
The required degree of matching similarity can be controlled using the threshold parameter
which is used to control the frequency of false positive and false negative matching errors.
The value of threshold represents the criteria as to what constitutes a successful match and is in the range 0 – 100,
where 100 represents an exact match and 0 represents no match.
If for example, threshold is set to 75 then only results with a matching score equal to or greater than 75 are returned.
The matching candidate list is returned in the matchResult output parameter sorted in order of highest score.
The higher the value of confidenceLevel the closer the candidate is to the beginning of the list,
with the best match being the first candidate in the list.
Note that where the number of templates that match the criteria of the threshold are greater than maximum,
only the maximum templates with the highest score will be returned.
Command Message
Completion Message
Event Messages
None18.2.5 - Biometric.SetMatch
This command is used for devices which need to know the match criteria data for the Biometric.Match before any biometric scanning is performed by the Biometric.Read. The Biometric.Read and Biometric.Match should be called after this command. For all other devices unsupportedCommand will be returned here.
If the capability matchSupported == combinedMatch then this command is mandatory. If it is not called first, the Biometric.Match will fail with the generic error sequenceError. The data set using this command is not persistent across power failures.
Command Message
Completion Message
Event Messages
None18.2.6 - Biometric.Clear
This command can be used to clear stored data. In the case where there is no stored data to clear this command completes with Success.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None18.2.7 - Biometric.Reset
This command is used by the client to perform a hardware reset which will attempt to return the biometric device to a known good state.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None18.2.8 - Biometric.SetDataPersistence
This command is used to set the persistence mode. This controls how the biometric data is persisted after a Biometric.Read. The data can be persisted for use by subsequent commands, or it can be automatically cleared.
Command Message
Completion Message
Event Messages
None18.3 - Event Messages
18.3.1 - Biometric.PresentSubjectEvent
This event is generated to notify the client when the device is ready for a user to present the subject to be captured to the biometric scanner, for example, placing a finger on a fingerprint reader.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
18.3.2 - Biometric.SubjectDetectedEvent
This event is generated to notify the client when the device has detected a subject in the capture area and an attempt to capture biometric data has been performed.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
18.3.3 - Biometric.RemoveSubjectEvent
This event is used to notify a client that the subject should be removed from the capture area of the device.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
18.4 - Unsolicited Messages
18.4.1 - Biometric.SubjectRemovedEvent
This message is generated when the subject has been removed from the capture area of the device. This event may be generated at any time.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
18.4.2 - Biometric.DataClearedEvent
This mandatory event notifies the client when data has been cleared. This can be the case when the data is cleared automatically after a Biometric.Read or Biometric.Match completion, or as a result of an explicit call to the Biometric.Clear or Biometric.Reset.
Unsolicited Message
18.4.3 - Biometric.OrientationEvent
This event is generated when the biometric subject has an incorrect orientation relative to the device scanner in order to allow a client to prompt a user to correct it.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
19 - Camera Interface
This chapter defines the Camera interface functionality and messages under XFS4IoT.
Banking camera systems usually consist of a recorder, a video mixer and one or more cameras. If there are several cameras, each camera focuses a special place within the self-service area (e.g. the room, the customer or the cash tray). By using the video mixer it can be decided, which of the cameras should take the next photo. Furthermore, data can be given to be inserted in the photo (e.g. date, time or bank code).
If there is only one camera that can switch to take photos from different positions, it is presented by the service as a set of cameras, one for each of its possible positions.
19.1 - Command Messages
19.1.1 - Camera.TakePicture
This command is used to start the recording of the camera system. It is possible to select which camera or which camera position should be used to take a picture. Data to be displayed on the photo can be specified using the camData property.
Command Message
Completion Message
Event Messages
19.1.2 - Camera.Reset
This command is used by the client to perform a hardware reset which will attempt to return the camera device to a known good state.
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
None19.2 - Event Messages
19.2.1 - Camera.InvalidDataEvent
This event is used to specify that the text string given was too long or in some other way invalid.
Event Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
20 - Lights Interface
This chapter defines the Lights interface functionality and messages.
This specification describes the functionality of the services provided by the Lights service by defining the service-specific commands that can be issued. This service allows for the operation of Lights, LEDs and Lamps on a device.
20.1 - Command Messages
20.1.1 - Lights.SetLight
This command is used to set the status of a light.
For guidance lights, the slow and medium flash rates must not be greater than 2.0 Hz. It should be noted that in order to comply with American Disabilities Act guidelines only a slow or medium flash rate must be used.
Command Message
Completion Message
Event Messages
None21 - Auxiliaries Interface
This chapter defines the Auxiliaries interface functionality and messages.
This Service allows for the operation of the following categories of Auxiliaries:
- Door sensors, such as cabinet, safe or vandal shield doors.
- Alarm sensors, such as tamper, seismic or heat sensors.
- Generic sensors, such as proximity or ambient light sensors.
- Key switch sensors, such as the ATM operator switch.
- Lamp/sign indicators, such as fascia light or audio indicators.
- Auxiliary indicators.
- Enhanced Audio Controller, for use by the partially sighted.
In self-service devices, the Auxiliaries unit is capable of dealing with external sensors, such as door switches, locks, alarms and proximity sensors, as well as external indicators, such as turning on lamps or heating.
When status information of the auxiliaries unit is changed, the Common.StatusChangedEvent is posted.
21.1 - Command Messages
21.1.1 - Auxiliaries.GetAutoStartupTime
This command is used to retrieve the availability of the auto start-up time function as well as the current configuration of the auto start-up time.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None21.1.2 - Auxiliaries.ClearAutoStartupTime
This command is used to clear the time at which the machine will automatically start.
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
None21.1.3 - Auxiliaries.Register
This command is used to register or deregister for events from the Auxiliaries Unit. The default condition is that all events are deregistered. The events are only registered or deregistered for the session which sends the command, all other sessions are unaffected. Only the events specified in the input payload will be affected, all others will remain in the same state.
No action has been taken if this command returns an error. If a hardware error occurs while executing the command, the command will return OK, but events will be generated which indicates the auxiliaries which have failed.
Command Message
Completion Message
Event Messages
None21.1.4 - Auxiliaries.SetAuxiliaries
This command is used to set or clear one or more device auxiliaries.
Command Message
Completion Message
Event Messages
None21.1.5 - Auxiliaries.SetAutoStartupTime
This command is used to set the time at which the machine will automatically start. It is also used to disable automatic start-up.
If a new start-up time is set by this command it will replace any previously set start-up time.
Before the auto start-up can take place, the operating system must be shut down.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None22 - Storage Interface
This chapter defines the Storage interface functionality and messages.
This specification describes the functionality of an XFS4IoT compliant Storage 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 other interfaces which require media storage functionality such as Cash Dispenser, Cash Acceptor or Card Reader interfaces to handle management of the device storage units.
22.1 - General Information
22.1.1 - Transaction Flows
The following sections describe how various scenarios are handled using XFS4IoT Storage.
22.1.1.1 - Replenishment of a Cash Handling device
Manual Cash Replenishment in XFS4IoT is performed using the Storage.SetStorage command.
Storage.SetStorage can operate in two flows depending on whether the associated Service supports exchange sessions. During an exchange session, the following additional functionality applies:
- Operational commands such as dispensing notes are not allowed.
- Cash configuration such as currency and value can be set. See Storage.SetStorage for details of which properties can be set.
22.2 - Command Messages
22.2.1 - Storage.GetStorage
This command is used to obtain information regarding the status, capabilities and contents of storage units. The capabilities of the storage unit can be used to dynamically configure the storage unit using Storage.SetStorage.
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
None22.2.2 - Storage.SetStorage
This command is used to adjust information about the configuration and contents of the device's storage units. Only properties that are to be changed need to be set in the payload of this command; properties that are not meant to change can be null.
This command generates the Storage.StorageChangedEvent to inform applications that storage unit information has been changed.
Only a subset of the information reported by Storage.GetStorage may be modified by this command therefore the payload is a subset of the GetStorage output. In addition, if the service supports an exchange state, only a subset of the information which may be modified by this command can be modified unless the service is in an exchange state. The descriptions of each property list which can be modified at any point using this command; any other changes must be performed while in an exchange state.
The values set by this command are persistent.
Command Message
Completion Message
Event Messages
22.2.3 - Storage.StartExchange
This command puts the device in an exchange state, i.e. a state in which storage units can be emptied, replenished, removed or replaced. The command will initiate any physical processes which may be necessary to make the storage units accessible. If this command returns a successful completion the device is in an exchange state.
The current exchange state is reported by exchange and any change of state is marked by a Common.StatusChangedEvent.
While in the exchange state:
- Storage.SetStorage may be called as required to configure the storage units. Note that some of the storage properties may only be set while in an exchange state, particularly properties which modify the configuration of the storage unit or units. The properties affected by this are documented in Storage.SetStorage. Note that Storage.SetStorage does not need to be called if the Service can obtain storage unit information from self-configuring units.
- Commands which operate the device mechanically such as an attempt to dispense notes may be rejected with exchangeActive. This allows the device to be replenished safely and in a controlled manner.
Not all devices which support the Storage interface support an exchange state, Storage.SetStorage may be sufficient to configure those storage units. In such devices, this command is not supported. Similarly, devices which support the Storage interface may not require an exchange state to be entered if for example only modifying counts.
The exchange state is exited by calling Storage.EndExchange.
In the exchange state the Storage.SetStorage command can be used multiple times to adjust the storage unit information, until the Storage.EndExchange command is performed.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
22.2.4 - Storage.EndExchange
This command will end the exchange state. If any physical action took place as a result of the Storage.StartExchange command then this command will cause the storage units to be returned to their normal physical state. Any necessary device testing will also be initiated.
The current exchange state is reported by exchange and any change of state is marked by a Common.StatusChangedEvent.
Storage.SetStorage does not need to be called if the Service can obtain storage unit information from self-configuring units.
If an error occurs during the execution of this command, then the application must issue a Storage.GetStorage to determine the storage unit information.
A Storage.StorageErrorEvent will be sent for any storage unit which cannot be successfully updated. If no units could be updated then an error code will be returned.
Even if this command does not return a successful completion the exchange state has ended.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
22.3 - Event Messages
22.3.1 - Storage.StorageErrorEvent
This event is generated if there is a problem with a storage unit during the execution of a command.
Event Message
22.4 - Unsolicited Messages
22.4.1 - Storage.StorageChangedEvent
This event is generated when a storage unit changes under the following circumstances:
-
When the unit changes in any way due to a Storage.SetStorage command.
-
When any change is made other than to counts by any other command or external intervention.
If a new storage unit is inserted the storage unit structure reported by the last Storage.GetStorage command is no longer valid. In that case an application should issue a Storage.GetStorage command after receiving this event to obtain updated storage unit information.
Unsolicited Message
22.4.2 - Storage.StorageThresholdEvent
This event is generated when a threshold condition has occurred in one of the storage units.
This event can be triggered either by hardware sensors in the device or by count thresholds being met.
Unsolicited Message
23 - Vendor Mode Interface
This chapter defines the Vendor Mode interface functionality and messages.
This interface allows for the coordination of access to resources, and should be read in conjunction with the Vendor Application interface.
23.1 - General Information
23.1.1 - Vendor Mode
In all device classes there needs to be some method of going into a vendor specific mode to allow for capabilities which go beyond the scope of the current XFS4IoT specifications. A typical usage of such a mode might be to handle some configuration or diagnostic type of function or perhaps perform some 'off-line' testing of the device. These functions are normally available on Self-Service devices in a mode traditionally referred to as Maintenance Mode or Supervisor Mode and usually require operator intervention. It is those vendor-specific functions not covered by (and not required to be covered by) XFS4IoT Services that will be available once the device is in Vendor Mode. This Service provides the mechanism for switching to and from Vendor Mode. The Vendor Mode service can be seen as the central point through which all requests to enter and exit Vendor Mode are synchronized.
Entry into, or exit from, Vendor Mode can be initiated either by an application or by the Vendor Mode Service itself. If initiated by an application, then this application needs to issue the appropriate command to request entry or exit. If initiated by the Vendor Mode Service i.e. some vendor dependent switch, then these request commands are not required. Once the entry request has been made, all registered applications will be notified of the entry request by an event message. These applications must attempt to close all open sessions with other Services (except for specific Services which explicitly allow sessions to remain open) as soon as possible and then issue an VendorApplication.EnterModeAcknowledge command to the Vendor Mode service when ready. Once all applications have acknowledged, the Vendor Mode Service will issue event messages to these applications to indicate that the System is in Vendor Mode. The application can then start the vendor dependent application.
Similarly, once the exit request has been made all registered applications will be notified of the exit request by an event message. These applications must then issue an VendorApplication.ExitModeAcknowledge command to the Vendor Mode service immediately. Once all applications have acknowledged, the Vendor Mode service will issue event messages to these applications to indicate that the system has exited from Vendor Mode.
The Vendor Mode Service is used in conjunction with the Vendor Application service. The Vendor Mode Service is responsible for coordinating the release of resources from other services, while the Vendor Application service is responsible for starting the vendor dependent application. The VendorApplication.StartLocalApplication command is used for the latter.
With regard to how the application relates to other services the following rules apply:
- If the vendor dependent application is published on the same service as a device, then the application only applies to that service/device.
- If the vendor dependent application is on its own service without any other device classes, then the app applies to all services/devices published by that publisher - i.e. from that vendor/hardware manufacturer.
The following diagrams show the various methods of entering and exiting Vendor Mode and should be read in conjunction with the command and event descriptions.
23.1.1.1 - Vendor Mode Entry triggered by an XFS Application
-
An XFS4IoT application calls VendorMode.EnterModeRequest to request entry into Vendor Mode.
-
The Vendor Mode service sends an VendorMode.EnterModeRequestEvent to all applications which have registered to participate in Vendor Mode. The applications relinquish control of the services they are connected to when and if they can.
-
Once the other applications have relinquished control of their device resources they send an VendorMode.EnterModeAcknowledge to the Vendor Mode service.
-
When all registered applications have reported that they have relinquished control of their services, the Vendor Mode service sends a VendorMode.ModeEnteredEvent to signify entry into Vendor Mode.
-
The Application calls the VendorApplication.StartLocalApplication command to start the vendor dependent application.
The system is now in Vendor Mode and a vendor dependent application can exclusively use the system devices in a vendor dependent manner.
23.1.1.2 - Vendor Mode Entry triggered by an XFS Application
-
The vendor dependent application exits.
-
The XFS4IoT application calls VendorMode.ExitModeRequest to request exit from Vendor Mode.
-
The Vendor Mode Service sends a VendorMode.ExitModeRequestEvent to all applications which have registered to participate in Vendor Mode.
-
The other applications call VendorMode.ExitModeAcknowledge.
-
When all registered applications have reported that they have exited Vendor Mode the Service sends a VendorMode.ModeExitedEvent to report exit from Vendor Mode.
The system is no longer in Vendor Mode.
23.2 - Command Messages
23.2.1 - VendorMode.Register
This command is issued by an application to register that it wants to participate in Vendor Mode.
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
None23.2.2 - VendorMode.EnterModeRequest
This command is issued by an application to indicate a logical request to enter Vendor Mode. The Service will then indicate the request to all registered applications by sending a VendorMode.EnterModeRequestEvent and then wait for an acknowledgement back from each registered application before putting the system into Vendor Mode. The service will change to enterPending on receipt of this command and will prevail until all applications have acknowledged, at which time service will change to active and the command completes. If the command fails when service is enterPending, service is changed to inactive and VendorMode.ModeExitedEvent is sent to all registered applications.
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
None23.2.3 - VendorMode.EnterModeAcknowledge
This command is issued by a registered application as an acknowledgement to the VendorMode.EnterModeRequestEvent and it indicates that it is ready for the system to enter Vendor Mode. All registered applications must respond before Vendor Mode can be entered. Completion of this command is immediate. If this command is executed outwith a request for Vendor Mode entry, or if the acknowledge has already been sent from this connection then the command completes with a sequenceError error code.
Note: Applications must be prepared to allow the vendor dependent application to display on the active interface. This means that applications should no longer try to be the foreground or topmost window to ensure that the vendor dependent application is visible.
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
None23.2.4 - VendorMode.ExitModeRequest
This command is issued by an application to indicate a request to exit Vendor Mode. The Service will then indicate the request to all registered applications by sending a VendorMode.ExitModeRequestEvent and then wait for an acknowledgement back from each registered application before removing the system from Vendor Mode. The status will change to exitPending on receipt of this command and will prevail until all applications have acknowledged, at which time the status will change to inactive and the ExitModeRequest command completes. If the command fails when the status is exitPending, the status is changed to active and a VendorMode.ModeEnteredEvent is sent to all registered applications.
This command can be used while in Vendor Mode.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None23.2.5 - VendorMode.ExitModeAcknowledge
This command is issued by a registered application as an acknowledgement to the VendorMode.ExitModeRequest command and it indicates that the application is ready for the system to exit Vendor Mode. All registered applications (including the application that issued the request to exit Vendor Mode) must respond before Vendor Mode will be exited. Completion of this command is immediate.
This command can be used while in Vendor Mode.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None23.3 - Unsolicited Messages
23.3.1 - VendorMode.EnterModeRequestEvent
This service event is used to indicate the request to enter Vendor Mode.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
23.3.2 - VendorMode.ExitModeRequestEvent
This service event is used to indicate the request to exit Vendor Mode.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
23.3.3 - VendorMode.ModeEnteredEvent
This event is used to indicate that the system has entered Vendor Mode.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
23.3.4 - VendorMode.ModeExitedEvent
This event is used to indicate that the system has exited Vendor Mode.
Unsolicited Message
24 - Vendor Application Interface
This chapter defines and describes the functionality of the Vendor Application Service, which is used to start a local application, and set the active interface.
24.1 - General Information
24.1.1 - Vendor Application
This specification describes the functionality of the commands and events provided by the Vendor Application Service by defining the service-specific commands that can be used. This service is responsible for starting a local vendor dependent application and should be used in conjunction with the Vendor Mode service, which is responsible for managing arbitration of access to active services in the services environment. For the exact detail of the interaction between the Vendor Mode service and the VendorApplication.StartLocalApplication command refer to the Vendor Mode Service documentation, which describes this fully.
The Vendor Mode Service is solely responsible for allowing an application to inform devices to either relinquish or reassert control of hardware, whereas the VendorApplication service is responsible for starting and managing the vendor dependent application itself. The vendor dependent application could be a monitoring application, a maintenance application or have another purpose. The exact purpose is not mandated by XFS4IoT.
Once the Vendor Mode Service has been called the VendorApplication.StartLocalApplication command can be used to run the vendor dependent application. When the vendor dependent application exits it sends a VendorApplication.VendorAppExitedEvent event to the main application to indicate that it has exited, the application can then use the Vendor Mode Service to communicate to other services that it is safe to regain control of the hardware.
The VendorApplication.SetActiveInterface command can be used to communicate to the Service which interface it should start on, this could be a local front screen, back screen or a remote screen on a terminal or mobile device. VendorApplication.GetActiveInterface reports the currently active interface. Note that the interface can also be changed while the vendor dependent application is running.
24.2 - Command Messages
24.2.1 - VendorApplication.StartLocalApplication
This command is issued by an application to start a local application which provides vendor dependent services. It can be used in conjunction with the Vendor Mode interface to manage vendor independent services and start vendor specific services, e.g. maintenance oriented applications.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None24.2.2 - VendorApplication.GetActiveInterface
This command is used to retrieve the interface that should be used by the vendor dependent application.
Command Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Completion Message
Event Messages
None24.2.3 - VendorApplication.SetActiveInterface
This command is used to indicate which interface should be displayed by a vendor dependent application. An application can issue this command to ensure that a vendor dependent application starts on the correct interface, or to change the interface while running.
Command Message
Completion Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
Event Messages
None24.3 - Unsolicited Messages
24.3.1 - VendorApplication.VendorAppExitedEvent
This event is used to indicate the vendor dependent application has exited, allowing an application the opportunity to exit Vendor Mode.
Unsolicited Message
| Payload (version 2.0) |
|---|
| This message does not define any properties. |
24.3.2 - VendorApplication.InterfaceChangedEvent
This event is used to indicate that the required interface has changed. This can be as a result of a VendorApplication.SetActiveInterface command, or when the active interface is changed through vendor dependent means while the vendor dependent application is active. The activeInterface property indicates which interface has been selected.
Note: Applications must be prepared to allow the vendor dependent application to display on the active interface. This means that applications should no longer try to be the foreground or topmost window to ensure that the vendor dependent application is visible.
Unsolicited Message
25 - 3.x Migration
This chapter provides information on how to migrate to and from XFS 3.x.
Migration to and from 3.x is a key requirement of XFS4IoT. This chapter describes how functionality available in XFS 3.x can be provided and/or derived to and from XFS4IoT.
25.1 - CDM (Cash Dispense Module)
The CDM class provides access to cash dispensing functionality. In XFS4IoT, it has been restructured to use the CashDispenser, Storage and CashManagement interfaces.
25.1.1 - WFS_INF_CDM_CASH_UNIT_INFO
storage unit storage information is defined by the WFS_INF_CDM_CASH_UNIT_INFO category which is replaced in XFS4IoT by Storage.GetStorage. The following table lists the output fields in WFS_INF_CDM_CASH_UNIT_INFO and how they are mapped in XFS4IoT.
The concept of logical and physical storage units does not exist in XFS4IoT, only physical units are reported. The 3.x logical cash counts can be easily calculated from the given cash counts as described below.
Storage.SetStorage provides all the same functionality as the 3.x command but also provides additional functionality:
- Only fields which need to be changed need to be provided, including only modifying storage units which are changing.
- Storage.GetStorage provides a much more detailed breakdown of the capabilities and status of the storage units than the 3.x equivalents, therefore it is possible to decide in advance what a storage unit can be configured to do using Storage.SetStorage.
- Storage.SetStorage only accepts as input the fields which can be modified.
| 3.x | XFS4IoT |
|---|---|
| WFSCDMCUINFO::usTellerID | Not supported, equivalent to 0 in XFS 3.x |
| WFSCDMCUINFO::usCount | Number of storage items with a cash interface |
| WFSCDMCASHUNIT::usNumber | index |
| WFSCDMCASHUNIT::usType | types. XFS4IoT has the option to support multiple types which is not available in 3.x, but an intelligent map can be performed, for example if the unit supports cashIn and cashOut then it can be mapped to WFS_CDM_TYPERECYCLING. |
| WFSCDMCASHUNIT::lpszCashUnitName | name |
| WFSCDMCASHUNIT::cUnitID | id |
| WFSCDMCASHUNIT::cCurrencyID | currency |
| WFSCDMCASHUNIT::ulValues | value. An additional conversion may be required due to the different types of these two items. value is the absolute value of the cash item, whereas ulValues is the value expressed in minimum dispense units. If the value of any of the items supported by the device can't be expressed as a C ULONG (integer between 0 and 0xffffffff) then a currency exponent will be required - see CashManagement.GetBankNoteTypes. |
| WFSCDMCASHUNIT::ulInitialCount | Total number of items in initial |
| WFSCDMCASHUNIT::ulCount | If not a retract unit, The total count of the items in the unit (ulCount in 3.x) is not reported directly but can be derived from the initial, out and in counts. The number of items in the unit is initial + in - out. However for units which dispense items, this calculation should only decremented when the items are either known to be in customer access or successfully rejected, therefore the intermediate out fields are not included in this calculation:stacked, transport, unknown and diverted. If counts being incorrectly set at replenishment time means that this would result in a negative number, this should report 0. A dispense storage unit which is not empty but has a derived ulCount of 0 may be dispensed from if locally configured to do so - this can cause problems for 3.x applications as ulCount can not be negative therefore it can't be used to track dispensed items once that point is reached. XFS4IoT deals with this issue by having separate counts for items in and out. If a retract unit, retractOperations |
| WFSCDMCASHUNIT::ulRejectCount | Total number of items in rejected |
| WFSCDMCASHUNIT::ulMinimum | lowThreshold |
| WFSCDMCASHUNIT::ulMaximum | highThreshold |
| WFSCDMCASHUNIT::bAppLock | appLockOut |
| WFSCDMCASHUNIT::usStatus | If operationStatus reports dispenseInoperative, then map to WFS_CDM_STATCUINOP, otherwise status if not ok, otherwise replenishmentStatus |
| WFSCDMCASHUNIT::usNumPhysicalCUs | No support for logical units in XFS4IoT. This is equivalent to XFS 3.x value 1. |
| WFSCDMCASHUNIT::ulDispensedCount | Add the total number of items in all of the out properties. |
| WFSCDMCASHUNIT::ulPresentedCount | Total number of items in presented |
| WFSCDMCASHUNIT::ulRetractedCount | Total number of items in retracted |
| WFSCDMPHCU::lpPhysicalPositionName | positionName |
| WFSCDMPHCU::cUnitID | id |
| WFSCDMPHCU::ulInitialCount | Total number of items in initial |
| WFSCDMPHCU::ulCount | 0 if a retract unit which cannot count items during a retract. In all other cases, start with WFSCDMCASHUNIT::ulCount and subtract the total number of items in stacked, transport and unknown. If this results in a negative number, this should be 0. |
| WFSCDMPHCU::ulRejectCount | Total number of items in rejected |
| WFSCDMPHCU::ulMaximum | capacity |
| WFSCDMPHCU::usPStatus | If operationStatus reports dispenseInoperative, then map to WFS_CDM_STATCUINOP, otherwise status if not ok, otherwise replenishmentStatus Note this is a change from XFS 3.x where physical status is not overridden by count thresholds (ulMaximum and ulMinimum). |
| WFSCDMPHCU::bHardwareSensor | hardwareSensors |
| WFSCDMPHCU::ulDispensedCount | Add the total number of items in all of the out properties. |
| WFSCDMPHCU::ulPresentedCount | Total number of items in presented |
| WFSCDMPHCU::ulRetractedCount | Total number of items in retracted |
25.2 - CIM (Cash-In Module)
The CIM class provides access to cash accepting functionality. In XFS4IoT, it has been restructured to use the CashAcceptor, Storage and CashManagement interfaces.
25.2.1 - WFS_INF_CIM_CASH_UNIT_INFO
storage unit storage information is defined by the WFS_INF_CIM_CASH_UNIT_INFO category which is replaced in XFS4IoT by Storage.GetStorage. The following table lists the output fields in WFS_INF_CIM_CASH_UNIT_INFO and how they are mapped in XFS4IoT.
The concept of logical and physical storage units does not exist in XFS4IoT, only physical units are reported. The 3.x logical cash counts can be easily calculated from the given cash counts as described below.
Storage.SetStorage provides all the same functionality as the 3.x command but also provides additional functionality:
- Only fields which need to be changed need to be provided, including only modifying storage units which are changing.
- Storage.GetStorage provides a much more detailed breakdown of the capabilities and status of the storage units than the 3.x equivalents, therefore it is possible to decide in advance what a storage unit can be configured to do using Storage.SetStorage.
- Storage.SetStorage only accepts as input the fields which can be modified.
| 3.x | XFS4IoT |
|---|---|
| WFSCIMCASHINFO::usCount | Number of storage items with a cash interface |
| WFSCIMCASHIN::usNumber | index |
| WFSCIMCASHIN::fwType | types. XFS4IoT has the option to support multiple types which is not available in 3.x, but an intelligent map can be performed, for example if the unit supports cashIn and cashOut then it can be mapped to WFS_CIM_TYPERECYCLING. |
| WFSCIMCASHIN::fwItemType | items |
| WFSCIMCASHIN::cUnitID | id |
| WFSCIMCASHIN::cCurrencyID | currency |
| WFSCIMCASHIN::ulValues | value. An additional conversion may be required due to the different types of these two items. value is the absolute value of the cash item, whereas ulValues is the value expressed in minimum dispense units. If the value of any of the items supported by the device can't be expressed as a C ULONG (integer between 0 and 0xffffffff) then a currency exponent will be required - see CashManagement.GetBankNoteTypes. |
| WFSCIMCASHIN::ulCashInCount | Add the total number of items in all of the in properties. |
| WFSCIMCASHIN::ulCount | If not a retract unit, The total count of the items in the unit (ulCount in 3.x) is not reported directly but can be derived from the initial, out and in counts. The number of items in the unit is initial + in - out. However for units which dispense items, this calculation should only decremented when the items are either known to be in customer access or successfully rejected, therefore the intermediate out fields are not included in this calculation:stacked, transport, unknown and diverted. If counts being incorrectly set at replenishment time means that this would result in a negative number, this should report 0. If a retract unit, retractOperations |
| WFSCIMCASHIN::ulMaximum | highThreshold |
| WFSCIMCASHIN::usStatus | If operationStatus reports depositInoperative, then map to WFS_CIM_STATCUINOP, otherwise status if not ok, otherwise replenishmentStatus |
| WFSCIMCASHIN::bAppLock | appLockIn |
| WFSCIMCASHIN::lpNoteNumberList | Combination of: 1. Start with initial 2. Add in 3. Remove out |
| WFSCIMCASHIN::usNumPhysicalCUs | No support for logical units in XFS4IoT. This is equivalent to XFS 3.x value 1. |
| WFSCIMCASHIN::lpszExtra | Any additional vendor-specific properties included in this storage unit not defined by the schema can be added to this field. |
| WFSCIMCASHIN::lpusNoteIDs | cashItems lists the cash items which the unit is configured to accept. This can be cross-referenced with CashManagement.GetBankNoteTypes to obtain the noteID for the given cash item. |
| WFSCIMCASHIN::usCDMType | types. XFS4IoT has the option to support multiple types which is not available in 3.x, but an intelligent map can be performed, for example if the unit supports cashIn and cashOut then it can be mapped to WFS_CIM_TYPERECYCLING. |
| WFSCIMCASHIN::lpszCashUnitName | name |
| WFSCIMCASHIN::ulInitialCount | Total number of items in initial |
| WFSCIMCASHIN::ulDispensedCount | Add the total number of items in all of the out properties. |
| WFSCIMCASHIN::ulPresentedCount | Total number of items in presented |
| WFSCIMCASHIN::ulRetractedCount | Total number of items in retracted |
| WFSCIMCASHIN::ulRejectCount | Total number of items in rejected |
| WFSCIMCASHIN::ulMinimum | lowThreshold |
| WFSCIMPHCU::lpPhysicalPositionName | positionName |
| WFSCIMPHCU::cUnitID | id |
| WFSCIMPHCU::ulCashInCount | Add the total number of items in all of the in properties. |
| WFSCIMPHCU::ulCount | 0 if a retract unit which cannot count items during a retract. In all other cases, start with WFSCIMCASHIN::ulCount and subtract the total number of items in stacked, transport and unknown. If this results in a negative number, this should be 0. |
| WFSCIMPHCU::ulMaximum | capacity |
| WFSCIMPHCU::usPStatus | If operationStatus reports depositInoperative, then map to WFS_CIM_STATCUINOP, otherwise status if not ok, otherwise replenishmentStatus Note this is a change from XFS 3.x where physical status is not overridden by count thresholds (ulMaximum and ulMinimum). |
| WFSCIMPHCU::bHardwareSensors | hardwareSensors |
| WFSCIMPHCU::lpszExtra | Any additional vendor-specific properties included in this storage unit not defined by the schema can be added to this field. |
| WFSCIMPHCU::ulInitialCount | Total number of items in initial |
| WFSCIMPHCU::ulDispensedCount | Add the total number of items in all of the out properties. |
| WFSCIMPHCU::ulPresentedCount | Total number of items in presented |
| WFSCIMPHCU::ulRetractedCount | Total number of items in retracted |
| WFSCIMPHCU::ulRejectCount | Total number of items in rejected |
25.2.2 - WFS_SRVE_CIM_COUNTACCURACYCHANGED
The count accuracy is reported as part of the Storage for a storage unit, therefore when the count accuracy changes, a Storage.StorageChangedEvent will be generated.