Set up 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 payments initiated from the POS app are always routed to the nearest terminal.  

The terminal advertises the following values, specified according to the iBeacon protocol: 

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

You can configure these values when you set up beacons in your Customer Area. Once set up, you can use the advertised Major and Minor values to forward payment requests to the advertising terminal. The exact information needed to route a payment request to a specific terminal depends on your integration with the Terminal API:

• Cloud-based communication
• Local communication

Cloud-based communication

With cloud-based communication, a payment request is routed to the correct terminal based on the unique terminal ID, the POIID, which you pass in the payment request.

You can use our placeholders to have the terminal advertise its serial number, encoded into the Major and Minor. Then, to get the POIID:

1. Get the serial number from the Major and Minor. 
2. Get the terminal model. To retrieve a list of the POIIDs of all connected terminals, use our connectedTerminals API.

Local communication

With local communication, a payment 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. Use this to determine the endpoint for the request.

You can use our placeholders to have the terminal advertise its IP address, encoded into the Major and Minor. To forward requests to the correct terminal, you then need to: 

1. Get the IP address from 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. Send a DiagnosisRequest 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 PaymentRequest (and other requests) using the correct POIID to the IP selected in step 1.

Set up beacons in your Customer Area

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

1. Log in to your Customer Area. 

2. Go to Point-of-Sale > Terminals. 
   This opens a page with a list of all terminals under your company account.

   You can also configure the iBeacon functionality at the merchant level, store level, or for a single terminal. For that, navigate to the required level before you proceed to the next step.

3. Go to the Network tab. 

4. In the Beacon section, set:

   1. Enable beacons to Yes. 
   2. UUID to the Universally Unique Identifier that you want to use. You can generate a UUID using an online tool, for example uuidgenerator.
   3. Major and Minor to the values that you want to use. You are free to choose your own values, or use our placeholders. 

5. Click Save at the bottom of the page.

Placeholders for the Major and Minor 

You can use our placeholders to dynamically encode into the Major and Minor either:

• The serial number of the terminal – if you are using cloud-based communication with the Terminal API. For this, set:

  Major	${SERIALH}
  Minor	${SERIALL}

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

• The IP address of the terminal – if you are using local communication with the Terminal API. 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 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

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