Getting started

Sample Application

mx51 has 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 in a number of different software languages so developers can gain an understanding of how the integration works. It is recommended that you start by familiarizing 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.

Test Terminal & Guides

Integrated Features

The available mx51 in-store integration features are explained here. The features are categorised into:

Supported
Transactional
POS driven
Terminal driven

API - Libraries and Code Sample

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

Designing the UI

mx51 provides a recommended 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:

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