A couple of options are available to help POS developers test their Pay@Table implementation:
- CLI test harness. A Java-based command-line interface test harness emulates the messaging between terminal and POS server. The software is distributed as a downloadable archive, with instructions for use included in the archive.
- Development terminal. Tyro can provide development terminals for up to 3 months. The terminal connects to Tyro's pre-production network and comes with a set of test cards. The development terminal processes transactions using these test cards with no actual financial effect.
All POS partners must pass Tyro's mandatory certification process before going into production with a Pay@Table integration. The certification process includes a testing component, which broadly involves:
- Providing the completed Tyro integration form and proof-of-functionality videos for the integration, once development and internal testing has concluded.
- Providing a sandbox version of the Pay@Table integration so Tyro can test it. Depending on the environment, platform and language used, the exact form this takes varies — specific instructions are provided at this stage by the Tyro Presales and Partner Support team member handling the project.
- Testing the integration, with regular feedback back to the POS partner for any issues that need addressing. The Tyro Certification Criteria determines feature eligibility for certification, barring any exceptions granted.
Once certification is complete, POS vendors can go into production. Tyro suggests running a pilot program before a broader release.
Pay@Table integration involves transmitting transaction requests and responses between the POS Pay@Table server and the Tyro terminal. This requires measures to ensure the validity and integrity of message contents. Tyro's Pay@Table protocol uses HMAC-SHA1 (HMAC using the SHA1 cryptographic hash function) to reasonably ensure that communication between the POS Pay@Table server and the Tyro terminal has come from the correct source and hasn't been modified in any way.
In simple terms, a Message Authentication Code (MAC) is a short piece of information used to authenticate a message.
MAC generation uses a MAC algorithm — sometimes called a keyed cryptographic hash function — which takes two inputs, a secret key and an arbitrary-length message to be authenticated, and produces a MAC as output. The MAC value protects both the message's data integrity and its authenticity, by letting verifiers who also possess the secret key detect any changes to the message content.
The MAC is sent along with the message to the receiver, who uses the secret key to generate a MAC from the received message and compares it with the MAC that was sent. If the two match, this confirms the validity and authenticity of the message.
The MAC algorithm adopted here is HMAC — a Hash-based Message Authentication Code, a secure MAC algorithm implemented across a wide range of programming languages, including .NET, Java and C.
Sample code for MAC generation using the SHA1 cryptographic hash function, in C# and Java:
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);- 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 doesn't apply to GET open sales and diagnostics requests sent by the Tyro terminal, since there's no message content in the HTTP request for the MAC to be calculated against — so no MAC is specified by the Tyro terminal in the
x-tyro-macrequest header for these requests. - The POS Pay@Table server, however, must calculate the MAC against the message contained in the response being returned to the Tyro terminal, and the terminal performs MAC verification to confirm the validity of that message.
- MAC verification therefore applies to all responses returned by the POS Pay@Table server to the Tyro terminal, since there's content to compute the MAC against in these cases.
- The MAC is provided to the receiving party as an HTTP header named
x-tyro-macin the HTTP request or response. - The receiving party must verify the message using the received MAC (in the
x-tyro-macheader) by computing the MAC for the received message using the process above, then comparing the computed MAC with the received MAC to confirm they're identical. - If MAC verification 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:
- 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.00.
- Received message: Approved transaction response message received
- Passphrase (secret):
p@ssphr@se - Generated MAC:
c6a578066f2b77c97261833bb47bebdc6b9717bf
Comparing the received MAC (e15c06852f355065ef2d044b0334fa14d43bd85d) with the generated MAC (c6a578066f2b77c97261833bb47bebdc6b9717bf) shows a mismatch, confirming that the message sent wasn't the one received — so the POS Pay@Table server returns a 403 HTTP status code to the Tyro terminal.
Table locking is a Pay@Table feature that lets access to tables opened on either the POS program or the Tyro terminal be locked down, so the other end can't access them while they're being accessed on one end. This means:
Tables being accessed, edited or modified on the POS program can't be pulled by the Tyro terminal through a GET open sales request — this is POS-side locking.
The sequence for this case:
- A stored open sale is opened on the POS program to edit the open sale.
- POS logic renders the table open on the POS as "unavailable" in the database.
- Attempting to pull the table with a table number that's open on the POS results in the Tyro terminal sending the GET open sales request.
- The POS Pay@Table server returns an HTTP 412 error code, along with the message the POS wants displayed on the Tyro terminal screen — up to ninety characters; longer messages are truncated to the first ninety. If no message is provided, the terminal displays a default message: "Table is unavailable at this time."
Tables open and ready to be closed on the Tyro terminal can't be edited or opened on the POS program until they're released by the terminal — this is terminal-side locking.
The sequence for this case:
- A stored open sale is opened on the Tyro terminal using the GET open sales request. This request needs
always-return-outcomeset totrue, to let the terminal participate in table locking. - The sale is successfully returned to the terminal and awaits the cardholder tapping, swiping or inserting their card to process the transaction.
- POS logic renders the table open on the terminal as "unavailable" in the database, so it can't be accessed on the POS until it's released by the terminal — i.e. a partial payment for the table is made, or the user releases the table on the terminal.
- Any attempt to access the table on the POS while it's open on the terminal results in the POS interface displaying a message that the table is currently open on the Tyro terminal.
- The POS can use the
CANCELLEDtransaction response returned by the terminal, once the table is released, to unlock the table for access on the POS.
- A stored open sale is opened on the Tyro terminal using the GET open sales request. This request needs
Table locking controls concurrent access to tables and prevents scenarios where table details are modified while the table is already open and being paid off on the terminal.
Tyro terminals have a built-in tipping workflow that can be enabled on the terminal. When enabled, the terminal prompts the cardholder to specify a tip amount during the transaction workflow. There are two kinds of tipping on Tyro terminals:
- Manual tipping — see How does tipping work on my EFTPOS terminal for more details.
- Percentage tipping — see How to enable percentage tipping for more details.
The cardholder can choose to tip an arbitrary amount or a percentage of the transaction amount. Any approved transaction with a tip added returns the tip amount in the tip-amount field of the approved transaction response. The POS must use that value when reporting tip amounts on receipts and in internal end-of-day POS reconciliation and tip reports.
An example of a transaction carrying both a surcharge and a tip 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"
}A Java command-line test harness is available for POS vendors developing and testing a Pay@Table implementation. It generates the same messages a terminal in Pay@Table mode would send.
The archive includes its own instructions for use.