Auto address resolution

What is Automatic EFTPOS Address resolution?

Automatic EFTPOS Address Resolution is an optional configuration in your POS’s EFTPOS Settings screen for Web-based Integration and a feature that is internalized for Non-Web Based Integrations. Please refer to the Non Web-Based EFTPOS UI or Web-Based Integration for the User flow.

When turned on, the client library will automatically try to resolve the address of the EFTPOS based on the supplied Serial-Number.

Why is it useful?

Automatic Address resolution solves 2 problems:

Helps with recovery when the local IP address of Eftpos changes due to underlying network circumstances
https browser-based POSes will now be able to integrate with the Eftpos without any changes to the user’s operating system or browser settings. (see the Web-Based Integration WSS section below)

Requirements

Internet Requirement

The Auto Address Resolution feature requires internet access however, it is only used in the UNPAIRED and PAIREDCONNECTING state or if the client library thinks that the address might have changed. It is NOT used in the normal happy path operation. The POS is still required to persist the last known EFTPOS address and inject it into the client library at startup.

If internet access is not available:

before pairing the address will not be automatically filled in. The user will have to untick the auto box and enter it manually.
after pairing when the client library is trying to recover from an IP address change, the recovery will not be possible until the internet connection is available again, or until the user goes into the settings screen and changes the address manually.

📘
Advanced Recommendation
For advanced network setups, we still recommend configuring the local network router to reserve a static IP address for the EFTPOS terminal, and for the automatic setting to be left OFF. The EFTPOS should still be left in DHCP mode. It is the local network router that will always assign the same address to the EFTPOS. This configuration remains the most robust solution and does not require an internet connection.

Test Mode

There are two kinds of EFTPOS devices:

A. Test devices that only do test transactions with test cards and are typically only used while developing the integration
B. Production devices that work with real cards and make real transactions used by real merchants.

These two environments are totally segregated.

Since the auto-address resolution feature uses a service in the cloud, the client library needs to know whether it should connect to the sandboxed test environment or to the real prod environment to resolve the address.

For this purpose, a “Test-Mode” tick box is needed. It should always be turned off by default. It should only be turned on by POS testers who are testing against test EFTPOS devices. Real users of the POS system should never be able to change it. We recommend to hide this option for production users of your POS system.

Required Changes - Code
As part of the update there is a requirement to provide an additional argument when instantiating the library and some extra values as part of the DeviceAddressService class. These have been defined below:

Non Web-Based Integrations

📘
Auto Address Resolution
Auto Address Resolution is now maintained within the SPI library. POS will have the ability to pair over IP address.

Before pairing (i.e. in the UNPAIRED state), the address will automatically be resolved when the user clicks the Save button. After pairing, if the address of the EFTPOS changes due to a networking condition, the client library will detect this and update the address accordingly.

The SPI Client library will inform the POS code via a callback whenever the address is set/changed, so that the POS can persist it across restarts, together with the rest of the settings on this screen.

Triggering the Auto Address Resolution

A number of scenarios will trigger the SPI Client to obtain an IP address based on a provided serial number. These are good to understand when completing the development for the Auto Device Resolution. Please refer to Designing the UI for UI reference and design.

setTenantCode - In order for the SPI Client to obtain the IP address of the terminal, we must first set the environment of where the EFTPOS terminal exists.
SetSerialNumber - We Set the Serial Number of the device given.
SetEftposAddress - We Set the IP Address of the EFTPOS terminal.
SetTestMode - For every Tenant environment, there is a production and live environment. This will set the environment the device is in.

Web-Based Integrations - WSS

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 “329-319-594.z1.sandbox.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 hosts file)