Handbook

In-Store Applications

Merchant Experience App (MXA)

The MXA is an application that runs on a payment terminal. MXA stands for Merchant Experience App.

The MXA implements the end-to-end user experience for the payment terminal (except for the part that actually reads the payment card and executes the transaction). Functionality includes:

  • Taking standalone transactions of various types, for example purchase, refund, pre-auth, etc.
  • Transaction listing and settlement triggering
  • Terminal activation experience – facilitates the CX when the merchant receives the terminal
  • Help and troubleshooting
  • Integrates with the underlying card payment application
  • Communicates with mx51’s backend for reporting, management, configuration and other functionality facilitated by the backend (RTM)
  • Accepts POS integration software for payments including for pay-at-counter and pay-at-table experience

The MXA is white-labelled for mx51 tenants. When onboarding a new tenant, branding and configuration is set up for that tenant.

mx51 has built two lines of MXAs:

  • Classic – Written in C++ for the Verifone VX690 and e355 terminals. This version is currently supported and maintained as legacy.
  • Next-Gen – Forward looking version built for Android devices and written in Kotlin using the Jetpack Compose framework. CI/CD happens on GitHub. There is typically a different build for each tenancy and environment.

A tenant build is supplied to the tenant’s terminal management system (TMS) for official deployment onto the tenant’s payment terminal fleet. Different TMS’ have their own unique ways for release management that in most cases involve manual steps to digitally sign a build.

The MXA used to be known as the VAA (Value-Added Application).

POS Integration Software

mx51 builds and maintains client integration software that allows Point of Sale (POS) vendors to integrate their software with the MXA. This software is built and maintained by the In-store Integrations squad.

At the highest level, the integration software comes in two flavours:

In-store POS integration works over the Local Area Network (LAN). The MXA acts as an HTTP server that listens on LAN interfaces. The POS needs to connect to the MXA by being an HTTP client. The HTTP connection is upgraded to a long-lived Websocket connection. Messages are exchanged over this connection both ways. Messages are defined by the mx51 proprietary SPI protocol, which also provides application level encryption of the exchanged messages.

The POS addresses the MXA by IP address in most cases. Browser-based POS software is a little different just in this regard as it addresses the POS using an FQDN (Fully Qualified Domain Name) instead of IP address, and uses HTTPS, instead of HTTP, so as to keep the browser happy.

Additionally, a mechanism called Device Auto-Address Resolution was internally designed and built for the purpose of obtaining the IP address or FQDN of a device knowing its Serial Number (S/N). This mechanism is facilitated via the backend so that the POS, knowing the S/N of a payment terminal, can find out the IP or FQDN directly from the backend. The mechanism is especially handy for automatically recovering on the rare occasion when the IP address of a payment terminal changes over time.

SPI Protocol

The SPI protocol defines the structure of the messages exchanged between the SPI Client on the POS side and the SPI Server being the MXA running on the payment terminal. The SPI acronym stands for Simple Payments Integration.

SPI messages are structured using JSON (JavaScript Object Notation). mx51’s SPI Committee is in charge of maintaining the SPI protocol.

At a high level there are two purposes of messages that are exchanged:

  • Functional messages – to do integrated transactions, for example, or to retrieve a bill
  • Non-functional – for creating and maintaining a secure connection, for example for the pairing process

One of the hardest aspects of this protocol is maintaining backwards compatibility such that a newer version of the MXA serving a later version of the SPI protocol can still serve POS clients using older versions of the SPI protocol without breaking expectations. This is important because it takes time for POS vendors to upgrade their integration to use newer SPI versions, and even more time for merchants to update the POS software in their stores. The SPI committee meticulously considers any changes to the protocol.

Pairing Process

The pairing process is the process through which a POS is paired with a payment terminal so that integrated functionality can be leveraged.

During the pairing process, an encryption and signing key are agreed between both sides using the Diffie-Hellman algorithm such that the keys themselves never cross the wire, to avoid listening attacks.

These keys are then used to encrypt and sign any further messages between the pair. The pairing process typically only happens once during the lifetime of the pair. Additionally, every week, the encryption and signing keys are automatically rotated through a mechanism on the SPI protocol.

