Android SDK - Developer Utilities

Describes the classes exposed in the Android mobile payments SDK that facilitate the developer’s use of the SDK to build, configure, and monitor a working reference app, but do not represent functional modules of the app behavior.

Bluetooth LE Library Utility

The com.paydiant.android.bluetooth.ble utility class implements a set of Bluetooth Low Energy (BLE) library classes that a developer can to configure the app to interact directly with a device, such as a POS, that is broadcasting the BLE service.

Ultimately, this implementation enables the mobile payments app to pair with the BLE service and read emitted beacons to initiate interaction with the Paydiant SDK, such as obtaining a checkout token value or activating an offer.

To use the BLE library utility classes, set up your development environment so your project meets the following minimum requirements:

  1. Reference Android 4.3 (API level 18) or higher in your project.
  2. Update your AndroidManifest.xml file to set the target SDK version to 18 or higher: android:targetSdkVersion="18".
  3. Make sure your project references the BLELibrary.apklib included in this Android SDK package (libs/BLE-Library). Refer to the README file located in the same directory for additional instructions.

Note: While this implementation of the BLE library classes provides the foundation toward BLE-enabled transactions, at this time the Android OS does not have the ability to decode the binary data emitted by the BLE service. Therefore, in order to use this feature, a developer must write a custom utility that is capable of converting the binary data into a value that can be used by the SDK, such as a checkout token.

The methods of the Bluetooth utility allow the developer to initialize the Bluetooth libraries and scan for supported BLE signals.

The following methods all throw BLEServiceProviderException; with event-specific error information.

Initialize the BLE service

Item Description
Method public void init (Context context);
Creates an instance of the Bluetooth service class using the provided parameters.

context - runtime android context in which the BLE service is started

Check status

Item Description
Method public getBLEStatus();
Checks the current initialization state of the BLE service on the current device.
Returns One of the following values that indicates the status of the service:

BLE_NOT_SUPPORTED_ERROR
BLE_STATE_TURNED_OFF
BLE_STATE_TURNED_ON

Start scanning

Item Description
Method public int startScan(UUID[] serviceUuids);
Kicks off a scan for BLE devices within the geo-perimeter that match the specified UUIDs representing supported devices relevant to the mobile payments app.

or public int startScan(UUID[] serviceUuids, long timeout);
An overloaded instance of the method that allows the developer to specify a duration for scanning, after which, if a UUID match has not been detected, the service will stop scanning.
Parameters serviceUuids - a list of BLE device UUIDs that are relevant to the app.

Note: In both variations of the method, if the serviceUuids array is null or empty, the service will initiate the scan in "beacon mode" meaning that the Android device will be able to pick up beacons and their advertisements. timeout - the amount of time, in seconds, that the BLE service will continue to scan for UUID matches before stopping.

Check scanning

Item Description
Method public isScanning();
Checks the current state of the BLE service to determine whether it is actively scanning for BLE devices in the vicinity.
Returns TRUE - the service is actively scanning
FALSE - the serice is not actively scanning

Stop scanning

Item Description
Method public stopScanning();
Instructs the service to stop scanning for BLE devices.

Release BLE resources

Item Description
Method public release();
Releases all the resources currently consumed by the BLEServiceProvider class and performs cleanup operations to enable the service to scan for a new BLE device.

Note: The release method must be called upon completion of any BLE operation.

Set BLE listener

Item Description
Method public void setBLEServiceProviderListener (IBLEServiceProviderListener listener);
Sets an implementation of the BLEServiceProvider listener interface for the purpose of invoking relevant callback methods to be returned by the Bluetooth library.

listener - an instance of the com.paydiant.android.bluetooth.ble.IBLEServiceProviderListener class.

Bluetooth Callbacks

The callback methods of the Bluetooth Library utility enable the developer to configure relevant behavior in the app to be invoked based on the results of the app’s interaction with a supported BLE device.

Device discovered

Item Description
Method public void onDeviceDiscovery(BLEDevice device, BLEScanRecord rawData, init rssi);
Invoked when a matched remote BLE device is detected during scanning.

device - an instance of the device data object that identifies the matched BLE device.
rawData - the characteristic value representation read from the LE emission. Since different LE devices may represent this data differently, developers should decode the raw data returned according to LE manufacturer specifications.
rawData is returned instead.
rssi - The RSSI value published by the Bluetooth device hardware that represents the power and distance of the detected BLE device relevant to the mobile payments device. This value will be 0 if no RSSI data is returned.

