Set up SPI

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.

📘

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.

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.

Tenants

💡

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}.mspenv.io/v1/${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