Pay at Table

This page provides an explanation of mx51's Spice pay at table and how best to develop this integration feature.

'Pay at Table' is designed for hospitality/dining environments where the operator drives a transaction from the EFTPOS terminals. This differs from the regular integration method where the POS drives the transaction. In this mode, you have the ability to drive Pay at Table transactions but not regular integrations. It is recommended a separate PC runs the basic Spice integration if applicable.

How does it work?


The Spice application first needs to be changed into 'Pay at Table'. The Spice adaptor will handle all pairing and communication to the EFTPOS terminal, much like the regular Spice application. From here, Spice will require a 'Pay At Table Server' to communicate and retrieve the tables, so the operator can process the Pay at table flow from the EFTPOS terminal. Before this can happen, an operator will need to create a table on the POS and this needs to reflect in the table server.

📘

Example

The operator will create a table with 10 items, totalling $10.00. This will be saved in the table server. If a patron would like to pay, the operator of the establishment will use the terminal to action the 'Pay At Table' button on the EFTPOS terminal, and Spice will retrieve the tables from the table server. The user has the ability to:

  1. Pay in Full
  2. Split Even (#) i.e. Split in 4
  3. Split by Amount ($)

After the Operator has selected a payment option and payment has been made - Spice will update the bill and table with the transaction, and the Table server will receive the transaction response + outstanding bill.


Requirements

The Pay At Table will have a few requirements in order to function, please review the information below to get started.

  • Spice version 1.4.0 and above
  • Windows 8 or higher meeting minimum specifications ( Meeting the original system requirements )
  • Merchant Experience App v3.1.1 or higher
  • Spice Pay at Table app and POS's Pay At Table server are on the same system

Getting Started


In order for Spice to be operable in 'Pay At Table', we first need to update the spi.json file found in the directory. Before we edit the file, we must first close spice and all its processors.

To start lets:

  1. first open Task manager and kill all Spice Processors
  2. Navigate to the directory by going to the file location C:\Users\ [USERNAME] \AppData\Roaming\Spice OR enter %appdata%\Spice into the File Explorer address bar.
  3. Open the file 'spi.json' with any code editing tool
    Note: Any code editing tool can be used, including notepad.
  4. In the configuration file, we will edit the following lines in order to enable 'pat' mode:
{
"IntegrationMode": "pat",
"HeadlessTransactions": true,
"MultiTerminalMode": true,
}
  1. Once this is done, save the file and relaunch Spice.

Once Spice has been relaunched, it will start in Multi-pairing mode. Please refer to Multi Pairing for more information.


Spice Pay at Table UI


From the above changes, Pay at Table will look differently as it will start in headless mode. In headless mode, Spice will not automatically appear on startup. Instead, you will need to open Spice hidden in the taskbar by right-clicking the spice logo and clicking 'Spice'. When Spice first opens up, you'll be greeted with the terminal list page, and options to manage the terminals and pair.

To pair a new terminal up:

  1. Click '+ Pair New Terminal'
  2. Select correct Payment Provider
  3. Enter a POS ID (Alphanumeric + no spaces)
  4. Enter the POS IP address and initiate pairing.
    Repeat this process as many times as needed for each device.

Pay At Table version will include a new tab under 'Settings' as seen in the screenshot below. In the settings, we have the ability to enable 'Pay at Table' on the EFTPOS and a number of settings you can enable.

Pay At Table Settings are found in the Settings tab.Pay At Table Settings are found in the Settings tab.

Pay At Table Settings are found in the Settings tab.

Some of the settings to enable in [email protected] include:

  • Require Operator ID
  • Enable Table Retrieval
  • Equal Split Retrieval
  • Split by Amount enabled
  • Report Summary
  • Tipping enabled
  • Editing:
    • Pay At Table Label
    • Operator ID Label
    • Table Label

Spice will need to communicate to the POS to retrieve the tables and all the items on the table. In order for this to happen, Spice will require a 'table server' where all the tables and bills exist to retrieve. The table server should include:

  • table ID
  • Bill ID
  • Total Amount ($)
  • Outstanding Amount ($)

With all this information, we can proceed to create a number of tables with a bill + Amount ($) owing. Spice will give you the option to enable some validation and settings before proceeding to choose a table and payment method.


Development


Spice pay at table implementation requires the POS to implement HTTP APIs over JSON protocol. This protocol will be called by Spice to retrieve the table sales total and posting a payment against the table.

Below is a description of the endpoints to be used by Spice to implement Spice pay at table.

Operator ID

The Operator ID reflects the user ID entered in the POS. The operator should be numeric to support all types of EFTPOS devices, as some devices may not support alphanumeric characters. Enabling this in Spice will require the user to enter an operator ID in order to access the Pay At Table functionality on the terminal.

Retrieve list of Tables


When pay at table is triggered from EFTPOS terminal, a list of tables can be displayed on the terminal.

This is supported by GET /tables/{table_id}

http://localhost:8282/v1/tables/{table_id}

This is the response to the table request. The Table will return the table details.

{
    "tableId": "table-01",
    "label": "big table",
    "locked": false,
    "bill": {
        "billId": "bill-01012321",
        "tableId": "table-01",
        "totalAmount": 233.23,
        "outstandingAmount": 133.23
        }
}

Retrieve Bill for a Table


To retrieve the table and the bill related to the table

This is supported by GET /bills/{bill_id}

http://localhost:8282/v1/bills/{bill_id}

The response back from the Bill request will detail the Total amount, and outstanding amount to pair for the table.

{
    "billId": "bill-01012321",
    "tableId": "table-01",
    "totalAmount": 233.23,
    "outstandingAmount": 133.23
}

Make a Payment against a Bill


When a bill is ready to be settled, you can make a payment against a bill you retrieved for the table.

This is supported by POST /bills/{bill_id}

http://localhost:8282/v1/bills/{bill_id}

{
    "billId": "string",
    "tableId": "string",
    "operatorId": "string",
    "paymentType": 0,
    "purchaseAmount": 0,
    "tipAmount": 0,
    "surchargeAmount": 0,
    "purchaseResponse": { }
}
{
    "billId": "bill-01012321",
    "tableId": "table-01",
    "totalAmount": 233.23,
    "outstandingAmount": 133.23
}

A table with a bill can be partially paid off and remain open. The operator is required to stop the transaction process after completing the first transaction. This is reflected in the 'outstanding amount' of the payment response or when performing a GET/bill request.


Testing

When you have completed development, please refer to the Certification test suite for Pay At Table testing and our test suite. Once you have completed this, please notify the Integrations team via email or Slack to being the certification process.