Ad device discovered

Item Description
Method public void onDeviceDiscoveredWithAdData(BLEDevice device, BLEScanRecord rawData, init rssi);
Invoked only when a discovered BLE device contains advertisement data.

device - an instance of the device data object that identifies the matched BLE device.
rawData - The advertising data value. Since different LE devices may represent this data differently, developers should decode the raw data returned according to LE manufacturer specifications.
rssi - The RSSI value published by the Bluetooth device hardware that represents the power and distance of the detected BLE device relevant to the mobile payments device. This value will be 0 if no RSSI data is returned.

Paydiant token device discovered

Item Description
Method public void onDeviceDiscoveredWithPydtToken(BLEDevice device, BLEScanRecord rawData, init rssi);
Invoked only when a discovered BLE device contains a Paydiant checkout token for initiating a transaction.

device - an instance of the device data object that identifies the matched BLE device.
rawData - the checkout token data value. Since different LE devices may represent this data differently, developers should decode the raw data returned according to LE manufacturer specifications.
rssi - the RSSI value published by the Bluetooth device hardware that represents the power and distance of the detected BLE device relevant to the mobile payments device. This value will be 0 if no RSSI data is returned.

Device connected

Item Description
Method public onDeviceConnect(BLEDevice device);
Invoked when the Android device successfully connects (pairs) with the detected BLE device.

device - An instance of the device data object that identifies the matched BLE device.

Device status updated

Item Description
Method public onDeviceStateChanged(int state);
Invoked when the status of a matched BLE device changes.

state - An integer value representing the BLE device status to which the state has been changed. The value for this parameter will be one of the following:

10 - BLE_STATE_TURNED_OFF
11 - BLE_STATE_TURNING_ON
12 - BLE_STATE_TURNED_ON
13 - BLE_STATE_TURNING_OFF

Service discovered

Item Description
Method public onServiceDiscovery(BLEDevice device, ListBLEService services);
Invoked when the BLE device advertises a service that the Android device has registered as relevant.

device - an instance of the device data object that identifies the matched BLE device.
services - an array of BLEService objects representing one or more registered services that have been discovered.

Characteristic read

Item Description
Method public onCharacteristicRead(BLEDevice device, BLEService service, BLECharacteristic characteristic);
Invoked when the Android device successfully reads a specific data value from a matched BLE service.

device - an instance of the device data object that identifies the matched BLE device.
service - the BLEService object identifying the service from which the characteristic was read.
characteristic - the BLECharacteristic object identifying the specific data value that was read. Characteristic values are returned as rawData and will need to be decoded per LE device manufacturer specifications.

All characteristics read

Item Description
Method public onAllCharacteristicsRead(BLEDevice device, BLEService service, ListBLECharacteristic characteristics);
Invoked when the BLE device successfully reads the entire set of data values advertised by a matched BLE service.

device - an instance of the device data object that identifies the matched BLE device.
service - The BLEService object identifying the service from which the characteristics were read.
characteristics - An array of BLECharacteristic objects representing one or more data values that were successfully read from the BLE device. Characteristic values are returned as rawData and will need to be decoded per LE device manufacturer specifications.

Scanning stopped

Item Description
Method public onScanStop();
Invoked when the BLE device stops scanning for matched BLE devices.

BLE error occurred

Item Description
Method public onError(BLEException e);
Invoked when the Android device encounters an error interacting with the BLE utility.

Heartbeat Utility

The com.paydiant.android.net.Reachability utility class allows a developer to routinely check the connectivity between the app and the mobile gateway. When enabled, the heartbeat events can be listened for through the Android broadcast receivers by registering for the Reachability.REACHABILITY_ACTION intent action. Then, connectivity status can be obtained from the intent's Reachability.EXTRA_R EACHABILITY_SUCCESS Boolean extra value. Successful connectivity checks return TRUE and failed connectivity checks return FALSE.

Note: This class uses Paydiant’s Logging Utility to record each successive heartbeat success and failure. Therefore, be sure to initialize the PaydiantLoggingUtility via its init method before starting the heartbeat utility.

The methods of the heartbeat utility enable the developer to create an instance of the reachability class, as well as enable and disable the status checks.

