Non-web-based EFTPOS UI

This UI is intended for integrations on 2.8 and above.

Setting up of EFTPOS Settings UI

Somewhere in your POS, you need to provide a settings screen that allows your user to set up and check on the status of the EFTPOS name, connection and pairing. Below is the recommended UI for the EFTPOS setting screen, to assist with Pairing, Unpairing, Pairing flow and Idle Screens.

User Flow

The below flow diagram shows how the pairing UI should be designed and in which order these modals should be displayed.


For more in-depth information, please see the below document.

Unpaired Screen

In the unpaired state, there are a few requirements before the user can action the pair button. The few requirements are:

  • Payment Provider is Selected
  • POS ID, EFTPOS Serial Number and EFTPOS address are entered and validated
  • Test Mode button available for Sandbox/test environment only

PAIR button is only actionable when all fields have been entered.

Once all fields have been entered and registered, the Pairing process can be kicked off. To start, the pair button will trigger "Pair()" and start the communication between the POS and EFTPOS Terminal. During the process, the POS and Eftpos will generate secrets that will need to be stored in a secure location. This is typical with the rest of your application data.

Paired Screen

In this state, the EFTPOS terminal and POS are paired and connected. This will be the 'Idle' state for the in-store pairing screen. In this state, all fields are not editable and the unpair button is only actionable.


Paired and Connecting

You should always try to keep the connection open with the EFTPOS when in the PAIRED state. If you’re currently in the process of reconnecting, you should change your settings screen to reflect below. The Paired and Connecting screen should display the status, "Paired but trying to connect" or similar and allow the user to edit the IP Address field.


Notice: The IP address field is editable in this state

This screen will persist due to a number of reasons such as Network or communication issues between the EFTPOS terminal, POS application, and/or the Local Area Network (LAN) access point. At this stage, the user has the option to make changes to the IP address or Unpair the EFTPOS terminal. If the IP address is changed, this should push an update to the SPI config and update the EFTPOS address. If unpaired, refer to the UI below.

Unpairing Message

Actioning the "Unpair" button will cause the EFTPOS terminal and POS to unpair. The SPI Status will change to "Unpair" and the secrets exchanged during the pairing process will drop. At this stage, the UI should display a similar message to below, indicating to unpair on the terminal if remained paired. The Pairing screen UI will return to the Unpaired Screen.


Pairing Flow

When your user clicks the “PAIR” button on the settings screen, bring up a modal dialog to display progress to the user. Also, give them “CANCEL” button which when clicked, returns back to the Unpaired state. As you following the underlying pairing process, we recommend displaying the following.

While establishing the connection, display the following:


While negotiating secret keys, display the following:


When you receive the key_check from the EFTPOS, prompt the following message. The user is required to accept or decline the code on the EFTPOS Terminal to proceed to the next stage. This has changed from the previous versions of the in-store product, in an effort to reduce user actions.


If the user is to action "YES" on the EFTPOS Terminal the pairing flow will finalize, 'pair_response" will return successful and the SPI Status will be updated to "pairedConnected".

Display the following success message and then return to the settings screen in the Paired state.


If pairing fails at any point, or the user actions “NO” on the EFTPOS terminal, display the following error message and then return to the settings screen in the Unpaired state.