Set up SPI

Instantiate SPI and configure it with settings and pairing details.

Sample code

Take a tour of the code below, and copy it into your project to get started.

SPI’s settings

These are global settings that are set on startup — they do not change while the application is running.

posVendorId This must be your POS Application Name.
It is set by spi.SetPosInfo(...) during pairing.
posVersion The current version of your POS. You must increment this each time you release an update and therefore we recommend setting this dynamically so it is always up to date with the current version.
It is set by spi.SetPosInfo(...) during pairing.
deviceApiKey This secret key grants you access to use the SPI library. We will provide you with this key; however, if you do not have one, please contact us on your dedicated Slack channel or at [email protected]
It is set by spi.SetDeviceApiKey(...) during pairing.
countryCode The two-letter ISO 3166 country code that represents the country in which your company is based.
It is used for SpiClient.GetAvailableTenants(...) during setup.
secureWebSockets When enabled, the connection between the paired SPI and the EFTPOS terminal will be encrypted with a secret code for security. This option is enabled by default on secure connections and it is recommended that you set it to true
It is set by spi.SetSecureWebSockets(...) during pairing.
printMerchantCopy When enabled, the terminal will prompt to print the merchant receipt.
It is set by setting the value of spi.Config.PrintMerchantCopy during pairing.
promptForCustomerCopyOnEftpos When enabled, the terminal will prompt to print the customer receipt.
It is set by setting the value of spi.Config.PromptForCustomerCopyOnEftpos during pairing.
signatureFlowOnEftpos When enabled, signature transactions will be confirmed on the terminal instead of the POS.
It is set by setting the value of spi.Config.SignatureFlowOnEftpos during pairing.


The printMerchantCopy, promptForCustomerCopyOnEftpos, and signatureFlowOnEftpos features can only be used if supported by the EFTPOS terminal.

Pairing details

These are details that are to come from what the user inputs into the pairing form. They are variables that can change while the application is running.

posId This code identifies the EFTPOS terminal. It is a string set by the merchant who must ensure that they use a unique posId for each of their terminals. Note that only letters and numbers are allowed in this string.
It is set by spi.SetPosId(...) during pairing.
serialNumber The serial number of the EFTPOS terminal. Find this in Gecko Bank by clicking the Menu > Support > About this terminal and look for the Serial number.
It is set by spi.SetSerialNumber(...) during pairing.
eftposAddress The IP address of the network to which your EFTPOS terminal is connected. Find this in Gecko Bank by clicking the Menu > Support > Network test and look for the Local IP address.
It is set by spi.SetEftposAddress(...) during pairing.
autoAddressResolution When enabled, if the EFTPOS terminal's IP address changes (usually due to a network disconnection), SPI will try to find the new IP address automatically. This option is enabled by default on secure connections since it can fix some network issues automatically and it is recommended that you set it to true
It is set by spi.SetAutoAddressResolution(...) during pairing.
testMode When enabled, the auto-address resolution feature will use our online testing environment instead of our online production environment. (It is recommended to enable this when testing your integration.)
When the POS is in production mode, this option must be false; otherwise, it must be true by default.
It is set by spi.SetTestMode(...) during pairing.

Auto Address Resolution


Auto address resolution (AAR) is an internalized feature that figures out what the IP address of the terminal is and recovers the connection to the terminal when/if the terminal IP address changes.
The POS application requires the IP address of the Eftpos terminal (IP address/ FQDN) to pair and communicate with the Eftpos terminal.

Key Considerations:

  1. SPI JS Browser integrations, the POS must pair and recover using AAR via FQDN
    1. Users need to select a payment provider and enter their POS ID and serial number to initiate the pairing
  2. For All other SPI integrations, pairing works over a direct IP address
    1. Users need to select a payment provider and enter their POS ID, serial number, and IP Address to initiate the pairing
    2. Note: Payment provider selection and serial number value are not validated during pairing. If the wrong payment provider OR serial number has been entered, recovery won’t be possible.



A tenant is the bank or organisation that provides an EFTPOS terminal. The pairing form must allow the merchant to select their tenant from a list of tenants.

As a Point of Sale (POS) system, you are required to incorporate a dropdown menu that presents our list of available tenants/acquirers. This functionality enables you to select a tenant and assign a valid tenant code when you initiate the pairing process. To get an idea of what the user interface for this feature should look like, you can refer to the example provided here: Pairing UI

To retrieve the terminal address for pairing, we use the following format https://device-address-api.${tenantCode}${serialNumber}/${path}

Note: If the tenantCode is not on our supported tenant list, you will receive an ERR_NAME_NOT_RESOLVED error message.

To populate the dropdown menu, please call SPI.GetAvailableTenants(posVendorId, apiKey, countryCode). This call will return the current list of tenants from our server in the following format:

"TenantList": [
        code: 'cba', 
        name: 'CommBank Smart'
        code: 'gko', 
        name: 'Gecko Demo Bank'
        code: 'next', 
        name: 'Next Payments'
        code: 'till', 
        name: 'Till Payments'
        code: 'wbc', 
        name: 'Westpac Presto'

It is important to call this function every time before starting the pairing process, and not to permanently store the tenant list in your database. The tenant list is subject to change over time and it is crucial to make sure you have the most up-to-date list of providers for successful pairing. If you need to store the tenant codes, you can use local storage, which is demonstrated in our "Set up SPI" recipe here: Recipes.

In order to accommodate for Tenants who are in the pilot phase but not in production yet, we suggest manually adding an "Other" option to the dropdown select. This will allow the user to input their own tenant code if needed. This is especially helpful in case one of your Merchants is selected as part of the Tenants' pilot phase and needs to enter a custom tenant code that is not currently listed.

The pairing flow should work as follows:

  1. Select the payment provider (tenant) from the dropdown list box
  2. Enter POS ID
  3. Enter the terminal serial number
  4. Enter IP address
  5. Save all of the pairing config data
  6. Initiate the pairing
  7. You can find more info on this here: Pairing UI