Wi-Fi profiles

Manage the Wi-Fi configuration of your terminals from the Customer Area or with API calls.

To connect to your wireless network, the payment terminal needs to know certain network properties, depending on your type of Wi-Fi network. For example, the terminal needs to know basic properties such as the channel, password, and name of the network as well as advanced properties such as certificates for server validation and client authentication.
The terminal obtains the network properties through a Wi-Fi profile, which you can set up remotely either in the Customer Area or using API calls. The terminal receives and loads the remote Wi-Fi profile as part of the terminal configuration.

Wi-Fi network and profile types

Adyen payment terminals support the following Wi-Fi networks:

WPA type	Authentication	Cipher suite	Encryption
WPA-Personal	PSK	TKIP	RC4
WPA-Enterprise	EAP-PEAP, EAP-TLS	TKIP	RC4
WPA2-Personal	PSK	CCMP/TKIP	AES
WPA2-Enterprise	EAP-PEAP, EAP-TLS	CCMP/TKIP	AES

The network properties are supplied to the terminal in an SSID profile, which we refer to as the Wi-Fi profile. This can be a local profile or a remote profile.

Local Wi-Fi profile:
- Is managed locally on the terminal.
- Supports WPA Personal and WPA2 Personal networks. However, we recommend using a remote Wi-Fi profile.
- Doesn't support WPA Enterprise and WPA2 Enterprise networks.
Remote Wi-Fi profile :
- Is managed centrally. This allows you to:
  - Configure Wi-Fi settings in one place instead of on each individual terminal.
  - Implement changes in one place instead of on each individual terminal, for example when the PSK password or an EAP-PEAP certificate expires.
- Is mandatory for WPA Enterprise and WPA2 Enterprise networks.
- Also supports WPA Personal and WPA2 Personal networks.

Remote Wi-Fi profile types

You can set up the following remote Wi-Fi profiles:

Enterprise EAP-PEAP: a profile for WPA-Enterprise and WPA2-Enterprise networks using EAP-PEAP authentication. This type of authentication uses only server-side certificates.
Enterprise EAP-TLS: a profile for WPA-Enterprise and WPA2-Enterprise networks using EAP-TLS authentication. This type of authentication uses both server-side and client-side certificates. The authentication server of the Wi-Fi network validates the certificate of the Adyen-supplied payment terminal, and the terminal as Wi-Fi client validates the certificate of the authentication server. This makes it the most secure wireless network, but you need to manage more certificates.

Because of the technical complexities, the option to create this type of profile is only available on demand. Contact your Adyen account manager.
Personal PSK: a profile for WPA-Personal and WPA2-Personal networks using PSK authentication.

The account level where you need to configure your remote Wi-Fi profile depends on the network infrastructure architecture and the account structure in the Customer Area. For example, if there is a store-specific Wi-Fi network and the account is structured with stores, configure the remote Wi-Fi profile at the store level.

Set up Wi-Fi profiles in the Customer Area

You can set up remote Wi-Fi profiles in your Customer Area or using API calls. To use the Customer Area, select a tab below to see the instructions for the type of profile you want to set up.

Set up Wi-Fi profiles using API calls

Instead of using your Customer Area, you can use our Management API to automate setting up remote Wi-Fi profiles.

Wi-Fi profiles are considered sensitive settings because they affect the Terminal API communications. To manage Wi-Fi profiles, you need to have the following role:

Management API—Terminal Advanced settings read and write

Proceed as follows:

Optional. To see what remote Wi-Fi profile settings have already been configured, make a GET request to the /terminalSettings endpoint for the company account, merchant account, store or terminal, and check the wifiProfiles object.

When removing settings, you need to know the settings that will be inherited from the next higher level.
For a new Enterprise EAP-PEAP or EAP-TLS Wi-Fi profile:
1. Make sure that you have the required certificates:
  - The CA root certificate in .pem format. This must be the root certificate from the CA that signed the certificate of the RADIUS server that is part of your wireless network.
  - For EAP-PEAP: the EAP intermediate certificate in .pem format (optional).
  - For EAP-TLS: the client certificate for the terminals in .pem format and the client key in .pem or .key format.
2. Convert each certificate file to a Base64-encoded string.

To create or update a Wi-Fi profile, make a PATCH request to the /terminalSettings endpoint for the account, store, or terminal.

Use the following endpoints:

