Getting started

The place to start when integrating to mx51's POS solution.

This site is intended for point-of-sale (POS) software engineers looking to develop mx51's in-store payments integration using the Simple Payments Integration library.

Below are a number of resources that outline how to technically integrate POS products to EFTPOS terminals using the SPI Library from mx51.

These contain all the required information to implement the integration including documentation, guides, development tools, and API references.


Working examples

mx51 have taken a living documentation approach when it comes to supplying development resources. What this means is that we provide working code in the form of sample POS is a number of different software languages so developers can gain an understanding of how the integration works. It is recommended that you start by familiarising yourself with the JavaScript sample POS as an introduction and then move to your desired technology.

This is available here: JavaScript Sample POS

Pair, unpair, make a few purchases, complete a settlement and get a feel for how it all works.

If you're planning on integrating Pay at Table you can use our sample Table POS

Development test terminal

In order to use the examples above you'll need to use a physical EFTPOS terminal. The terminal can be paired with the POS using either the terminal IP Address or be using Auto Address Resolution.

The terminals supplied run the same software as production terminals but without a connection to a live payment environment. Each terminal can connect via Wi-Fi or Ethernet, and comes with a Bluetooth charging base and test card for transactions. If you don't have a terminal please contact your Integration Engineer.

More: Test Terminal & Guides

Integrated feature list

The available mx51 in-store integration features are explained here. They are split into required and optional functionality.


Libraries and reference POS

mx51 provides a set of integration libraries and command line POS examples for developers. The libraries are designed to remove the complexity from integration development. The libraries are available for .NET, Java, iOS, and JavaScript.

A valid deviceAPIKey is required for pairing. Reach out to your mx51 Contact if you have not been provided with a deviceAPIKey.

Below are code samples in each language that are required to instantiate the Simple Payment Interface (SPI):

var spi = new Spi(posId, eftposAddress, spiSecrets);
// It is ok to not have the secrets yet to start with.

// Called when pairing status changes.
spi.StatusChanged += OnStatusChanged;

// Called when secrets are set, changed or voided.
spi.SecretsChanged += OnSecretsChanged;

// Called throughout to pairing process to update us with progress.
spi.PairingFlowStateChanged += OnPairingFlowStateChanged;

// Called throughout to transaction process to update us with progress.
spi.TxFlowStateChanged += OnTxFlowStateChanged;

spi.Start();
Spi spi = new Spi(posId, eftposAddress, spiSecrets);
// It is ok to not have the secrets yet to start with.

// Called when pairing status changes.
spi.setStatusChangedHandler(new Spi.EventHandler<SpiStatus>() {
  @Override
  public void onEvent(SpiStatus value) {
    ...
  }
});

// Called when secrets are set, changed or voided.
spi.setSecretsChangedHandler(new Spi.EventHandler<Secrets>() {
  @Override
  public void onEvent(Secrets value) {
    ...
  }
});
        
// Called throughout to pairing process to update us with progress.
spi.setPairingFlowStateChangedHandler(new Spi.EventHandler<PairingFlowState>() {
  @Override
  public void onEvent(PairingFlowState value) {
    ...
  }
});

// Called throughout to transaction process to update us with progress.
spi.setTxFlowStateChangedHandler(new Spi.EventHandler<TransactionFlowState>() {
  @Override
  public void onEvent(TransactionFlowState value) {
    ...
  }
});

spi.start();
var spi = new Spi(posId, eftposAddress, spiSecrets, log); 
// It is ok to not have the secrets yet to start with.

// Called when pairing status changes.
document.addEventListener('StatusChanged', (e) => ...);

// Called when secrets are set, changed or voided.
document.addEventListener('SecretsChanged', (e) => ...);

// Called throughout to pairing process to update us with progress.
document.addEventListener('PairingFlowStateChanged', (e) => ...);

// Called throughout to transaction process to update us with progress.
document.addEventListener('TxFlowStateChanged', (e) => ...);

spi.Start();
var spi = SPIClient()

spi.posId = posId;
spi.eftposAddress = eftposAddress;
spi.setSecretEncKey(encKey, hmacKey: hmacKey)
// It is ok to not have the secrets yet to start with.

spi.delegate = self

spi.start()

// Your class must implement this delegate.
extension ViewController: SPIDelegate {

  // Called when pairing status changes.
  func spi(_ spi: SPIClient, pairStateChanged 
           state: APSpiState) {
    ...
  }
  
  // Called when secrets are set, changed or voided.
  func spi(_ spi: SPIClient!, secretsChanged secrets: APSecrets?, 
           state: SPIState!) {
    ...
  }
  
  // Called throughout to pairing process to update us with progress.
  func spi(_ spi: SPIClient, pairingFlowStateChanged state: SPIState) {
    ...
  }
  
  // Called throughout to transaction process to update us with progress.
  func spi(_ spi: SPIClient, transactionFlowStateChanged state: SPIState) {
    ...
  }
  
}

More: Libraries and Reference POS


The paring user interface

mx51 provides a User Interface page for you to use as a reference when designing pairing screens. This page includes examples of the basic functionality that will need to be implemented. Please follow the UI requirements closely.

More: Designing The Pairing User Interface


Transaction workflow & user interface

This page outlines the workflow of a transaction and presents a set of UI recommendations to display to the user. You should look at this page to understand the role of libraries and their required inputs and expected outputs.

More: Transaction Workflow