---
title: "Bluetooth beacons"
description: "Use beacons to have your mobile POS app automatically connect to the nearest terminal."
url: "https://docs.adyen.com/point-of-sale/design-your-integration/network-and-connectivity/set-up-beacons"
source_url: "https://docs.adyen.com/point-of-sale/design-your-integration/network-and-connectivity/set-up-beacons.md"
canonical: "https://docs.adyen.com/point-of-sale/design-your-integration/network-and-connectivity/set-up-beacons"
last_modified: "2020-10-07T09:04:00+02:00"
language: "en"
---

# Bluetooth beacons

Use beacons to have your mobile POS app automatically connect to the nearest terminal.

[View source](/point-of-sale/design-your-integration/network-and-connectivity/set-up-beacons.md)

Our Bluetooth terminals use the [iBeacon protocol](https://developer.apple.com/ibeacon/) to advertise their presence to other nearby Bluetooth devices, such as a mobile POS app. You can use the advertised data to make sure that the POS app discovers the closest terminal and uses its unique identifiers to correctly route Terminal API requests.

## Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

| Requirement          | Description                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Integration type** | A [Terminal API integration](/point-of-sale/basic-tapi-integration/) with payment terminals.          |
| **Limitations**      | The beacon functionality is not supported for Android terminals and unattended non-Android terminals. |
|                      |                                                                                                       |

## Advertised values and integration types

The terminal advertises values using the [iBeacon protocol](https://developer.apple.com/ibeacon/) so your mobile POS app can recognize the closest terminal. You define the following values when you [set up beacons in your Customer Area](#set-up-beacons-in-your-customer-area):

* **UUID**: a Universally Unique Identifier consisting of 32 hexadecimal digits.
* **Major**: a decimal value between 0 and 65535.
* **Minor**: a decimal value between 0 and 65535.

The [Major and Minor values](#placeholders-for-the-major-and-minor) are set up to encode the terminal data needed for routing: the **serial number** for cloud-based communication, or the **IP address** for local communication.

After you set up beacons, the specific terminal detail you need to retrieve from the advertised Major and Minor values depends on your [integration architecture](/point-of-sale/design-your-integration/choose-your-architecture#local-communications):

* [Cloud communications](#cloud-based-communication)
* [Local communications](#local-communication)

## Set up beacons in your Customer Area

To enable the beacon functionality and set your values for the **UUID**, **Major**, and **Minor**:

1. Log in to your [Customer Area](https://ca-test.adyen.com/).

2. Go to **In-person payments** > **Terminal settings**, or first go to the merchant account, store, or individual terminal where you want to set up beacons and then go to the terminal settings.

3. Go to the **Connectivity** tab.

4. In the **Beacon** section:

   1. For **Enable beacons** select **Enabled**.
   2. Set **UUID** to the Universally Unique Identifier that you want to use. You can generate a UUID using an online tool, for example [uuidgenerator](https://www.uuidgenerator.net/).
   3. Set **Major** and **Minor** to the values that you want to use. You are free to choose your own values, or [use our placeholders](#placeholders-for-the-major-and-minor).

5. Select **Save** at the bottom of the page.

### Placeholders for the Major and Minor

You can use our placeholders to dynamically encode either the serial number or the IP address of the terminal into the Major and Minor, depending on whether you are using cloud or local communications.

* Encode the **serial number** of the terminal if you are using [cloud communications](#cloud-based-communication):

  |           |            |
  | --------- | ---------- |
  | **Major** | ${SERIALH} |
  | **Minor** | ${SERIALL} |

  To learn how to decode the advertised data, see [Get the serial number](#get-the-serial-number).

* Encode the **IP address** of the terminal if you are using [local communications](#local-communication). Here, the placeholder also depends on your network interface. For example, if you are using the first Ethernet interface, set **Major** to **${IPH:ETH0}**, and **Minor** to **${IPL:ETH0}**.

  |           |             |             |              |              |              |
  | --------- | ----------- | ----------- | ------------ | ------------ | ------------ |
  | **Major** | ${IPH:ETH0} | ${IPH:ETH1} | ${IPH:WLAN0} | ${IPH:WLAN1} | ${IPH:GPRS0} |
  | **Minor** | ${IPL:ETH0} | ${IPL:ETH1} | ${IPL:WLAN0} | ${IPL:WLAN1} | ${IPL:GPRS0} |

  To learn how to decode the advertised data, see [Get the IP address](#get-the-ip-address).

## Use beacons with cloud communications

With [cloud communications](/point-of-sale/design-your-integration/choose-your-architecture#cloud-communications), a Terminal API request is routed to the correct terminal based on the unique terminal ID, the `POIID`, which you pass in the request.

`POIID` = *\[Terminal model] - \[Serial number]*, for example **P400Plus-324688179**.

After you have [set up beacons in your Customer Area](#set-up-beacons-in-your-customer-area), route your Terminal API requests as follows:

1. [Get the serial number from the Major and Minor](#get-the-serial-number). You can use [our placeholders](#placeholders-for-the-major-and-minor) to have the terminal advertise its serial number, encoded into the Major and Minor.

2. Get the full `POIID`:

   1. Make a POST [`/connectedTerminals` ](/point-of-sale/diagnostics/check-cloud-connection#use-an-api-call)request to find the terminals under a company account, merchant account, or store.\
      The response lists the POIIDs.
   2. In the response, look up the `POIID` by searching for the serial number you retrieved in Step 1.

3. Send your Terminal API request using the correct `POIID` retrieved in Step 2.

### Get the serial number

If you set **Major** to **${SERIALH}** and **Minor** to **${SERIALL}**, the terminal advertises its serial number, encoded in the Major and Minor. For example, the serial number 324688179 is advertised as:

* **Major**: 4954
* **Minor**: 22835

To get the serial number from the advertised values:

1. Convert the Major and the Minor into hexadecimal:

   * hex (4954) = 135A
   * hex (22835) = 5933

2. Concatenate the values, with the Major corresponding to the high bits, and the Minor corresponding to the low bits:
   * 135A5933

3. Convert the resulting value into decimal:
   * dec(135A5933) = 324688179

## Use beacons with local communications

With [local communications](/point-of-sale/design-your-integration/choose-your-architecture#local-communications), a Terminal API request is routed to the correct terminal based on:

* The unique terminal ID, the `POIID`, which you pass in the request message.
* The IP address of the terminal.

After you have [set up beacons in your Customer Area](#set-up-beacons-in-your-customer-area), route your Terminal API requests as follows:

1. [Get the IP address from the Major and Minor](#get-the-ip-address). You can use [our placeholders](#placeholders-for-the-major-and-minor) to have the terminal advertise its IP address, encoded into the Major and Minor.

2. Get the `POIID`. For this, you should use your own mapping from the IP address to the `POIID`. To populate this mapping dynamically:

   1. [Make a diagnosis request](/point-of-sale/diagnostics/request-diagnosis) with a dummy `POIID` (for example, `V400m-123456789`).
   2. Extract the actual `POIID` of the terminal from the response and update your mapping.

3. Send your Terminal API request using the correct `POIID` to the IP selected in step 1.

### Get the IP address

You can use our placeholders to have the terminal advertise its IP address, encoded in the Major and Minor.

For example, the IP address 192.168.47.95 is advertised as:

* **Major**: 49320
* **Minor**: 12127

To get the IP address from the advertised values:

1. Get the high 16 bits of the IP address from the Major:

   1. Convert the Major to hexadecimal:
      * hex (49320) = C0A8
   2. Convert the high bits of the result to decimal:
      * dec(C0) = 192
   3. Convert the low bits of the result to decimal:
      * dec (A8) = 168
   4. Combine the results of steps b. and c. to get the high 16 bits of the IP address:
      * 192.168

2. Get the low 16 bits of the IP address from the Minor:

   1. Convert the Minor to hexadecimal:
      * hex (12127) = 2F5F
   2. Convert the high bits of the result to decimal:
      * dec(2F) = 47
   3. Convert the low bits of the result to decimal:
      * dec (5F) = 95
   4. Combine the results of steps b. and c. to get the low 16 bits of the IP address:
      * 47.95

3. Combine the results of steps 1. and 2. to get the high 16 bits of the IP address:

   * 192.168.47.95

## See also

* [Terminal API overview](/point-of-sale/design-your-integration/terminal-api)
* [Apple's iBeacon documentation](https://developer.apple.com/ibeacon/)