API

The asynchronous interface supports the standard way of integrating components in an event-based programming environment. That is, when long running requests are made (such as purchase and refund requests), control is returned immediately to the caller after the request is submitted, while the Tyro Terminal Adapter works in the background to complete the request. When the Tyro Terminal Adapter has something to report to the caller, it will raise an event, which the caller should have previously registered an interest in.

When constructing a new TerminalAdapter there are a couple of things to note:

• A POSInformation object must be used to construct the TerminalAdapter with. The TTA passes this information to Tyro for each transaction so that Tyro is able to log the source of each transaction. Some platforms may need to use setters for passing this information through.

Asynchronous Event Driven Interface

As mentioned, the API is registered upon installation for calling via .Net The interface essentially functions exactly the same in .net environment. The mechanism for binding your particular environment to the chosen style of interface may differ.

As of TTA v2, there is a 'headless' capability which allows POS vendors to implement their own UI rather than the default one provided by Tyro. The interface for this is "Tyro.Integ.ITerminalAdapterHeadless". This interface has the same method signatures as normal interface along with some extra methods and events necessary for driving the UI

Methods

The methods of the API are all non-blocking, allowing for the event loop of most Windows based runtime environments to be freed to perform other tasks. If one of these methods is called while the Terminal Adapter is busy performing another transaction, they will return false, otherwise they will return true.

Methods that are recommended for the retail and hospitality industries are:

• boolean PurchaseAdditionalData(int amountInCents, , int cashoutInCents, "{ 'enableSurcharge': true | false }"): To commence a purchase transaction signalling to a terminal (that is configured for surcharging) to include or exclude a surcharge. For more information on surcharging, see Appendix B.
• boolean PurchaseTransactionIdAdditionalData(int amountInCents, , int cashoutInCents, String transactionId, "{ 'enableSurcharge': true | false }"): To commence a purchase transaction using a transactionId generated by the POS* and signalling to a terminal (that is configured for surcharging) to include or exclude a surcharge. For more information on surcharging, see Appendix B.
• boolean Refund(int amountInCents): To commence a refund transaction. The method will return false if this instance of the Tyro Terminal Adapter is busy performing another transaction, or the amount is invalid.
• boolean Refund(int amountInCents, String transactionId): To commence a refund transaction using a transactionId generated by the POS*. The method will return false if this instance of the Tyro Terminal Adapter is busy performing another transaction, or the amount is invalid.

Methods that are recommended for the health industry that wants to implement the multi-merchant feature are:

• boolean PurchaseMidTidAdditionalData(string merchantID, string terminalID, int amountInCents, int cashoutInCents, "{ 'enableSurcharge': true | false }"): Same as above, but allowing a specific Merchant ID and Terminal ID to be specified, for multi-merchant capable terminals and signalling to a terminal (that is configured for surcharging) to include or exclude a surcharge.
• boolean RefundMidTid(string merchantID, string terminalID, int amountInCents): Same as above, but allowing a specific Merchant ID and Terminal ID to be specified, for multi-merchant capable terminals.

Events

There are two different kinds of events that are raised by the Terminal Adapter:

• Events which are raised during a transaction: These events may be raised multiple times, even within the same event type, during the course of a transaction. Only the ReceiptReturned event falls into this category.
• Events which are raised at the conclusion of a transaction: These events indicate that the terminal has concluded its operations for this transaction, because the transaction was completed, or perhaps because some error occurred. Only one of any of these types of events will be raised per transaction.

The main events are:

• ReceiptReturned: When there is a receipt available for printing. This event will be raised only when printing via the POS is selected in the printing tab of the configuration menu. As many receipts per transaction may be produced, this event may be raised many times, and should be immediately printed by the POS. This includes the following methods:
  • String GetText() : Returns the text of the receipt, formatted only with spaces and newline characters.
  • Boolean IsSignatureRequired() : An indication of whether a signature line should be added by the POS at the bottom of this receipt.
• TransactionCompleted: When the TTA has been given an indication by the terminal that the transaction has been completed.
  • String GetStatus() : The status of the transaction, as a String. Can be either "PENDING" or "COMPLETE".
  • String GetResult() : The result of this transaction, as a String. Can be either "APPROVED", "DECLINED", "CANCELLED", "REVERSED" or "SYSTEM ERROR". Please see Appendix A for an interpretation guide for these messages.
  • String[] GetReceipts() : A string array of all of the receipts for this transaction, in the order in which they were produced by the terminal. This will only be populated if "Printing managed by the POS" was enabled in the Printing tab of the Configuration dialog.
  • String GetID() : The integrated transaction ID used in the transaction (used in combination with reconciliation)
  • String GetCardType() : The card type used in this transaction. Currently "EFTPOS", "Visa", "MasterCard", "American Express", "Diners Club", "JCB", "UnionPay" or "Afterpay" but changes as new card types are accepted by Tyro.
  • String GetAuthorisationCode() : The Authorisation Code for this transaction, as a String, from the issuer (if available - not always present).
  • String GetTransactionReference() : The transaction reference, as a String, which together with the date and time of the transaction identifies this transaction within Tyro. This will only be populated if "Printing managed by the POS" was enabled in the Printing tab of the Configuration dialog.
  • String GetTipCompletionReference() : Deprecated. The tip completion reference. The POS needs to store this value so that it can be used later on in the integrated tip completion process. Only contains a value if the terminal processed a tipping transaction where the tip amount will be written on the receipt.
  • String GetTipAmount() : The tip amount that was keyed into the terminal during the transaction.
  • String GetCompletionReference() : The tab completion reference. The POS needs to store this value so that it can be used later on in the close tab completion process.
  • String GetExtraData() : Returns an XML string with extra data (detailed below)
• Boolean ErrorOccurred: When there has been an error, either communicating with the integration server, or because of misconfiguration. When this is raised, the Terminal Adapter has no idea of the transaction result on the terminal, and the POS operator should be instructed to determine the status of the transaction by other means.
  • String GetErrorMessage() : A plain english description of the error.
  • Boolean IsTransactionStarted() : An indication of whether the Terminal Adapter has sent the request to commence the transaction. If this is false, then the POS operator does not need to be concerned with finding the final status of the transaction.