Constructor

Item Description
Method public Reachability(Context context, int reachabilityInterval, int retryAttempts, int retryAttemptInterval)
Creates an instance of the Reachability class using the provided parameters.

Start checking

Item Description
Method public synchronized void start()
or
public void startReachableCheck()
Starts the heartbeat. Paydiant’s Logging Utility must be initialized prior to starting the heartbeat.

Note: Reachability tests should only be done when the app is active. Stop the heartbeat when the app moves to the background because reachability is irrelevant when the app is not being used.

Stop checking

Item Description
Method public void stopRechableCheck()
Stops the heartbeat.

Device Property Utility

The com.paydiant.android.core.util.DevicePropertyUtil utility class exposes the methods that obtain information about the device on which the app is running for operational and troubleshooting purposes.

These methods enable a developer to retrieve and use device data such as the hardware, OS, and network information.

Retrieve device properties

Item Description
Method public static Map < String, String > retrieveDeviceProperties(ContextWrapper deviceContext)
Gets the device id, manufacturer, brand, model, CPU architecture, network operator (if available) and the OS release version information.
Keys Use the following keys defined in com.paydiant.android.core.util.IDevicePropertyCodes to extract the values from the returned Map.

Device - IDevicePropertyCodes#DEVICE_ID
Manufacturer - IDevicePropertyCodes#MANUFACTURER
Brand - IDevicePropertyCodes#BRAND
Model - IDevicePropertyCodes#MODEL
CPU Architecture - IDevicePropertyCodes#CPU_ARCHITECT
Network Operator - IDevicePropertyCodes#NETWORK_OPERATOR_NAME
OS Build Version - IDevicePropertyCodes#BUILD_VERSION

Retrieve system process and memory information

Item Description
Method public static Map < String, String > retrieveCurrentSystemInfo(ContextWrapper deviceContext)
Gets the available memory and the active processes count information.
Keys Use the following keys defined in com.paydiant.android.core.util.IDevicePropertyCodes to extract the values from the returned Map.

Active Processes -IDevicePropertyCodes#NO_OF_RUNNING_PROCESSES
Available Memory - IDevicePropertyCodes#AVAILABLE_MEMORY

Retrieve active network information

Item Description
Method public static Map < String, String > retrieveActiveNetworkInfo(ContextWrapper deviceContext)
Gets information about the current active network.
Keys Use the following keys defined in com.paydiant.android.core.util.IDevicePropertyCodes to extract the values from the returned Map.

Active Network Type - IDevicePropertyCodes#ACTIVE_NETWORK_TYPE.

Valid values are:
Wi-Fi - IDevicePropertyCodes#ACTIVE_NETWORK_TYPE_WIFI
Cellular - IDevicePropertyCodes#ACTIVE_NETWORK_TYPE_MOBILE
SSID (Wi-Fi Only) - IDevicePropertyCodes#WIFI_SSID
Mac Address (Wi-Fi Only) -IDevicePropertyCodes#WIFI_MAC_ADDRESS
Network Operator (Cellular Only) - IDevicePropertyCodes#NETWORK_OPERATOR_NAME

App Utility

The com.paydiant.android.common.util.AppUtils utility class provides functionality to retrieve app related information for troubleshooting and support purposes. These methods enable a developer to retrieve and use app data such as the version and the current state.

Retrieve app label

Item Description
Method public static String getApplicationLabel(Context context)
Gets the value of the android:label as defined in the AndroidManifest.xml file.

context - current android content

App is in background

Item Description
Method public static boolean isAppInBackground(Context context)
Indicates if the app is in background or not.

Note: Checking the app’s background state this way is inefficient and unreliable. This utility is intended solely as an alternative to the activity's life cycle methods, which are a better determination of the app's background/foreground state, but are not necessarily always visible to the calling method.

App Authenticity Verification Utility

The com.paydiant.android.common.util.AppVerificationUtils utility class provides functionality to validate the app's authenticity for the purpose of heightened security.

This utility exposes a single method to verify the fingerprint of an app's original signed certificate against that of the current running app. To use this method, find the JAR file and usage.txt file in the tools folder of the Android SDK bundle. The JAR file should be used to generate the fingerprint value. The usage.txt file provides instructions on how to use this JAR file.

Verify app signature

Item Description
Method public static void verifyAppSignature(Context context, long[] keyFingerprint, IVerificationCallback verificationCallback)

