# Specification ## Overview Pay@Table is a feature of the Tyro Payments system that allows direct integration with point-of-sale systems. It was originally built for paying at the table in restaurants, but its success led to it being expanded to support retail locations as well. Pay@Table offers all the benefits of integrated EFTPOS without locking up POS workstations: the terminal "pulls" the amount from the POS system rather than the POS "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, letting the POS store detailed records of card payments. The terminal offers three modes of Pay@Table: Restaurant, Restaurant & Bar, and 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.** The terminal workflow asks the staff member to enter 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 returns a single open sale, but by allowing the POS system to return a list, the POS system can optionally return open sales by seat or as a list of sub-tabs. If more than one open sale is returned, the terminal presents the open sales in a list so the staff member can select the correct one. In restaurant mode, the terminal offers the choice of paying the full amount or splitting the bill, and will offer tipping if enabled. 2. **Retail mode.** The terminal workflow asks the staff member to enter 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 presents the open sales in a list so the staff member can select the correct one. The terminal will offer tipping if enabled. 3. **Restaurant & 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 table entry and request the POS system to return open sales based only on their operator ID. This mode is useful where Pay@Table is used for both pay-at-table and pay-at-counter scenarios. If **BAR** is pressed and the selected open sale contains a table parameter, the terminal workflow reverts to the restaurant workflow so that split billing can still be offered. ## Requirements for point-of-sale systems To implement Pay@Table, a number of prerequisites must be in place: 1. Wi-Fi access to the Local Area Network (LAN) must be available at the business's premises for the Wi-Fi terminals to use. 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 HTTP protocol. ## Pay@Table communication protocol The communication protocol is based on sending JSON (JavaScript Object Notation) messages over HTTP. JSON is a lightweight, language-independent data interchange format that's easy for both humans and machines to read, write, parse and generate. For more information about JSON and sample implementations, see [json.org](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 establishing connectivity during installation and configuration. The terminal is web server agnostic, so any programmable web server should be able to implement the communication protocol. To let the terminal determine the authenticity of a message, the POS server must include a Message Authentication Code (MAC) as an HTTP header named `x-tyro-mac`. See [Generating and verifying Message Authentication Codes](/docs/in-person-payments/pay-in-person/features/pay-at-table/testing#generating-and-verifying-message-authentication-codes) for how to generate the MAC. The MAC requires a secret passphrase shared between the POS and the terminal — use a strong password that's unique to each location. ## Cloud-based Pay@Table integrations Tyro's Pay@Table also supports cloud-based integrations, for added convenience, ease of use and scalability. Cloud-based Pay@Table extends LAN-based Pay@Table POS integrations by supporting HTTPS for the three URLs described above, as well as [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_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](https://www.tyro.com/selftest/). The communication pathways and information exchanged between the POS Pay@Table server and the Tyro terminal for cloud-based Pay@Table integrations are shown below: ![Cloud-based Pay@Table integration](/assets/paytable-cloud-based.99f7d30fc476af03efdf08951f565805118146dcc63c1a875306d51d564cd702.68286485.jpg) ### Requirements for cloud-based Pay@Table integration 1. Each of the three URLs (open sales, transaction result, diagnostics) must start with the `https` prefix. 2. Only a single set of username and password credentials must be used for HTTP Basic Authentication — one set of credentials per POS partner, not one per merchant. 3. The password used for HTTP Basic Authentication must be different from the one used for MAC validation. 4. Any customer identifiers required in the URLs must be in the host name or the resource section of the URL, not in the query string — i.e. customer identifiers must sit 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] ``` Continue to [LAN-based integration](/docs/in-person-payments/pay-in-person/features/pay-at-table/lan-based).