Assembly Payments

Developer Portal

Welcome to the Assembly Payments developer portal. Here you’ll find comprehensive guides and documentation to help you start working with Assembly as quickly as possible, as well as support if you get stuck. Let's get started!

Platforms & Marketplaces Point of Sale

Auto Address Resolution / WSS

What is Automatic EFTPOS Address resolution?

Automatic EFTPOS Address Resolution is an optional configuration in your POS’s EFTPOS Settings screen.

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:

  1. Helps with recovery when the local IP address of an Eftpos changes due to underlying network circumstances
  2. 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 JavaScript WSS section below)

How does it work?

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.

Internet Requirement

The Auto Address Resolution feature requires internet access. However it is only used in the UNPAIRED 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.

If internet access is not available 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 to configure 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.

JavaScript 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 “” (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)


For existing POS installations upgrading to a new version that uses the auto-resolution, the auto-mode should be defaulted to being OFF. This is because older installations would not have had the concept of Serial-Number. To take advantage of this feature after the upgrade, the user would have to go to the settings screen and change the configuration accordingly. We recommend that the POS team tests upgrades scenarios properly to make sure the user experience is seamless.

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.