PATCH /companies/{companyId}/terminalSettings
PATCH /merchants/{merchantId}/terminalSettings
PATCH /stores/{storeId}/terminalSettings
PATCH /terminals/{terminalId}/terminalSettings

In the request body, specify:

The general network settings:

Parameter	Data type	Description
`band`	String	The preferred Wi-Fi Band, for use if the terminals support multiple bands. Possible values: All, 2.4GHz, 5GHz.
`roaming`	Boolean	Indicates if roaming is enabled on the terminals.
`timeout`	Integer	The connection time-out in seconds. Minimum value: 0

Specific parameters for each profile in the profiles array. For the parameters of different types of profiles, see the table below.

When you receive the response, note that this returns the entire configuration at the level where you made the request.

Load profiles on the terminal

First-time use

When you have set up a remote Wi-Fi profile and are going to use the terminal for the first time:

Set up a temporary internet connection on the terminal.

For the temporary connection, you can use the alternative connectivity options of the terminal (if any) such as Ethernet or 3G/4G cellular, or connect to a (Personal) Wi-Fi network that doesn't require a remote profile.
Board the terminal.

During boarding, the terminal retrieves its configuration including the Wi-Fi profile. The terminal then automatically reconnects to the internet using the network settings specified in the Wi-Fi profile.

Updates

An already-boarded terminal will receive a new Wi-Fi profile or changes to an existing Wi-Fi profile through the regular automatic maintenance call.

Because the Wi-Fi profile is part of the terminal configuration, you can also obtain it manually by downloading the latest configuration: on the terminal, open the Admin menu and select Config > Update.

Verifying

To check whether the terminal is using a remote Wi-Fi profile:

On the terminal, open the Admin menu and go to Network > Wi-Fi.
Select the info icon for the network you are interested in.
Check the Added field:
- via CA: a remote Wi-Fi profile from your Customer Area has been applied.
- local on device: the terminal is not using a remote Wi-Fi profile.

Manage changes using multiple-node Wi-Fi profiles

Over time, changes will occur in your wireless network:

Certificates are about to expire.
The EAP-PEAP username and password need to change.
The PSK needs to be reset.
You want to migrate to a different network, for example from a Personal network to an Enterprise network.

To manage such changes you can configure multiple Wi-Fi profiles or "profile nodes" for the same SSID. Each profile node for the SSID contains a different configuration. For example:

Profile node 1, which is the first profile you configured, contains the current certificates.
Profile node 2, which you configured next, contains the new certificates that will be needed when the current certificates expire.

The terminal tries to connect to the SSID using the available profile nodes one by one until it succeeds in establishing a connection. The next time the terminal tries to connect, as when rebooting or updating the software, it will start with the same profile node that it used for the previous successful connection.

If the terminal has established a connection, but the corresponding profile node fails, the terminal starts again trying to connect using the profile nodes one by one.

If a profile is outdated, you can remove it.

Know when certificates expire

To establish a safe Wi-Fi connection, Enterprise Wi-Fi profiles must include certificates for server validation and client authentication. When such a certificate expires, terminals cannot connect to the Wi-Fi network.

To prevent connection problems, you can prepare a new profile node with new certificates, as described under Manage changes. But to do this in time, it is important to know when the current Wi-Fi profile certificates expire. You can stay informed as follows:

Look up the expiry date and other details of uploaded EAP-PEAP and EAP-TLS certificates in your Customer Area under In-person payments > Terminal settings > Connectivity > Wi-Fi profiles.
Enable receiving emails before a certificate expires. We'll send an email 90, 60, 30, 7, and 3 days before the expiry date. To set this up:
1. In your Customer Area, go to In-person payments > Terminal settings > Connectivity > Wi-Fi profiles.
2. Enable Receive emails about expiring certificates.
3. Under Contact list, add one or more email addresses.
4. Select Save.

Security recommendations

PCI DSS sets requirements for secure cryptographic protocols. If you do not meet these requirements, payment terminals using EAP-TLS and EAP-PEAP Wi-Fi profiles will not be able to connect to your Wi-Fi network to process transactions.

To prevent Wi-Fi authentication failure, make sure that:

The size of RSA keys used by the Certification Authority is 2048 bytes or more.
You only use secure hash algorithms from the SHA2 and SHA3 family.
You do not use ciphers from SHA1 and MDA5 groups.
Your RADIUS server supports the TLS 1.2 protocol or later.