Web-based EFTPOS UI

In the case that the client library being used is the JavaScript library running in an internet browser HTTPS session, the client library will resolve the address to a fully qualified domain name, such as “328-467-291.z1.apdvcs.net” (instead of to an IP address).

This is required so the client library can use Secure WebSockets (WSS) to talk to the EFTPOS, thus preventing the browser from complaining about and blocking “mixed content”.

In this mode, the POS will need an internet connection because the operating system of the POS will use the public DNS system to resolve the fully qualified domain. (This could technically be worked around if the POS administrator could hardcode the mapping in the host operating system, for example in the traditional host's file)

🚧

UI Recommendation

This recommended UI is intended for browser-based POS, utilising Auto Address resolution.

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

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 and EFTPOS Serial Number is Entered
• Auto Address ticked
• EFTPOS Address populated when 'SAVE' button is triggered

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.

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 follow the underlying pairing process, we recommend displaying the following.

As the Pairing is initiated, the POS and terminal will begin the 'handshake'. At this stage both devices are handling the incoming keyRequest and have begun sharing the secrets.

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 finalise, '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.