Testing
Testing is an important part of any software development project, so we have a couple of options available to help POS developers test their implementation:
- CLI test harness: We have developed a Java based command line interface test harness that emulates the messaging between terminal and POS server. The software is distributed as a downloadable archive. Instructions for use are contained within the archive.
- Development terminal: We are happy to provide development terminals for a period of up to 3 months. The terminal will be connected to our pre-production network and comes with a set of test cards for use with the terminal. The development terminal will process transactions using these test cards with no actual financial effect.
Certification and Testing process
All POS partners must pass Tyro's mandatory certification process before they can go into production with their Pay@table integration. The certification process also involves a testing component as well, this broadly entails the following:
- The provision of the filled-in Tyro integration form and the proof-of-functionality videos for your integration post-development and internal testing once development and internal testing has concluded.
- The provision of a sandbox version of the developed Pay@table integration to allow us to test the integration, depending on the environment, platform, and language used to develop the integration the provision can vary in nature, specific instructions and directions are provided at the stage in the process by the Tyro Presales and Partner Support team member handling the project.
- Testing of the integration with regular feedback passage back to the respective POS partner for any issues that need addressing, please note that the Tyro Certification Criteria will be used to determine the eligibility of features for certification barring any exceptions granted.
Once certification is complete, POS vendors are then allowed to go into production. We suggest that a pilot program is run prior to a broader release.
Generating and Verifying Message Authentication Codes
Pay@table integration involves the transmission of transaction requests and transaction responses between the POS Pay@table server and the Tyro terminal, this communication requires that measures be taken to ensure the validity and integrity of the contents of the messages received. Tyro's Pay@table protocol makes use of HMAC-SHA1 using the SHA1 cryptographic hash function to reasonably ensure that communication between the POS Pay@table server and the Tyro Terminal have come from the correct source and that have not been modified in any way.
In the simplest terms, a Message Authentication Code (MAC) is a short piece of information used to authenticate a message.
MAC generation is carried out using A MAC algorithm, sometimes called a keyed (cryptographic) hash function, this hash function uses two inputs, a secret key and an arbitrary-length message that is to be authenticated, and produces a MAC as the output. The MAC value protects both the message's data integrity as well as its authenticity by allowing verifiers (who also possess the secret key) to detect any changes to the message content.
This is done by sending the MAC along with the message to the receiver who then uses the secret key to generate the MAC using the received message, the MAC generated on the receiver's end is then compared with the original MAC received. If the MAC generated on the receiver's end matches the received one then this confirms the validity and authenticity of the message.
The MAC algorithm that has been adopted in this case is HMAC (http://en.wikipedia.org/wiki/HMAC). A HMAC is a Hash-based Message Authentication Code which is very secure MAC algorithm and is implemented across a wide range of programming languages including .NET, Java, C etc.
Some sample code for MAC generation using the SHA1 cryptographic hash function in C# and Java is given below:
C# Sample Code:
byte[] mac = new HMACSHA1(passphrase).ComputeHash(message);Java Sample Code (1.4+):
Mac hmac = Mac.getInstance("HmacSHA1");
SecretKeySpec secret = new SecretKeySpec(passphrase.getBytes("ISO-8859-1"), "HmacSHA1");
hmac.init(secret);
byte[] mac = hmac.doFinal(message.getBytes("ISO-8859-1"));
String macAsHex = Hex.encodeHexString(mac);-
Please note that MAC verification only applies to the following requests:
- POST requests for transaction responses (Terminal-to-Pay@table Server)
- All request responses (GET open sales request response, GET diagnostics request) by the POS Pay@table server to the Tyro terminal.
- MAC verification on the POS Pay@table server does not apply to GET open sales and diagnostics requests that are sent by the Tyro terminal since there is no message content in the HTTP request for the MAC to be calculated against, and therefore no MAC is specified by the Tyro terminal in the x-tyro-mac request header for these requests.
- The POS Pay@table server however, can and is required to calculate the MAC against the message contained in the response that is being returned back to the Tyro terminal, and the terminal will perform MAC verification to confirm the validity of the message.
- MAC verification thus applies to all responses returned by the POS Pay@table server to the Tyro terminal since there is content that can be used to compute the MAC in these cases.
- The MAC is provided to the receiving party as a HTTP header named ‘x-tyro-mac’ in the HTTP request/response .
- The receiving party must verify the message using the received MAC (contained in the 'x-tyro-mac' request header) by computing the MAC for the message received using the process detailed above and then comparing the computed MAC with the received MAC to ensure that they are identical.
- If verification of the MAC by the POS Pay@table server fails, the POS Pay@table server must return an HTTP status code of 403.
An example of failed MAC verification is given below:
- Request type: POST request by the Tyro terminal posting an approved transaction response back to the POS Pay@table server.
- Transmitted Message: Approved transaction response message transmitted
- Passphrase (Secret): p@ssphr@se
- Generated and transmitted MAC: e15c06852f355065ef2d044b0334fa14d43bd85d
During transmission the message has had its amount changed from 1.00 $ to 100.0 $
- Received Message: Approved transaction response message received
- Passphrase (Secret): p@ssphr@se
- Generated MAC: c6a578066f2b77c97261833bb47bebdc6b9717bf
During transmission the message has had its amount changed from 1.00 $ to 100.0 $
- Received Message: Approved transaction response message received Expand source
- Passphrase (Secret): p@ssphr@se
- Generated MAC: c6a578066f2b77c97261833bb47bebdc6b9717bf
Comparing the received MAC (e15c06852f355065ef2d044b0334fa14d43bd85d) and the generated MAC (c6a578066f2b77c97261833bb47bebdc6b9717bf) it can be seen that there is a mismatch which confirms that the message sent was not the one that was received and the POS Pay@table will return a 403 HTTP status code back to the Tyro terminal.
Table Locking
Table Locking is a feature of Pay@table integration that allows access to tables opened on either the POS program or the Tyro terminal to be locked down so that the other end is unable to access them as long as they are being accessed on one end. This means that:
-
Tables being accessed, edited, or modified on the POS program can not be pulled by the Tyro terminal through a GET open sales request, this is called POS-side locking.
The sequence for these cases is as given below:
- A stored open sale is opened on the POS program to edit the open sale.
- POS logic is used to render the table open on the POS as 'unavailable' on the database.
- Attempting to pull the table with the table number of the table open on the POS results in Tyro terminal sending the GET open sales request.
- The POS Pay@table server returns a HTTP 412 error code along with the messaging that the POS wants to be displayed on the Tyro terminal screen, the maximum message length for this message is ninety characters. If the message is longer than ninety characters, the first ninety characters will be displayed. If no message is provided, a default message of "Table is unavailable at this time" will be displayed.
-
Tables open and ready to be closed on the Tyro terminal can not be edited or opened on the POS program until they are released by the terminal, this is called Terminal-side locking.
The sequence for these cases is as given below:
- A stored open sale is opened on the Tyro terminal using the GET open sales request. This GET open sales request will need to contain the always-return-outcome set to 'true' to allow the terminal to accommodate table locking.
- The sale is successfully returned to the terminal and is awaiting the cardholder to tap, swipe, or insert the card and process the transaction.
- POS logic is used to render the table open on the terminal as 'unavailable' on the database so that it can not be accessed on the POS until it is released by the terminal i.e. a partial payment for the table is made, or the user releases table on the terminal.
- Any attempts to access the table on the POS while it is open on the terminal result in suitable messaging advising the user that the table is currently open on the Tyro terminal being displayed on the POS interface.
- The POS can use the CANCELLED transaction response that is returned by the terminal to the POS server upon the table being released to unlock the table for access on the POS.
Table locking provides a mechanism to control concurrent access to tables and prevent scenarios for e.g. where the table details are being modified for tables that are already open and being paid off on the terminal.
Integrated Surcharging
Tyro terminals can be configured to support surcharging. Surcharging is where merchants are allowed to reduce the cost of acquiring card payments by adding on the cost of the transaction as a surcharge.
Merchants can specify a percentage surcharge for credit cards and the terminal will automatically apply the surcharge during the transaction. To ensure that reconciliation between the Tyro and the POS is maintained, Tyro will settle the transaction amounts minus the surcharge amounts and deduct the surcharge amounts from the invoice at the end of the month. This means that surcharging can be enabled by a merchant even if the POS has not added support for Tyro surcharging.
Surcharges are set by the merchant as a uplift percentage and are applicable for all schemes except UnionPay and EPAL (i.e. EFTPOS) cards. Tyro allows a different surcharge rate to be applied to each of the following card types:
- Visa Credit
- Visa Debit
- MasterCard Credit
- MasterCard Debit
- American Express
- Diners Club
Once configured, the surcharge rates can be seen on the terminal under Menu > Surcharge Rates Surcharging will automatically be applied to all applicable Pay@Table transactions. Please see https://help.tyro.com/s/article/How-to-enable-surcharging for further information on how surcharge can be enabled on the Tyro terminal.
The surcharge amount applied to any transaction is returned in the Approved transaction response in the surcharge-amount field, and the POS is required to use the value from this field for reporting the surcharge amount on any receipts as well as the internal end-of-the-day POS reconciliation reports.
Integrated Tipping
The Tyro terminals have a built-in tipping workflow that can be enabled on the terminals, when enabled the terminals prompt the cardholder to specify the tip amount during the transaction workflow. There are two kinds of tipping on the Tyro terminals
- Manual Tipping - https://help.tyro.com/s/article/How-does-tipping-work-on-my-EFTPOS-terminal for more details
- Percentage Tipping - please see https://help.tyro.com/s/article/How-to-enable-percentage-tipping for more details
The cardholder has the choice to tip an arbitrary amount of their choice or a percentage of the transaction amount, any approved transaction that has a tip added onto it will return the tip amount in the tip-amount field in the approved transaction response. The POS is required to use the value from this field for reporting the tip amounts on any receipts as well as the internal end-of-the-day POS reconciliation and/or tip reports.
An example of a transaction carrying both a surcharge and a tip amount is given below:
Approved transaction carrying Tip and Surcharge amount
{
"approval-code": "000006",
"base-amount": "100.00",
"base-currency": "AUD",
"card-currency": "AUD",
"card-type": "Visa",
"elided-pan": "xxxxxxxxxxxx9521",
"issuer-action-code": "00",
"mid": "850",
"operator-id": "6",
"pan-length": "16",
"pos-reference": "MUCJBZDOG3",
"receipt-block": "
Pay@table test
123 test street
Sydney NSW 2000
MERCHANT COPY
Tyro Payments EFTPOS
NAB Visa Credit
AID: A0000000031010
Card: xxxxxxxxxxxx9521 (t)
Purchase AUD $100.00
Tip AUD $5.00
Sub-Total AUD $105.00
Surcharge AUD $0.50
----------
Total AUD $105.50
APPROVED 00
Table number: 0
Terminal ID: 437
Transaction Ref: 460033
Authorisation No: 000006
25 Jan 2021 at 04:52 PM
Retain copy for your records
Response time: .94 sec
",
"response-message": "APPROVED",
"result": "APPROVED",
"rrn": "102516460033",
"surcharge-amount": "0.50",
"table": "0",
"terminal-transaction-local-date-time": "20210125165211+1100",
"tid": "437",
"tip-amount": "5.00",
"transaction-amount": "105.50",
"transaction-currency": "AUD",
"transaction-reference": "460033",
"transaction-type": "purchase",
"transmission-date-time": "20210125055211+0000"
}Tyro Pay@Table Simulator
We have developed a test harness that POS vendors can use to develop and test their Pay@Table implementations with. The tool is a Java Command Line Interface (CLI) program that can generate the same messages that are generated by a terminal operating in Pay@Table mode.
The software archive is attached and instructions for use are contained within the archive.