Project Documentation


Purpose

Simple, secure payments on every device in every region

  • One integration

    • Across regions

    • Across hosts

    • Across connections

    • Across payment protocols

    • Across Verifone platforms & devices

      • POS app written for CM5 or Carbon will also work on an Android BYOD with an e280.

    • Across Merchant platforms & devices

      • POS app written for Android on Carbon will use the same APIs and flows if ported to iOS or Windows

  • Simplifies and streamlines the experience for the developer

    • The POS can integrate once and it works regardless of the region, host, or Verifone device.

    • One set of documentation covering 3 merchant platforms (Android, iOS, Windows) and Verifone devices (Carbon, Carbon Mobile, e280, …)

    • Unified API and error codes across Verifone and Merchant platforms



SDK Design

Use the Payment SDK to communicate with various services on the device, including:

  • Payment Service - This service provides session management and acts as an abstraction into the actual payment services of the device. As the Payment SDK can run on a variety of different Verifone devices, the Payment Service discovers the appropriate payment application interface and adapts the APIs to this interface.

  • Peripheral Service - This service connects to supported peripherals attached to the device, including printers, barcode scanners, and cash drawers.

  • Navigator - Enables Verifone’s proprietary accessibility options on a touch screen device.

  • CP Triggers & APIs - The SDK provides the constants and factories to interpret the CP Trigger Requests and correctly send the CP Trigger Responses and CP API messages.

 @startuml
 !include uml_styles.iuml

 actor "Cashier"

 component "Android\n" as Android <<device>> {
   rectangle "POS" {
     rectangle "PSDK" as PSDK <<highlight>>
   }

   rectangle "Peripheral Service" as PeripheralService {
     rectangle "Cash Drawer\nAdapter" as CashDrawerManager <<highlight>>
     rectangle "Printer\nAdapter" as PrinterManager <<highlight>>
     rectangle "Scanner\nAdapter" as ScannerManager <<highlight>>
   }
   CashDrawerManager <<-u->> PSDK
   PrinterManager <<-u->> PSDK
   ScannerManager <<-u->> PSDK

   rectangle "Navigator" as NavigatorService {
     rectangle "Accessibility\nManager" as Navigator <<highlight>>
   }
   PSDK <<-r->> Navigator

   rectangle "Payment Service" as PaymentService {
     rectangle "Payment App\nProtocol Adapter" as ProtocolAdapter <<highlight>>
   }
   PSDK <<-r->> ProtocolAdapter
 }

 rectangle "Cash Drawer" as CashDrawer <<highlight>>
 rectangle "Printer" <<highlight>>
 rectangle "Scanner" <<highlight>>
 CashDrawerManager <<-d->> CashDrawer
 PrinterManager <<-d->> Printer
 ScannerManager <<-d->> Scanner

 component "POI\n" as POI <<device>> {
   rectangle "Payment App" as PaymentApp <<highlight>>
   ProtocolAdapter <<-d->> PaymentApp
   Navigator <<-d->> PaymentApp
 }
 Android <<-l->> Cashier

 actor "Customer"
 POI <<-r->> Customer

 @enduml

Payment Service

The Payment SDK uses simple, high level interfaces for transactions like sale, void, refund, etc. The Verifone Payment Application manages all payment workflows, including consumer UI interaction, interfacing with the card readers of the device, and interfacing with the host.

Peripheral Service

The SDK provides a uniform interface to interact with the various supported peripherals that might be attached, enabling a simpler interaction with those devices.

For the printer, this provides a single interface to print receipts or receipt-like documents on the supported printers using a single set of commands.

For the scanner, this provides access to a barcode scanning library that is optimized for the current device, making the built-in camera more efficient and accurate when scanning barcodes.

For the cash drawer, this provides an interface to open and query the state of the cash drawer attached through the base.

CP Triggers & APIs

Provides the necessary classes to expose the data contained in the CP Triggers and easily create API calls or Responses based on those Triggers, removing much of the boilerplate code necessary to parse the data out of the Android Broadcast.



Setup

Versions

Carbon 8/10 uses SDK Version 22, so the minimum SDK version must be at most 22 to work. In addition, the SDK uses some features that are only available in API 27 to support compatibility with later devices, so the compile version must be at least 27. There will also need to be some reference to the library in the dependencies section of the build.gradle, generally as an implementation. Example values below for the build.gradle file.

android {
  compileSdkVersion 27 // Or higher
  defaultConfig {
    minSdkVersion 22 // Or less
    ...
  }
  ...
}
...
dependencies {
  implementation project("DeveloperSDK")
  ...
}

Importing the SDK

When importing the library, it’s generally best to use Android Studio to add a New Module to the project, select “Import .JAR/.AAR Package”, then select the AAR file using the file chooser to properly link it to the project. This will allow you to include it in the dependencies using the example above.

Android Manifest Configuration

The Android Manifest must contain a couple of values to work on the Carbon platforms, must not contain certain values, and there are a couple recommended values to help the app work better.

Required Elements

The app must contain the CP App ID, enabling the system to allow it certain privileges and properly track if the correct version is installed. If the app is registering for CP Messages (see CP Application Integration Guide), then it must also have the trigger version. See below for the meta-data elements that describe these two required values.

<application ...>
    <meta-data
        android:name="com.verifone.commerce.manifest.appid"
        android:value="ExampleCpApp-695973514" />
    <meta-data
        android:name="com.verifone.commerce.manifest.trigger.version"
        android:value="4.3.0" />

Optional Elements

Docking and undocking the Carbon device with the base triggers a UI Mode change in Android, which shuts down and restarts the current Activity. Following the Android best practices as described at https://developer.android.com/guide/topics/resources/runtime-changes RetainingAnObject will mean this won’t be a problem. If it is necessary to handle the configuration change directly, adding android:configChanges="uiMode" to the Android Manifest and overriding onConfigurationChanged() will allow them to remain running during the change. For more information on this setting, visit https://developer.android.com/guide/topics/manifest/activity-element#config

<activity android:name=".MyActivity"
          android:configChanges="uiMode"
          ...>

Prohibited Elements

Below is a list of items that should not be present in the Android Manifest, and may cause it to be removed from the devices and general distribution.

android:sharedUserId="android.uid.system"
android.app.action.DEVICE_ADMIN_ENABLED
android.intent.action.BOOT_COMPLETED"
android.intent.action.DEVICE_INITIALIZATION_WIZARD
android.intent.action.PACKAGE_CHANGED
android.intent.action.PACKAGE_REMOVED
android.intent.action.PACKAGE_REPLACED
android.intent.action.USER_PRESENT
android.intent.category.HOME
android.permission-group.SYSTEM_TOOLS
android.permission.CLEAR_APP_CACHE
android.permission.DISABLE_KEYGUARD
android.permission.MANAGE_USERS
android.permission.MOUNT_UNMOUNT_FILESYSTEMS
android.permission.SHUTDOWN
com.android.launcher.permission.READ_SETTINGS
com.android.launcher.permission.WRITE_SETTINGS


Warning

Verifone Confidential

This documentation is protected by law from any form of duplication unless prior permission is obtained from the officers of Verifone.