Manage payment devices

For the card reader solution, you need to add specific metadata to your Android POS app. You also need to present a device management UI for pairing your mobile device and the card reader, connecting to the card reader, viewing card reader details, and updating the card reader firmware.

UI for device management

To use the card reader, store staff needs to:

• Pair the mobile device running the Adyen POS Mobile SDK with the card reader.
• See an overview of card readers. For example, to switch to a different card reader.
• View details of the card reader they are using. For example, to check the battery charge level.
• Update the firmware of the card reader they are using.

The SDK provides a built-in UI for all of those tasks. Here are some example screens.

To handle the device pairing and viewing of device details, you can:

• Use the built-in UI
• Build a custom UI

Use the built-in UI

To use the device management screens built into the Adyen POS Mobile SDK for Android, call the following code.

DeviceManagementActivity.start(activity)

Build a custom UI

If you intend to build your own UI for device management, use the DeviceManager interface to obtain all the necessary information.

val deviceManager = AdyenCardReaders.getInstance(context).deviceManager

For details, see DeviceManager functions.

DeviceManager functions

DeviceManager functions let you scan for card readers through Bluetooth device discovery, connect and disconnect a card reader, get information about the currently connected card reader, and manage firmware updates.

You can use the following functions:

• connectionState: StateFlow<ReaderConnectedState>: returns the connection state of the currently connected card reader.

• activeDeviceInfo: StateFlow<DeviceInfo>: returns the hardware information and battery state of the currently connected card reader.

• startBluetoothDiscovery(): Flow<Result<List<DiscoveredDevice>>>: starts scanning for nearby card readers. Returns an error if scanning failed.

• stopBluetoothDiscovery(): stops scanning for nearby card readers.

• getKnownDevices(): List<CardReaderDevice>: returns a list of paired card readers.

• connect(cardReaderDevice: CardReaderDevice): connects to a card reader.

• disconnect(): disconnects from the currently connected card reader.

• firmwareUpdateSummary(): Result<AvailableFirmwareUpdate>: returns information about available firmware updates for the card reader that is currently connected to the mobile device. The result includes:

  • requiresBluetoothConnection: indicates if a Bluetooth connection is required to update the card reader.
  • requiredDate: null, or the date by which transactions will be refused if the card reader is not updated to this firmware version.

• startFirmwareUpdate(): implements the available card reader firmware update. Shows an error if the update failed because the card reader was connected through USB and the update required a Bluetooth connection.

Manage card reader firmware

The firmware of the card reader must be updated from time to time, to keep the reader secure. Firmware updates have a due date, at which time they become mandatory. This means the card reader cannot process transactions anymore until it is updated to the mandatory firmware version.

Our built-in UI shows a red indicator when a new firmware version is available for the connected card reader, and has an Update button to start the firmware update. In case a firmware update failed because the card reader didn't have an active Bluetooth connection when the update required it, the built-in UI shows instructions on how to reset the reader before retrying the update.

Custom UI

If you use your own custom UI, it is required that you build logic into your POS app to:

• Check for new card reader firmware updates often. For example, when the app is launched.
• Handle the firmware update flow correctly within your POS app.

In this way, you are informed in time, and can prevent card readers becoming blocked because a mandatory update was not installed.

You can manage the card reader firmware using the following DeviceManager functions:

• firmwareUpdateSummary(): Result<AvailableFirmwareUpdate>
• startFirmwareUpdate()

In case a firmware update failed because it required a Bluetooth connection and the error UpdateRequiresBluetooth is thrown, ensure you provide instructions on how to reset the card reader before retrying the update. The instructions you need to provide, are as follows:

1. Power off the reader.
2. Press and hold the power button until a single loud beep sounds.
3. Wait for the reader to reset and reboot.
4. In the Bluetooth settings of the mobile device, select "Forget This Device".
5. Re-pair the reader and retry installing the update.

Next steps