Point-of-sale icon

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 an Enterprise EAP-PEAP profile

  1. Make sure you have the following certificates converted to .pem format:

    • CA root certificate. This must be the root certificate from the CA that signed the certificate of the RADIUS server that is part of your wireless network.
    • EAP intermediate certificate. This is optional, depending on your network infrastructure.

  2. Log in to your Customer Area.

  3. Switch to the merchant account or store that you want to configure a Wi-Fi profile for.

  4. Go to Terminal settings > Connectivity.

  5. Under Wi-Fi profiles select the + (plus) sign.
    The Wi-Fi Profile dialog opens.

  6. Complete the WI-FI SECURITY and WI-FI PROFILE settings:

    • Authentication type: select wpa_eap for a WPA Enterprise network or wpa2_eap for a WPA2 Enterprise network.
    • Name: name of the profile.
    • SSID: name of the wireless network.
    • Hidden SSID: indicates if a network doesn't broadcast its SSID. Mandatory for Android terminals, because these terminals rely on this setting to be able to connect to any network.
    • Default: select this checkbox if this is your preferred wireless network. The terminal will try connecting to that network first.

  7. Complete the EAP SETTINGS:

    • EAP: select peap. The applicable fields appear.
    • EAP Identity: EAP-PEAP username from your MS-CHAP account. Must match the configuration of your RADIUS server.
    • EAP Password: EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.
    • EAP CA Cert: upload 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.
    • EAP Intermediate Cert: upload the EAP intermediate certificate in .pem format.

  8. Complete the NETWORK SETTINGS, making sure they match your Wi-Fi infrastructure:

    • Channel: the recommended setting is auto.
    • BSS Type: the recommenced setting is infra.
    • Encryption: the recommended setting is ccmp.

  9. Select Save in the dialog.
    The profile is added.

  10. Optionally select the preferred Wi-Fi Band if your terminal supports both 2.4 GHz and 5 GHz. A terminal that supports both bands will connect to the 2.4 GHz band most of the time. If you want the terminal to connect to the less 'noisy' 5 GHz band, either select that here or disable 2.4 GHz on your network.

  11. Select Save at the bottom of the terminal settings page.

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:

  1. 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.

  2. For a new Enterprise EAP-PEAP or EAP-TLS Wi-Fi profile:

    1. Make sure 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.

  3. 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:

    In the request body, specify:

    • The general network settings:

      Parameter Data type Required 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.

    For an Enterprise EAP-PEAP Wi-Fi profile, use the following parameters:

    Parameter Data type Required Description
    authType String -white_check_mark- The type of Wi-Fi network. Use the value wpa-eap for a WPA Enterprise network, or wpa2-eap for a WPA2 Enterprise network.
    autoWifi Boolean Indicates whether to automatically select the best authentication method available. Does not work on older terminal models.
    bssType String -white_check_mark- Use infra for infrastructure-based networks. This applies to most networks. Use adhoc only if the communication is p2p-based between base stations.
    channel Integer Channel number of the Wi-Fi network. The recommended setting is 0 for automatic channel selection.
    defaultProfile Boolean Indicates whether this is your preferred wireless network. If true, the terminal will try connecting to this network first.
    eap String For authType wpa-eap or wpa2-eap. Use the value peap. (Other possible values: tls, leap, fast.)
    eapCaCert Object (file) For authType wpa-eap or wpa2-eap. The root certificate from the CA that signed the certificate of the RADIUS server that is part of your wireless network.
    eapIdentity String For authType wpa-eap or wpa2-eap. EAP-PEAP username from your MS-CHAP account. Must match the configuration of your RADIUS server.
    eapIntermediateCert Object (file) For eap peap. The EAP intermediate certificate.
    eapPwd String For eap peap. EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.
    hiddenSsid Boolean Indicates if a network doesn't broadcast its SSID. Mandatory for Android terminals, because these terminals rely on this setting to be able to connect to any network.
    name String -white_check_mark- Your name for the Wi-Fi profile.
    ssid String -white_check_mark- The name of the wireless network.
    wsec String -white_check_mark- The type of encryption. Possible values: auto, ccmp (recommended), tkip.

    The certificate file objects (eapCaCert and eapIntermediateCert) each consist of:

    Parameter Data type Description
    name String Name of the certificate. Must be unique across Wi-Fi profiles.
    data String Certificate content converted to a Base64-encoded string.
  4. 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:

  1. 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.

  2. 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:

  1. On the terminal, open the Admin menu and go to Network > Wi-Fi.
  2. Select the info icon for the network you are interested in.
  3. 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 can't 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 don't use ciphers from SHA1 and MDA5 groups.
  • Your RADIUS server supports the TLS 1.2 protocol or later.

See also