Pay@Table Integration Specification

Document Status

Introduction

Pay@Table is a feature of the Tyro Payments system that allows direct integration with Point of Sale systems. Initially, Pay@Table was only implemented for the specific case of paying at the table in restaurants however due to the success of the method of integration, we have expanded it to support retail as well as restaurant locations. Pay@Table offers all of the benefits of Integrated EFTPOS without locking up Point of Sale (POS) workstations. With Pay@Table, the terminal 'pulls' the amount from the POS system rather than the POS system 'pushing' the amount to the terminal and waiting for the result. Transaction amounts are retrieved by the terminal from the POS system in real time and approved transaction results are reported back to the POS in real time allowing the POS to store detailed records of card payments.

The terminal offers 3 modes of Pay@Table; Restaurant, Restaurant & Bar, Retail. For restaurant transactions, the terminal also offers a split bill function allowing separate card payments (of any amount) to be made by individual patrons.

Pay@Table Modes

Pay@Table is offered in three different modes:

1. Restaurant mode: In restaurant mode, the terminal workflow asks the staff member to enter in their operator ID and table number. The terminal passes these values to the POS system and the POS system returns a list of (up to 100) open sales. Typically the POS server will return a single open sale however by allowing the POS system to return a list of open sales, the POS system can then optionally return a list of open sales by seat or a list of sub tabs. If more than one open sale is returned, the terminal will present the open sales in a list allowing the staff member to select the correct one. In restaurant mode, the terminal will offer the choice of paying the full amount or splitting the bill. If enabled the terminal will also offer tipping.
2. Retail mode: In retail mode, the terminal workflow asks the staff member to enter in their operator ID. The terminal passes this value to the POS system and the POS system returns a list of (up to 100) open sales. If more than one open sale is returned, the terminal will present the open sales in a list allowing the staff member to select the correct one. If enabled the terminal will also offer tipping.
3. Restaurant and Bar mode: In restaurant and bar mode, the terminal offers a combination of Restaurant and Retail modes. On the 'Enter table number' screen, the staff member can press the 'BAR' button to skip the table entry section and request the POS system to return the open sales based only on their operator ID. This mode is useful in the situation where Pay@Table is used in both in pay at table or pay at counter scenarios. Please note that if 'BAR' is pressed and the selected open sale contains a table parameter, then the terminal workflow will revert back to the restaurant workflow so that split billing can be offered.

Requirements for Point-of-Sale Systems

To implement Pay@Table, a number of prerequisites must be in place. specifically they are:

1. There must be a Wi-Fi access to the Local Area Network (LAN) in place inside at the business' premises for the Wi-Fi terminals to use - Please note that this applies only to LAN-based Pay@table integrations, Cloud-based Pay@table integrations are agnostic to terminal connectivity method (Wi-Fi, 3G).
2. The Wi-Fi network being used must be secured using WPA or WPA2 security.
3. The LAN must be adequately firewalled from the Internet.
4. The POS server must implement Tyro’s Pay@Table protocol (detailed below), which is a JSON over 5. HTTP protocol.

Pay@Table Communication Protocol

The communication protocol is based on sending JSON (JavaScript Object Notation) messages over HTTP. According to the JSON.org Web site, JSON is a lightweight data interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. JSON is also a text format that is completely language independent but is familiar for programmers in a wide variety of languages. For more information about JSON and sample implementations, please visit http://www.json.org.

The POS system needs to expose three URLs for the terminal to access:

1. A URL for the terminal to request open sales for a particular operator ID (and optional table number)
2. A URL for the terminal to post approved transaction results back to
3. A diagnostic URL for the purposes of establishing connectivity during installation and configuration

The terminal is Web server agnostic so that any programmable web server should be able to implement the communication protocol.

To ensure that the terminal can determine the authenticity of the message, the POS server must include a Message Authentication Code (MAC) as an HTTP header (with name x-tyro-mac). Please refer to Appendix A for details regarding how to generate the MAC for the message. The MAC requires that a secret passphrase be shared between the POS and the terminal. We require that a strong password be used that is unique to each location.

Cloud-Based Pay@table integrations

Tyro's Pay@Table supports Cloud-based Pay@table integrations as well for added convenience, ease-of-use, and scalability. The support for Cloud-based Pay@table extends the support for LAN-based Pay@Table POS integrations by supporting HTTPS for the threes URLs (described above) as well as including HTTP Basic Authentication. As an additional security measure, all communication between the terminal and the data centre hosting the POS is proxied via Tyro's data centres. This allows the POS to only accept Pay@Table requests from Tyro's IP ranges

The communication pathways and the information exchanged between the POS Pay@table server and the Tyro terminal for cloud-based Pay@table integrations is specified in the image below:

Requirements for Cloud-based Pay@table integration:

1. Each of the three URLs (open sales, transaction result, and diagnostics) must start with the https prefix.
2. Only a single set of username and password credentials must be used in the HTTP Basic Authentication i.e. not one per merchant but a single set of credentials per POS partner.
3. The password used for the HTTP Basic Authentication must be different to the one used for the validation of message MACs.
4. Any customer identifiers that you require to be included in the URLs must be in the host name or the resource section of the URL and not in the query string. I.e. customer identifiers must be to the left of the '?'

For example, an open sales URL that allows the POS to determine the customer might look like this: https://merchant-name.mypos.com/{company id}/{site ID}/open-sales?operatorId=2175&mid=1234&tid=5[&table=37]

To learn more, please refer to the next section