context - Specifies the current Android context.
keyFingerprint - The fingerprint value generated using the JAR file in the Android SDK bundle provided by Paydiant.
verificationCallback - instance of an implementation of the AppVerificationUtils.IVerificationCallback interface, which gets called when the app verification completes.

Note: The status value provided by the interface's onVerificationComplete method defines whether the verification completed successfully (TRUE) or failed (FALSE) due to a tampered/modified app that is not published by the original developer.|

Date Time Conversion Utility

The com.paydiant.android.common.util.DateUtils utility class provides functionality to convert the timestamp associated with a mobile app event to the local time of the device.

Convert time to device timezone

Item Description
Method Date convertDateToLocal(String datetimePattern, String datatimeValue)
Gets the date and date format associated with an event in the app, then converts the timestamp from UTC time-zone to the local time-zone of the device and returns the converted value in the original format.

datetimePattern - Specifies the format used by the datetime value to be converted.
datatimeValue - The datetime value to convert.

Cryptographic Utility

The com.paydiant.android.common.util.CryptoUtil utility class provides the functionality to encrypt or decrypt sensitive data for security purposes. These methods exposed by the cryptographic utility enable the developer to quickly and securely encode data in a variety of ways to protect it from malicious interception.

Encrypt as string

Item Description
Method public static String encrypt(String seed, String cleartext)
Encrypts the provided cleartext value with the use of the "AES" algorithm and the provided seed parameter.

Decrypt as string

Item Description
Method public static String decrypt(String seed, String encrypted)
Decrypts the encrypted value with the use of the "AES" algorithm and the provided seed parameter.

Encode string to hex format

Item Description
Method public static String toHex(String txt)
Converts the provided string to the equivalent hex representation.

Decode hex string to string

Item Description
Method public static String fromHex(String hex)
Decodes the provided hex string to the original string.

Decode hex string to byte[]

Item Description
Method public static byte[] toByte(String hexString)
Decodes the provided hex string to a byte array.

Encode byte[]

Item Description
Method public static String toHex(byte[] buf)
Converts the provided byte array to the equivalent hex representation.

Generate MD5 digest

Item Description
Method public static byte[] md5Digest(byte[] data)
Generates MD5 digest for the provided data.

Generate SHA-256 digest

Item Description
Method public static byte[] sha256Digest(byte[] data)
Generates SHA-256 digest for the provided data.

Paydiant Wi-Fi Configuration Parser

The com.paydiant.android.net.wifi.PaydiantWifiConfigParser utility class provides functionality to parse contents created through Paydiant’s Wi-Fi portal.

The parser returns android.net.wifi.WifiCon figuration objects that can be used to setup the required Paydiant-supported Wi-Fi networks.

The methods exposed in the parser utility enable a developer to instantiate the parser as well as perform the actual parsing.

Constructor

Item Description
Method public PaydiantWifiConfigParser(ContextWrapper contextWrapper, String wifiConfigProtocol, String wifiConfigHost, String wifiConfigBrandPath, boolean eapEnabled)
Creates an instance of the Paydiant Wi-Fi Config Parser using the provided parameters.

contextWrapper - A reference to the app's android ContextWrapper.
wifiConfigProtocol, wifiConfigHost and wifiConfigBrandPath - define the configuration's access path, which is created using the Paydiant Wi-Fi portal.
eapEnabled - specifies whether or not Wi-Fi configurations supporting the 802.11 EAP standard should be considered.

Parse configurations

Item Description
Method public List < WifiConfiguration > parseConfigs()
Parses the configurations created through the Paydiant Wi-Fi portal and return a list of android.net.wifi.WifiConfiguration objects that enable the Android Wi-Fi Manager to create the necessary Wi-Fi networks on user devices.

Location Utility

The Location Utility tool enables the developer to retrieve the latitude and longitude geo-location of the device for the purpose of populating the mobile wallet’s store locater with data that is relevant to the user’s current location.

Note: When geo-location information is captured, mobile wallet users must be notified and afforded the ability to opt-out in accordance with legal requirements. Therefore, developers are advised to implement a Just-in-Time notification at the time of app initialization to obtain the wallet user’s consent. If the user declines to give consent, you must Suspend Locating.

