SmartPOS API Version 1.7
Revision #1
Table of Contents
1. Overview
Welcome to the developer documentation for the SmartPOS API, a powerful library that enables seamless integration with a wide range of smart point-of-sale (SmartPOS) devices. The SmartPOS API provides a unified interface to access various features and services provided by all Worldline offered SmartPOS devices.
The SmartPOS API is designed to facilitate communication and interaction with SmartPOS devices, allowing developers to leverage their capabilities for tasks such as compliant secure connections or access to the hardware features. By utilizing the library, you can access a range of functionalities tailored to meet the specific requirements of your application.
In this documentation, you will find detailed information on how to integrate and utilize each part of the SmartPOS API, along with code examples, best practices, and troubleshooting tips. We are excited to have you on board and look forward to helping you leverage the full potential of SmartPOS devices through the SmartPOS API. Let's get started!
1.1 What's New
- SmartPOS Info - New methods added:
setStatusBar(expandable: Boolean)setNavigationBar(visible: Boolean)
1.2 Revision History
- Revision #1
- Document creation
2. Getting Started
This guide will walk you through the steps to integrate the SmartPOS API into your Android Studio project. By following these instructions, you will be able to access the powerful features and functionality provided by SmartPOS devices within your application.
Prerequisites
Before you begin, ensure that you have the following prerequisites in place:
- Android Studio: Make sure you have the latest version of Android Studio installed on your development machine. You can download it from the official Android Studio website.
- SmartPOS API Library: Obtain the SmartPOS API library from the official source.
- SmartPOS Device: Ensure that you have a compatible SmartPOS device available for testing and integration.
Integration Steps
Follow the steps below to integrate the SmartPOS API into your Android Studio project:
- Create a New Android Studio Project:
- Launch Android Studio and select "Create New Project" from the welcome screen.
- Choose the desired project template and configure your project settings as needed.
- Click "Finish" to create the project.
- Import the SmartPOS API Library:
-
Copy the SmartPOS API library (.aar file) into your project's "libs" directory.
-
In Android Studio, Go to Project structure, Dependencies, click under 'All dependencies" +
-
Choose "JAR/AAR Dependency", type 'libs' under Step 1 and click OK.
-
Click Apply to automatically modfiy the build.gradle file from your project. The following code is now part of your project
-
Build.gradle.kts (:app)...dependencies {implementation(fileTree(mapOf("dir" to "libs","include" to listOf("*.aar", "*.jar"),)))}...
-
- (OTHER OPTION) Configure the Module Dependencies:
-
Host the .AAR in your mavenLocal or Repository manager
-
Open your project's "build.gradle" file. In the dependencies block, add the following line to include the SmartPOS API library as a dependency:
-
Build.gradle.kts (:app)...dependencies {implementation("com.worldline.smartposapi:core:<version>")}...
-
- Sync Gradle and Build the Project:
- Sync the Gradle files by clicking the "Sync Now" button that appears in the toolbar or by selecting "File" > "Sync Project with Gradle Files".
- After the sync is complete, build the project by selecting "Build" > "Make Project" from the menu.
- Start Using the SmartPOS API:
- Now that the SmartPOS API library is integrated into your project, you can start utilizing its features.
- Refer to the SmartPOS API documentation for specific instructions on how to use the different blocks, such as SmartPOS Info, Security, Printer, NFC & ChipCard Reader, and Feature Check.
- Typically, you will need to instantiate the appropriate classes or interfaces provided by the library and call their methods to interact with the SmartPOS device.
Congratulations! You have successfully integrated the SmartPOS API into your Android Studio project. You can now explore the various functionalities offered by the library and leverage the power of SmartPOS devices within your application.
As the SmartPOS API is an AIDL interface we recommend you to read the official documentation to connect to out service at https://developer.android.com/guide/components/aidl . The service connection should be open only as long as your application needs to use each specific component, having a permanent open connection could result in performance issues.
Remember to consult the SmartPOS API documentation for detailed information on the available methods, parameters, and usage examples. If you encounter any issues during the integration process, refer to the troubleshooting section or reach out to the SmartPOS API support team for assistance.
Happy coding with SmartPOS devices and the SmartPOS API!
3. Interface Structure
The SmartPOS API provides a set of interfaces and methods to interact with SmartPOS devices and access their features. The API is an AIDL interface - the Service runs on any SmartPOS device Worldline offers.
| Interface | Description |
|---|---|
| SmartPOS Info | Access generic informal data on the SmartPOS device for analysis, reporting, or customizing user experience |
| Security | Establish secure connections with compliant cipher suites for confidentiality and integrity |
| Printer | Interact with the hardware printer for receipts and documents |
| NFC Reader | Read and write to MIFARE and FELICA chip cards using NFC technology |
| ChipCard Reader | Read Belgium eID cards |
| Feature Check | Validate supported features of the SmartPOS device |
3.1 SmartPOS Info
The SmartPOS Info block provides methods to retrieve various information and statistics about the SmartPOS device.
Methods
| Method | Returns | Description |
|---|---|---|
getBatteryStatus() | BatteryStatus | Current battery level and charging status |
getCPUStats() | CPUStats | CPU load and process count |
getDeviceMode() | DeviceMode | Production or development mode |
getFirmwareVersion() | String | Firmware version |
getMemoryStats() | MemoryStats | Total and free memory |
getNetworkInfo() | NetworkInfo | MAC address, available and active networks |
getSerialNumber() | String | Device serial number |
getSimData() | MutableList<Sim> | SIM card data (IMEI, Slot ID, APNs) |
getSimSlotIds() | MutableList<String> | Available SIM card slot IDs |
getModuleSupported() | List<Module> | Supported hardware modules |
APN Management
| Method | Parameters | Returns | Description |
|---|---|---|---|
selectSimApn() | slotId: String?, apn: Apn? | ApnStatus | Select APN configuration for SIM slot |
deleteSimApn() | slotId: String?, apn: Apn? | ApnStatus | Delete APN configuration from SIM slot |
System UI Control (New in 1.7)
| Method | Parameters | Returns | Description |
|---|---|---|---|
setNavigationBar() | visible: Boolean | Boolean | Show/hide navigation bar system-wide |
setStatusBar() | expandable: Boolean | Boolean | Enable/disable notification shade expansion |
Module Support
The Module class represents hardware modules that may be supported:
| Module | Description |
|---|---|
MAGSTRIPE_READER | Magnetic stripe reader |
ICC_READER | Contact chip card reader |
PICC_READER | Contactless card reader |
PED | PIN Entry Device |
KEYBOARD | Physical keyboard |
PRINTER | Receipt printer |
BT | Bluetooth connectivity |
CASH_BOX | Cash drawer |
CUSTOMER_DISPLAY | Customer-facing display |
ETHERNET | Ethernet connectivity |
FINGERPRINT_READER | Fingerprint reader |
G_SENSOR | Gravity sensor |
HDMI | HDMI port |
ID_CARD_READER | ID card reader |
SM | Security module |
MODEM | Network modem |
SCANNER | Barcode scanner |
3.2 Security
The Security block provides methods related to creating secure connections with compliant cipher suites.
Methods
| Method | Returns | Description |
|---|---|---|
requestSupportedCiphers() | MutableList<String> | List of supported cipher suites for secure connections |
3.3 Printer
The Printer block provides methods to interact with the hardware printer integrated into the SmartPOS device.
Methods
| Method | Parameters | Returns | Description |
|---|---|---|---|
registerPrinterListener() | printerListener: IPrinterListener | - | Register for printer events |
unregisterPrinterListener() | printerListener: IPrinterListener | - | Unregister printer listener |
getStatusOfPrinter() | - | PrinterStatus | Get printer status (deprecated) |
getExtendedStatusOfPrinter() | - | ExtendedPrinterStatus | Get detailed printer status |
getMaxCharactersPerLine() | printLineObject: PrintLineObject | Int | Max characters per line |
printDocument() | document: List<PrintObject> | PrintResult | Print a list of print objects |
Print Objects
PrintLineObject - Single line of text
data(String): Text to printprintLineProperties(PrintLineProperties): Layout properties (optional)
PrintEmptyLines - Empty lines
amountOfEmptyLines(Int): Number of empty lineslineHeight(Int): Height in pixels
PrintLeftRightInLine - Left/right aligned text
printLineObjectLeft(PrintLineObject): Left-aligned textprintLineObjectRight(PrintLineObject): Right-aligned text
PrintListOfLines - Multiple lines
listOfLines(List<PrintLineObject>): List of lines to print
3.4 NFC & ChipCard Reader
The NFC & ChipCard Reader block allows reading and writing to chip cards using NFC technology and contact chip readers.
NFC Methods
| Method | Parameters | Returns | Description |
|---|---|---|---|
readMifareSectors() | mifareSectorRequest: MifareSectorRequest | CardReadResultMifareSector | Read MIFARE sectors |
readNfcData() | auth: String? | CardReadResult | Read NFC data with optional auth |
readNfcUID() | - | CardReadResult | Read NFC card UID |
writeMifareSectors() | mifareSectorRequest: MifareSectorRequest | CardReadResult | Write to MIFARE sectors |
writeNfcData() | auth: String?, data: String? | CardReadResult | Write NFC data |
sendFelicaCommand() | command: ByteArray, bufferSize: Int, closeAfterResponse: Boolean, timeout: Long | NfcCommandResponse | Send FeliCa command |
openCardReader() | timeout: Long | CardOpenResult | Open NFC reader and get ATR |
sendAPDU() | apdu: ByteArray, bufferSize: Int, closeAfterResponse: Boolean | NfcCommandResponse | Send APDU command |
closeCardReader() | - | - | Close reader and release ownership |
ChipCard Methods (Belgium eID)
| Method | Parameters | Returns | Description |
|---|---|---|---|
readEidData() | isoCountryCode: String? | CardReadResult | Read Belgium eID data |
readUID() | - | CardReadResult | Read chip card UID |
openCardReader() | timeout: Int | CardOpenResult | Open reader and get ATR |
sendAPDU() | apdu: byte[], bufferSize: Int, closeAfterResponse: boolean | ApduResponse | Send APDU command |
closeCardReader() | - | - | Close reader |
APDU Example
// Open the card reader with a timeout of 5 seconds
val openResult: CardOpenResult = chipCardReaderService.openCardReader(5000)
if (openResult.status == CardReadStatus.SUCCESS) {
val atr: String = openResult.atr
// Send an APDU command
val commandApdu: ByteArray = byteArrayOf(0x00, 0xA4, 0x04, 0x00, 0x0A)
val bufferSize: Int = 255
val closeAfterResponse: Boolean = true
val apduResponse: ApduResponse = chipCardReaderService.sendAPDU(
commandApdu, bufferSize, closeAfterResponse
)
when (apduResponse.status) {
CardReadStatus.SUCCESS -> {
val responseData: ByteArray = apduResponse.data
// Process response data
}
CardReadStatus.OPERATION_NOT_ALLOWED -> {
// APDU command not whitelisted
val errorMessage: String = apduResponse.errorMessage
}
else -> {
val errorMessage: String = apduResponse.errorMessage
}
}
chipCardReaderService.closeCardReader()
} else {
val errorMessage: String = openResult.errorMessage
}
3.5 Feature Check
The Feature Check block provides methods for validating the availability of specific features supported by the SmartPOS device.
Methods
| Method | Parameters | Returns | Description |
|---|---|---|---|
getAvailableFeatures() | - | MutableList<Feature> | List of available features |
isFeatureAvailable() | feature: Feature? | Boolean | Check if specific feature is available |
3.6 Permissions
The SmartPOS API provides access to the NFC and ChipCard readers which require runtime permissions.
AndroidManifest.xml
<uses-permission android:name="com.worldline.smartposapi.worldline.permission.NFC"/>
<uses-permission android:name="com.worldline.smartposapi.worldline.permission.CHIP_CARD_READER"/>
Runtime Permission Request
class TestActivity : AppCompatActivity() {
private val requestPermissionLauncher =
registerForActivityResult(
ActivityResultContracts.RequestMultiplePermissions(),
::onPermissionResult
)
override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
super.onCreate(savedInstanceState, persistentState)
checkAndRequestPermission()
}
private fun checkAndRequestPermission() {
val hasNfc = ContextCompat.checkSelfPermission(
this, Permissions.NFC
) == PackageManager.PERMISSION_GRANTED
val hasChipCardReader = ContextCompat.checkSelfPermission(
this, Permissions.CHIP_CARD_READER
) == PackageManager.PERMISSION_GRANTED
if (!(hasNfc && hasChipCardReader)) {
requestPermissionLauncher.launch(
arrayOf(
Permissions.NFC,
Permissions.CHIP_CARD_READER
)
)
}
}
private fun onPermissionResult(permissionMap: Map<String, Boolean>) {
val refusedPermissions = permissionMap.filter { (_, v) -> !v }
if (refusedPermissions.isEmpty()) {
// All permissions granted
} else {
// Some permissions were not granted
}
}
}
3.7 Service Connection
As an AIDL interface, you must establish a connection for each service you want to use. See the Android AIDL documentation for details.
Example: Feature Check Service Connection
class MainActivity : ComponentActivity() {
companion object {
private const val DEFAULT_SMARTPOS_API_PACKAGE = "com.worldline.smartposapi.service"
}
var iFeatureCheckService: IFeatureCheckService? = null
private val serviceConnectionFeatureCheck = object : ServiceConnection {
override fun onServiceConnected(className: ComponentName?, service: IBinder?) {
iFeatureCheckService = IFeatureCheckService.Stub.asInterface(service)
}
override fun onServiceDisconnected(name: ComponentName?) {
iFeatureCheckService = null
Toast.makeText(
applicationContext,
"Service has unexpectedly disconnected",
Toast.LENGTH_SHORT
).show()
}
}
private fun bindToFeatureCheck() {
try {
val intent = Intent(BindingActions.FEATURE_CHECK)
intent.putExtra(BindingExtras.API_VERSION, "v1")
intent.setPackage(DEFAULT_SMARTPOS_API_PACKAGE)
bindService(
intent,
serviceConnectionFeatureCheck,
Context.BIND_AUTO_CREATE
).also {
Log.d("MainActivity", "Bind Feature Check: $it")
}
} catch (e: Exception) {
Log.d("MainActivity", "Not able to bind!")
}
}
override fun onStart() {
super.onStart()
bindToFeatureCheck()
}
override fun onStop() {
super.onStop()
unbindService(serviceConnectionFeatureCheck)
}
}
4. Glossary
4.1 Troubleshooting
Connection Issues
If you are experiencing connection problems with the SmartPOS device:
- Ensure the SmartPOS device is powered on and within range
- Verify the device address or connection parameters are correct
- Check WIFI/ethernet settings on both devices
- Restart both the SmartPOS device and your device
API Initialization Issues
If you are facing issues during initialization:
- Double-check that you have imported the correct classes from the SmartPOS API library
- Ensure you have connected to the SmartPOS service properly
- Verify necessary permissions are declared in your Android manifest file
Functional Issues
If you are encountering problems with specific API functionalities:
- Review the documentation and ensure you are using the correct methods and parameters
- Check for required permissions or additional configurations
- Validate that the SmartPOS device supports the feature you are trying to use
- Ensure you are handling API responses and errors appropriately
Device Compatibility
If you are unsure about device compatibility:
- Refer to the SmartPOS API documentation or contact support to confirm compatibility
- Check for specific requirements or limitations related to your SmartPOS device model
Error Messages and Logs
Pay attention to error messages or logs provided by the API or device. These provide valuable insights into the cause of issues. Capture and analyze them for troubleshooting purposes.