Getting Started

This section is intended for point-of-sale (POS) software engineers looking to develop in-store EFTPOS integration using Spice Payments Adaptor. Spice is available for Windows-based POS and designed to be the simplest integration option but offers less UI flexibility compared to using the SPI library.

Spice Payments Adaptor

Spice is a Windows-based application that is installed on the POS PC and will drive transactions requested by the POS. The adaptor provides the ability to pair to the EFTPOS terminal and it maintains a persistent connection. Transactions are initiated from the POS by sending HTTP requests using JSON payload to the adaptor. The Spice transaction UI will then drive the transaction workflow and return the result and receipt to the POS.

Spice can be downloaded here.

Minimum PC Requirements:

  • 1.6 GHz or faster processor (32-bit or 64-bit)
  • Windows 7 or newer
  • 2 GB Ram
  • Internet connection (will function offline)

Architecture Diagram

Note: All messaging between the Point of Sale and Spice is via HTTP requests JSON payload.

API Documentation

To drive transactions the Point-Of-Sale must send HTTP requests.

The API specification for Spice is available here - https://code.mx51.io/spice-adaptor/

You can test sending HTTP requests to the Spice using Insomnia API through the following pre-defined commands.

Run in Insomnia}Run in Insomnia}

Once Insomnia is installed select "Use Localhost" from the Activate Environment dropdown. Then it's simply a matter of selecting an available GET or POST requests and clicking on "Send."

Features

Pairing: Pairing and connection to the EFTPOS terminal is managed by the adaptor.

Transaction Support: Purchase, Refund and MOTO with support for Cash-out, Tipping and Surcharging.

Receipt Printing Configuration: Receipt printing can be configured to be performed by the EFTPOS machine or POS printer.

Settlement: Sending a settlement instruction to the EFTPOS terminal is possible from within the adaptor. The settlement report will be displayed after the settlement is completed.

Settlement Inquiry: Sending a settlement inquiry to the EFTPOS terminal is possible from within the adaptor. The settlement inquiry report will be displayed after the settlement is completed.

Transaction Receipt Logs: The last ten transaction receipts are displayed for the user to view.

Light & Dark Mode: To help the transaction dialog blend into the POS UI a light and dark UI skin can be selected.

Auto close transactions: It's possible to turn on or off automatic closing of the transaction dialog, or to set a 2 second delay.

Steps to integrate

  1. Obtain an mx51 test terminal through your mx51 contact.

  2. Once you have the terminal connect it to the same local network as the PC. Instructions can be found here.

  3. Install the Spice Adaptor. Downloaded here.

  4. Open Spice and enter the IP address of the EFTPOS terminal. First, select "Pair with POS" on the EFTPOS terminal and then "Pair" in Spice. Once pairing negotiation is complete click yes to confirm the code on the EFTPOS terminal, and then click on enter. Finally, click on the OK button in Spice. The EFTPOS terminal and Adaptor are now paired.

  5. Use the API specification to implement the HTTP requests to Spice. When running the Adaptor it will listen on localhost:8282.

Sample Habanero POS

To demonstrate how Spice functions a sample C# open-source POS has been provided. This sample is named Habanero POS and can be used to drive transactions and settlements to Spice.

Habanero POS is available here.

Getting in touch

If you would like to get in touch with a team member, please send us an email at [email protected] and we will do our best to assist you.