DocumentationLegacy Documentation
Guides
Partner PortalMerchant Portal

Platform Specific Requirements

Suggest Edits

The SDK is available for iOS and Android platforms. There are some specific requirements for each platform and these are detailed below.

SQLCipher

SQLCipher is the SQLite database extension. It means that the default SQLite libraries provided by iOS APIs cannot be used in the same application, as this will cause unexpected behaviour. However, the provided SQLCipher libraries can be used by an integrating application for database access. The Payment Device SDK requires a password during initialisation of its own database but an empty password can be used for an unencrypted database used within the integrating application.

SQLCipher is required for the SDK to compile and run. The iOS SDK has the sqlicipher library and dependencies included in the release package, while in Android this must be included via Gradle by placing the following line in the applications dependencies:

compile 'net.zetetic:android-database-sqlcipher:4.5.3@aar'

ID TECH VP3350 SDK

Unlike other supported PIN pads the ID TECH VP3350 requires the ID TECH SDK to be added to the project in order for it to function. The ChipDNA Mobile SDK is supplied with the supported version of the ID TECH SDK.

In the Android release this can be found at libs/Universal_SDK_1.00.177_os.jar.

In the iOS release this can be found at ChipDnaMobile/IDTech.xcframework.

BBPOS SDK

Similarly to ID TECH VP3350 the BBPOS CHB30 requires the BBPOS SDKs to be added to the project in order for it to function. The ChipDNA Mobile SDK is supplied with the supported version of the BBPOS SDKs.
In the Android release this can be found at libs/bbdevice-android-3.29.1.jar and libs/bbdeviceota-android-1.6.28.jar.
In the iOS release this can be found at ChipDnaMobile/BBDeviceOTA-1.6.13.xcframework and ChipDnaMobile/BBDevice-BT-3.27.0.xcframework.

iOS

The minimum supported iOS version is 15.0.

A list of protocol strings must be presented by the application to enable the Payment Device SDK to communicate with an individual PIN pad. The following string must be added to the UISupportedExternalAccessoryProtocols property of an application’s Info.plist file:

  • com.miura.shuttle - To use the Miura Shuttle
  • com.idtechproducts.neo - To use the ID TECH VP3350
Only add the protocol strings of the devices you will be supporting otherwise your application may get rejected by Apple during the App Store review.
BBPOS Chipper integrations do not require submission of an MFi Product Plan ID therefore there is no accessory protocol entry to be added to the Info.plist for these devices.

The “external-accessory” string must be added to the UIBackgroundModes property of an application’s Info.plist file.

The libraries CoreLocation, CoreData, ExternalAccessory, MessageUI, SystemConfiguration, Security, AVFoundation, MediaPlayer, CoreAudio, AudioToolbox and CoreBluetooth should be added to the application target's linked libraries as they are used by the SDK.

Libraries libsqlite3.dylib or libsqlite3.0.dylib, if present, should be removed from the linked libraries, as the database library provided with the SQLCipher libraries will be used instead.

Build settings should be changed to include Other C Flags:

  • -DSQLITE_HAS_CODEC,

And Other Linker Flags:

  • -ObjC
  • -lz
  • -lstdc++

Swift

To use the Payment Device SDK in a Swift project add the SDK files to your project in the usual way. Then create a new header file to use as a bridge header by going ‘File >> New >> File’ and selecting to create a new ‘.h’ file. In the new header file add import statements for all ‘.h’ files in the SDK.

Once the files are imported in the bridge header, select your project file from the navigation menu in Xcode. Under ‘Build Settings’ change the viewing option from ‘Basic’ to ‘All’ and scroll down to the ‘Swift Compiler – Code Generation’ section. Then set the ‘Objective-C Bridging Header’ value to the path of your newly created bridge header file.

For more information on using Objective-C code in a swift project please refer to the Apple documentation.

Android

The minimum supported Android version is 12 (SDK version 31).

Android has been designed such that no application, by default, has permission to perform any operations that would adversely affect the operating system or the user. Therefore, to utilise the complete API the following permissions must be granted:

  • READ_PHONE_STATE - allows read only access to the phone state and is used to obtain a unique identifier for the mobile device required for a configuration update and to read the IMSI from the SIM to verify the Home Network Identity.
  • BLUETOOTH and BLUETOOTH_ADMIN - allows applications to connect to Bluetooth devices.
  • BLUETOOTH_SCAN and BLUETOOTH_CONNECT (SDK versions 31 and above) - allows applications to connect to Bluetooth devices.
  • ACCESS_COARSE_LOCATION (SDK versions 23 and above) and ACCESS_FINE_LOCATION (SDK versions 30 and above) - allows applications to scan for and connect to Bluetooth Low Energy devices.
  • INTERNET - allows applications to open network sockets.
    android.hardware.telephony feature - should be included and set to false, prevents the devices without telephony from being filtered out on Google Play.
  • android.hardware.usb feature - should be set in Applications planning to use a USB connection to prevent the application being shown to devices without USB on the Google Play store.

The Android SDK also requires the following dependencies to be linked in order to compile and run. You can do this by adding the following to the application dependencies block in the build.gradle file.

implementation fileTree(include: ['*.jar'], dir: 'libs')
implementation 'androidx.core:core-ktx:1.8.0'
implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.8.0'
implementation 'net.zetetic:android-database-sqlcipher:4.5.3@aar'
implementation 'androidx.sqlite:sqlite:2.0.1'
implementation 'com.jakewharton.timber:timber:4.7.1'

More information about adding kotlin to existing projects can be found in the Android documentation here: https://developer.android.com/kotlin/add-kotlin

Obfuscation

The Payment Device SDK for Android is already obfuscated. Passing the binaries through secondary obfuscation can result in incorrect operation of the SDK including loss of data.

Below is an example ProGuard configuration for excluding the Payment Device SDK binaries from obfuscation.

-keep class net.sqlcipher.** { *; }
-keep class net.sqlcipher.database.* { *; }
-libraryjars /libs/ChipDnaMobile.jar
-libraryjars /libs/CardEaseXMLClient.jar
-libraryjars /libs/Universal_SDK_1.00.173_os.jar
-libraryjars /libs/bbdevice-android-3.29.1.jar
-libraryjars /libs/bbdeviceota-android-1.6.28.jar


-keep class com.creditcall.** {
  *;
}

Updated 4 months ago