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 “803-098-987.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 hosts file)

Upgrading

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.

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:

To receive an apiKey please contact your Assembly contact

Triggering the Auto Device 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:

SetSerialNumber - When unpaired, if the serial number changes, the library will resolve the device address.
SetAutoAddressResolution - When paired and disconnected, if auto address resolution is enabled, the library will resolve the device address.
SetTestMode - When unpaired, toggling the test mode will resolve the device address.
Disconnection - When disconnected the library will try and re-connect - When disconnected, the mode will switch to PairedConnecting and if auto address resolution is enabled and the number of retries (normal reconnect) is more than 5, the library will resolve the device address and try to re-connect.

Auto Address Resolution / WSS


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.