The merchant is able to go through the pairing process themselves using the GUI on the POS and the one on the MXA. The user is shown part of the signature on both sides and needs to confirm that they match. This ensures that there was no man-in-the-middle during the pairing.

SPI Client Libraries

mx51 builds and maintains a SPI client library that the POS vendor embeds in their own software. It takes care of implementing the SPI protocol and adds robustness around edge cases and network issues.

The library provides functions to interact with the payment terminal, but does not provide any graphical user interface (GUI). The POS vendor is expected to implement the GUI necessary to perform the pairing process and functional interactions.

Four lines of this library are currently maintained, to cater for different programming languages that POS software can be built in, namely:

  • .NET – Written in C#, caters primarily to Windows-based POS software written in .NET
  • Java – Caters to POS software written in this language, including Android
  • JavaScript – Caters to browser-based POS as well as other POS software written in this language
  • iOS – Written in Objective-C, caters to POS written as native iOS apps

Spice for Windows

The Spice software, written as an ElectronJs application, runs as its own program. It implements the GUI necessary to interact with the terminal, and it is minimized in the system tray. The POS software invokes it by using HTTP requests. Spice starts an HTTP server that listens on the localhost interface. An HTTP API is provided for POS software developers that triggers the Spice software to initiate transactions and interact with the payment terminal. Under the hood, Spice itself uses the JavaScript SPI client library to interact with the terminal

Spice is meant to run on the same machine that is running the checkout POS software, but in some configurations it can run in the back-office of the merchant premises, in which case transactions happen in “headless mode”, i.e. without needing to invoke the graphical user interface during the transaction.

Spice is preferred as a method of integration because it simplifies the integration process, and also makes the integration more maintainable. The Spice software can be self-updated over the wire.

Some POS vendors, given the choice, may still prefer to use the SPI Client libraries over Spice if they are after a more native and embedded checkout experience user interface.

Spice could also run on MacOs and Linux based environments, but so far this has not been leveraged.

Reverse Integrations

In rare cases, a POS vendor will require mx51 to integrate to their requirements and specifications. These are called reverse integrations and so far there are two instances of them:

  • Oracle – Integration is still achieved using Spice, with an additional layer on top that conforms to Oracle’s Payment API Specifications known as OPI and SPI (unfortunate name clash). Symphony and Opera are two of Oracle’s POS software.
  • Vend – Integration is achieved using the JavaScript SPI client library wrapped in an HTML iframe that conforms to the Vend specification

Supported In-Store Architectures

Every POS software and indeed merchant will have their own in-store architecture and technology layout. To help with initial discussions and a consistent approach, a list of blueprint in-store architectures is maintained.

It details various configurations such as one-POS-to-many-terminals, many-POS-to-one-terminal, Spice vs. Libraries, Pay-at-Table vs. Pay-At-Counter, etc.

POS Integration and Certification Process

When a POS vendor signs a partnership agreement with mx51, the In-store Integration Support squad helps the POS developers with the technical integration, providing documentation and support. A certification test-suite is provided for the POS vendor to go through before submitting for official certification. The Integration Support squad then tests and certifies the submitted software.

Support documentation and tutorials for in-store integrations can be found at developer.mx51.io.

RTM

RTM stands for Real-time Terminal Monitoring and Management and refers to the underlying capability to communicate remotely with the payment terminals and to all the functionality that can be delivered on top of that capability.

The MXA maintains a long lived connection with the Device Gateway component in the cloud. Backend uses private/public keys and signatures checks to register and authenticate MXA. The RTM connection is kept up all the time as long as the MXA is running and it has internet connectivity.

RTM delivers the following functionality:

  • Device Registration Mechanism and other lifecycle processes
  • Reporting of any metrics and events that happens on the device including over the POS integration
  • Reporting of transactions
  • Exchanging and updating of configuration
  • Coordination of execution of non-card transactions through the cloud, also known as alt-payments

The RTM protocol is managed by the RTM committee. RTM messages are in the form of JSON and at a high level it is a 2-way RPC protocol.

Patent Protected

The mx51 in-store solution is unique and we have a patent pending in Australia, Canada, Europe and the United States.