Bluetooth beacons

Our Bluetooth terminals use the iBeacon protocol 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.

Advertised values and integration types

The terminal advertises values using the iBeacon protocol so your mobile POS app can recognize the closest terminal. You define the following values when you 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 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:

• Cloud communications
• Local communications

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.

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

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:

  Major	${SERIALH}
  Minor	${SERIALL}

  To learn how to decode the advertised data, see Get the serial number.

• Encode the IP address of the terminal if you are using local communications. 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.

Use beacons with cloud communications

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

After you have set up beacons in your Customer Area, route your Terminal API requests as follows:

1. Get the serial number from the Major and Minor. You can use our placeholders to have the terminal advertise its serial number, encoded into the Major and Minor.
2. Get the full POIID:
   1. Make a POST /connectedTerminals 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, 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, route your Terminal API requests as follows:

1. Get the IP address from the Major and Minor. You can use our placeholders 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 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