TTA (V2) Integration SDK Guide
Introduction
To achieve integration between a Point Of Sale system and the Tyro Terminal, the POS system must send requests for the terminal via an Integration Server within the Tyro system. The server acting as a proxy for all requests has been implemented this way not only for reasons of security, but also because it makes terminal deployment much simpler, and it allows us to easily expose extra functions of our systems (such as richer reporting) to the POS. At the moment, the information sent to the Terminal via the Integration Server includes requests to perform purchases and refunds, to send input to the terminal during transactions, and to receive transaction status updates and receipts for printing via the POS system. This communications channel is secure, in that no third party can inspect the information passed between the POS system and the Terminal, and also authorised, in that the Terminal and the Terminal operator has complete control over who can communicate with it. The communications with the terminal, via the Integration Server, take place over a RESTful HTTP protocol (over SSL) which uses XML as the content for responses, which we call the "Web Integration" protocol. This style of integration is standards based, allowing any development environment which is readily capable of communicating via HTTP and consuming XML to integrate with the Tyro Terminals. Some integrators benefit greatly from the flexibility this style of integration affords. It allows them to fully customise the style of interaction during integration, so that it may be wholly incorporated into the POS system, according to that systems style. It also allows development on an extremely wide range of platforms, as HTTP and XML are platform-independent technologies. However, at Tyro we have found that most integrators want an easy way of integrating their POS systems with the Tyro Terminals. We have responded to this need by creating the Tyro Terminal Adapter, a piece of software which basically takes all of the hard work out of integrating with the Tyro Terminals. It exposes a very simple .net programmable interface that can be called to perform purchase and refund transactions. During these transactions, the POS system operator is presented with a new window showing the progress of the transaction on the terminal, while it manages all aspects of communications with the terminal to perform the transaction. In the TTA v2, there is a 'headless' capability which allows POS vendors to implement their own UI rather than the default one provided by Tyro.
Integration Overview
A POS system communicates with a Tyro Terminal via the Tyro Integration server, as can be seen in the following diagram:
As you can see, the same secure and reliable network connection that the Terminal uses to perform financial transactions is also used to facilitate integration. This style of integration is called "Web Integration".
At a high level, the operations that the Tyro Terminal Adapter exposes that are available to a POS are:
- Purchase (with optional cashout). Please see the "Methods" section below for more information on the data that can be sent at the start of a purchase.
- Refund. Please see the "Methods" section below for more information on the data that can be sent at the start of a refund.
The general flow of a transaction from the perspective of a POS system is as follows:
The diagram above illustrates some important points.
Firstly, the POS system starts a transaction using the Tyro software and then waits for the transaction to finish, either because:
- The transaction completed successfully and the result is know (approved, declined etc). Please see the "Events" section below for details of the information available at this point.
- Or, there was some fatal error communicating with the terminal and hence the result of the EFTPOS transaction on the terminal could not be determined. Please see the "Events" section below for details of the information available at this point.
During the time between the POS system starting the transaction and waiting for it to finish, the Tyro Terminal Adapter (TTA) will display a window to the POS operator, offering updates on the EFTPOS transaction in progress and the opportunity to control the transaction in some way. This window offers detailed information on the progress of the transaction, removing the need for the POS operator to interact directly with the EFTPOS terminal at all.
Also, during that transaction, if the POS system has elected to manage the printing of the EFTPOS receipts itself (configured outside of the EFTPOS transaction process flow), the POS system will receive notification when receipts are available so that it can print the receipt, store the receipt etc. Please see the "Events" section below for details of the data elements that are available.
All new POS integrations are required to incorporate integrated receipts in their integration with Tyro Payments. This is because not all of our terminals have integrated printers so we expect that POS integrations will be able to offer this facility.
TTA .NET CORE (V2)
In the new .NET Core world, there is no GAC for libraries anymore. Any libraries .NET Core applications use need to be pulled down in the form of NuGet package from NuGet Gallery and become part of the application to be shipped together. Microsoft wants all .NET applications to be self-sufficient hence less errors due to missing/incorrect dependencies. The issue with this new way of sharing library is that TYRO loses the ability to enforce what version to be used, as any updated version of TTA will require the POS application to be re-built using a new NuGet package and re-released, the old POS application will still run just fine with old TTA library.
Deprecated Components
This new online model significantly streamlines the solution by removing the following areas:
- Registry Usage: Currently registry is used for two kinds of settings, the per user settings like pairing info and the global settings like integration server URL. The per user settings are moved to user config file in %UserProfile%\AppData\Local\Tyro\config.json. The global settings are moved to online settings.json file to be hosted by TYRO. All registry usage in codebase is cleaned up.
- Installer: This is no longer needed as no installation is required to use TTA functionality on client machine. All the WiX Toolset projects are removed from codebase.
- Filewatcher: This is no longer supported as it requires admin right to see and turn on the option in configurator app which will now be started via thin client interface by POS application which will not have admin access. It also requires admin right to modify the registry so that it runs when OS starts up which is no longer possible.
- RMS COM: This is no longer supported as it requires COM installation.
- Updater & Telemetry: This is no longer needed as they require installing windows services. For updater, it is also because the online model is the new way of enforcing updates.
- Compact Framework: The support for compact framework is removed as it no longer exists. The codebase has a lot of conditional logic using directive (#if COMPACT_FRAMEWORK) for the support. Also, the projects have a specific build for compact framework. So, all those are now removed.