Connecting and Disconnecting the app with the device location client may take a few seconds, so the developer is advised to implement a programmatic delay prior to calling any subsequent methods that are dependent on the service.

Enable locating

Item Description
Method public void startLocationUpdationService(Context context);
Connects the mobile wallet app to the device’s GPS location client. This method must be invoked before the Get Location method can be called.

Suspend locating

Item Description
Method public void stopLocationUpdationService(Context context);
Disconnects the mobile wallet app with the device’s GPS location client and removes the registered listener callbacks. We recommend that you call this method whenever the mobile wallet app is sent to the background in order to optimize the device battery preservation and performance, which can be affected by the app’s continuous effort to update the device location.

Get location

Item Description
Method public void getLocation(Context context);
Returns the current geo-location of the device, provided that the Enable Locating method has been invoked prior to calling this method.

Payment Account Utility

The Payment Account Utility tool enables the developer to retrieve and cache a payment account’s reference identification for the purpose of using it for the app’s default autopay account feature.

Each method exposed in the Payment Account Utility includes two overloaded versions to allow the developer to implement the functionality associated with either the meta-data or non-meta-data based payment account retrieval methods.

Cache default payment account

These methods cache the specified payment account as the default payment account in the device.

Note: Due to the sensitive information contained in the payment account object, the cached data will only be a hashed identifier, so that none of the payment account object's data is reversible in case of an unauthorized access to the device's application data.

Non meta-data

Item Description
Method public static boolean cacheDefaultPaymentAccount(Context context, PaymentAccount paymentAccount)
In this overloaded instance of the caching method, the paymentAccount parameter is populated with the non-meta-data object representing the payment account to be cached.

Meta-data

Item Description
Method public static boolean cacheDefaultPaymentAccountData(Context context, PaymentAccountData paymentAccountData)
In this overloaded instance of the caching method, the paymentAccountData parameter is populated by the meta-data object representing the payment account to be cached.

Retrieve Default Payment Account

These methods identify and return the cached payment account from the provided list of payment accounts. Since the utility caches the payment account as an identifier only, the list of Payment Accounts available for the user must be provided in order to identify the cached payment account and retrieve its corresponding data.

Non meta-data

Item Description
Method public static PaymentAccount retrieveDefaultPaymentAccount (Context context, List < ? extends PaymentAccount > paymentAccounts)
In this overloaded instance of the caching method, the paymentAccounts parameter is populated with the object containing the array of non-meta-data payment accounts available in the mobile wallet.

Meta-data

Item Description
Method public static PaymentAccountData retrieveDefaultPaymentAccountData (Context context, List < ? extends PaymentAccountData > paymentAccountData)
In this overloaded instance of the caching method, the paymentAccountData parameter is populated with the object containing the array of meta-data payment accounts available in the mobile wallet.

Clear cached default payment account

Item Description
Method public static boolean removeCachedDefaultPaymentAccount (Context context)
Removes the cached default payment account from the mobile wallet device cache.

Online Ordering Integration

For mobile wallet providers who enable online ordering through the mobile wallet, Paydiant provides a mechanism for retrieving recent order history for a particular user for the purpose of streamlining repeat orders.

Get order summary

Item Description
UI Method public List < Order > retrieveOrderHistorySummary();

Retrieves the set of order objects representing orders that have previously been placed for the logged-in user.
Success public void onRetrieveOrderHistorySummarySuccess(List < Order > orderList):
Failure public void onRetrieveOrderHistorySummaryFailure(Paydiant Exception exception);
Core method public ListorderretrieveOrderHistorySummary();

Get order detail

Item Description
UI Method -(void)retrieveOrder:(String orderId)
Returns detailed information about the particular order specified in the orderId parameter.
Success public void onRetrieveOrderSuccess(Order order):
Failure public void onRetrieveOrderFailure(Paydiant Exception exception);
Core method public void retrieveorder:(String orderId);

Set order listener

Item Description
Set Listener void setOrderHistoryServiceListener(IOrderHistoryServiceListener listener);
Sets com.paydiant.android.ui.service.orderHistory, IOrderHistoryServiceListener or an overridden instance of com.paydiant.android.ui.service.orderHistory.orderHistoryServiceListenerAdapter so callback methods can be invoked during execution of the order integration methods for the UI Package.
Remove Listener public void removeListender();
Removes the order integration listener and sets it to null.

Other Resources

javadocs