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, Windows or Linux.

  • 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 4 merchant platforms (Android, iOS, Windows, Linux) and Verifone devices (Carbon, Carbon Mobile, e280, …)

    • Unified API and error codes across Verifone and Merchant platforms


Packaging

Full PSDK

OS

@startuml
left to right direction
rectangle "Android" as 1 #White
rectangle "iOS" as 2 #White
rectangle "Windows" as 3 #White
rectangle "Linux" as 4 #White
1 -[hidden]- 2
2 -[hidden]- 3
3 -[hidden]- 4
@enduml

Integrations

@startuml
left to right direction
rectangle "Navigator + Control Panel" as 1 #White
rectangle "Setup Wizard" as 2 #White
rectangle "SCI" as 3 #White
rectangle "NEXO" as 4 #White
1 -[hidden]- 2
2 -[hidden]- 3
3 -[hidden]- 4
@enduml

Physical Connections

@startuml
left to right direction
rectangle "USB" as 1 #White
rectangle "Bluetooth" as 2 #White
rectangle "TCP/IP Network" as 3 #White
rectangle "BLE" as 4 #SkyBlue
1 -[hidden]- 2
2 -[hidden]- 3
3 -[hidden]- 4
@enduml

Key

@startuml
left to right direction
rectangle "Current" as 1 #White
rectangle "Roadmap" as 2 #SkyBlue
1 -[hidden]- 2
@enduml

Note

This same strucuture is observed for all 4 platforms (Android, iOS, Windows, & Linux). The package extensions and some of the API signatures change slightly for each platform according to the programming language and other platform requirements.


SDK Design

 @startuml
 !include uml_styles.iuml

 actor "Cashier"

 component "BYOD\n" as byod <<device>> {
   rectangle "POS" {
     rectangle "PSDK" as PSDK <<highlight>> {
       rectangle "Navigator" as Navigator <<highlight>>
       rectangle "Printer\nAdapter" as PrinterManager <<highlight>>
       rectangle "Barcode Scanner\nAdapter" as ScannerManager <<highlight>>
       rectangle "Payment App\nProtocol Adapter" as ProtocolAdapter <<highlight>>
     }
   }
   rectangle "Camera" <<highlight>>
   rectangle "OS Printer Framework" as PrinterFramework <<highlight>>
 }

 rectangle "Printer" <<highlight>>
 rectangle "Barcode Scanner" as Scanner <<highlight>>

 PrinterManager <<-d->> PrinterFramework
 PrinterFramework <<-d->> Printer
 ScannerManager <<-d->> Camera
 ScannerManager <<-d->> Scanner

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

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

 @enduml


Integration Paradigms

Semi-Integrated

The payment device contains a complete payment application which interfaces to an external ECR/POS system, and handles all host interactions. The Payment SDK is embedded in the ECR/POS system.

 @startuml
 !include uml_styles.iuml

 scale 300 width
 scale 300 height

 component "Retailer ECR System\n" as ECR <<device>> #Ivory {
   rectangle "POS" #LightYellow {
     rectangle "Cross-Platform PSDK" #LightSkyBlue {
       rectangle "Payment Adapter" as PA
     }
   }
 }

 component "Engage Payment Device\n" as Engage <<device>> #Ivory {
   rectangle "GPA Payment\nApplication" as GPAAPP
   rectangle "SCA Payment\nApplication" as SCAAPP
   SCAAPP -[hidden]-> GPAAPP
   PA <<-l->> SCAAPP
   PA <<-l->> GPAAPP
 }

 cloud "Payment Host" as HOST1 #Ivory
 SCAAPP <<-l->> HOST1
 GPAAPP <<-l->> HOST1

 component "Android Payment Device\n" as Android <<device>> #Ivory {
   rectangle "POS Application" as POSAPP
   rectangle "Android Payment\nApplication" as AndroidAPP
   rectangle "Card Reader\nService" as CRS
   rectangle "Headless SDI" as HeadlessSDI #LightSalmon
   POSAPP <<-d->> AndroidAPP
   AndroidAPP <<-d->> CRS
   CRS <<-d->> HeadlessSDI
   PA <<-r->> AndroidAPP
 }

 cloud "Payment Host" as HOST2 #Ivory
 AndroidAPP <<-r->> HOST2

 @enduml

Slim-Integrated

In the slim-integrated model, supported only by the Android terminal, the payment application no longer communicates directly with the host, but rather sends a transaction event for host authorization/finalization to the POS application, which manages the host interactions.

 @startuml
 !include uml_styles.iuml

 scale 300 width
 scale 300 height

 component "Retailer ECR System\n" as ECR <<device>> #Ivory {
   rectangle "POS" #LightYellow {
     rectangle "Cross-Platform PSDK" #LightSkyBlue {
       rectangle "Payment Adapter" as PA
     }
   }
 }

 cloud "Payment Host" as HOST #ivory
 PA <<-d->> HOST

 component "Engage Payment Device\n" as Engage <<device>>

 Engage -[hidden]> ECR
 hide Engage

 component "Android Payment Device\n" as Android <<device>> #Ivory {
   rectangle "POS Application" as POSAPP {
     rectangle "PSDK" as PSDKAND #LightSkyBlue
   }
   rectangle "Android Payment\nApplication" as AndroidAPP
   rectangle "Card Reader\nService" as CRS
   rectangle "Headless SDI" as HeadlessSDI #LightSalmon
   POSAPP <<-d->> AndroidAPP
   AndroidAPP <<-d->> CRS
   CRS <<-d->> HeadlessSDI
   PA <<-r->> AndroidAPP
 }

 @enduml


Platforms and Features

Platform

Platform Requirements

Platform Features

Android

Minimum Android SDK Version 22 (Lollipop 5.1)

Java/Kotlin API

Target Android SDK Version 28 (Pie 9.0)

Barcode Scanner UI

Architectures ABI: x86, x86_64, armeabi-v7a, arm64-v8a

Assisted Terminal Discovery and Selection UI

Persisted Device Selection

Connectivity: USB, BT, and TCP/IP

iOS

Minimum iOS version 10.0

Obj-C/Swift API

Architectures: arm64, arm64e

Barcode Scanner UI

Assisted Terminal Discovery and Selection UI

Persisted Device Selection

Connectivity: MFi (USB and Bluetooth), TCP/IP

Windows

Windows 10 UWP

C++ API

Architectures: x86, x86_64

Barcode Scanner UI

Requires Visual C++ Redistributable (min 2015)

Assisted Terminal Discovery and Selection UI

Persisted Device Selection

Connectivity: USB, TCP/IP

Windows

Windows Dot Net

C# API

Architectures: x86, x86_64

Barcode Scanner UI

Persisted Device Selection

Connectivity: USB, TCP/IP

Linux

Linux GCC Version 7, libstdc++, C++17 libs

C++ API

32 & 64 bit support with C++03 ABI

Runtime Configuration

Persisted Device Selection

Connectivity: TCP/IP

Java

Windows Minimum Version 10

Java API

Linux GCC Version 7, libstdc++, C++17 libs

Barcode Scanner UI (Windows), Runtime Configuration (Linux)

Architectures: x86, x86_64

Persisted Device Selection

Connectivity: USB, BT, and TCP/IP (Windows), TCP/IP (Linux)


Project Setup

Android Initial Setup Guide

Adding PaymentSDK library to the Android project

  1. Place PaymentSDK-xxxxx.aar file in the project at specific location(e.g. Project/app/libs).

  2. Go to File->Project Structure->Dependencies, select Modules(app), select ‘+’, choose Jar dependency, provide file path and choose configuration as implementation.

  3. Go to ‘File->Project Structure->Modules->app->DefaultConfig->Min SDK Version’, Set minSdkVersion to 22 and above.

  4. AndroidX and other configuration options are required to use any Activities or Fragments provided by the PSDK.


iOS Initial Setup Guide

Adding PaymentSDK Framework to the iOS project

  1. In Xcode IDE, Drag “PaymentSdk.xcframework” into the project. It opens “Choose options for adding these files:”.

    1. At “Destination:”, put tick mark at “Copy items if needed”.

    2. At “Added folders:”, select “Create folder references”.

    3. At “Add to targets:”, select project.

  2. Click on main project file, under “TARGETS” select project.

    1. Go to “General” tab.

    2. Click on small triangle at “Frameworks, Libraries and Embedded Content”.

    3. Select “PaymentSdk.xcframework”.

    4. Under “Embed”, select “Embed & Sign”.

  3. Update project’s Info.plist.

    1. Add these privacy usage descriptions.

      1. NSBluetoothAlwaysUsageDescription

      2. NSBluetoothPeripheralUsageDescription

      3. NSCameraUsageDescription

    2. Add Supported external accessory protocols “UISupportedExternalAccessoryProtocols” if you are using Blutooth.

      1. com.verifone.pmr.xpi

      2. com.verifone.pmr.debug

      3. com.verifone.pmr.control

      4. com.verifone.pmr.barcode

      5. com.verifone.pmr.zontalk


Windows Initial Setup Guide

Visual Studio Project Setup

  1. Open Visual Studio installer. Click “Modify” on the Visual Studio tile.

  2. Select “Modify” on the Visual Studio tile.

  3. In the “Workloads” tab, select the “Universal Windows Platform development” tile.

  4. In the “Individual Components” tab, select the compatible version of “Windows SDK” checkbox.

  5. Select “Modify”.

  6. Different versions of Windows 10 builds will be compatible with different “Windows SDK” versions. To select the correct version go to Settings->System->About and check your OS build.

  7. In the “Individual Components” tab select the Windows SDK version with the same OS build version number. E.g. OS build 17763.678 and Windows SDK 10.0.17763.0.

  8. Enable logging in Visual Studio to show PSDK logs as follows.

    • Go to your project’s properties.

    • Select the “Debug” tab on the left.

    • There should be a section labeled “Debugger type”.

      • Change “Application process:” to “Mixed (Managed and Native)”.

      • Change “Background task process:” to “Mixed (Managed and Native)”.

  9. To enable network access for inbound and outbound, open Payckage.appxmanifest. Check “Internet (Client & Server)” for public network. Check “Private Networks (Client & Server)” for private network.

NuGet Package Setup

  1. Open an existing solution or create a new UWP project.

  2. Tools → NuGet Package Manager → Manage NuGet Packages for Solution.

  3. In Package source, there will be a settings button, click and add a new package source directory in the settings window. The Package source directory is the directory where the Nuget packages are located.

  4. Install both “Verifone.PaymentSDK” and “Verifone.PaymentSdkUi” as these two packages would show up once the package source is added correctly.


Windows Dot Net Initial Setup Guide

Visual Studio Project Setup

  1. Open Visual Studio installer and install .Net Framework 4.6.

  2. Open DotNetReferenceApp.sln with Visual Studio.

  3. Inside Solution Explorer, in project DotNetReferenceApp.sln, right click “References”, then add VerifoneSdk dll.

  4. Deploy on local machine with green start menu.


Linux Initial Setup Guide

CMake project setup

  1. Install C++17 compatible compiler toolchain. Refer to your distribution documentation for more information.

  2. Install CMake. See https://cmake.org for additional information.

  3. Unzip PaymentSDK. We will refer to the created directory as PSDK_DIR.

  4. Create a directory for your project. We will refer to this directory as PROJ_DIR.

  5. In the PROJ_DIR create an example C++ main.cpp source file with following content:

#include <functional>
#include <iostream>
#include <string>
#include <unordered_map>

#include "PaymentSdkInterface.hpp"
#include "PlatformContextLinux.hpp"
#include "PsdkDeviceInformation.hpp"
#include "PsdkStatusListener.hpp"
#include "Status.hpp"
#include "StatusCode.hpp"

// Converts a listener class to using lambdas
class Listener : public verifone_sdk::PsdkStatusListener {
 public:
  typedef std::function<void(const std::shared_ptr<verifone_sdk::Status>&)> HandleEventListener;

  Listener(HandleEventListener listener) : listener_(listener) {}
  void handleEvent(const std::shared_ptr<verifone_sdk::Status>& status) override {
    listener_(status);
  }

 private:
  HandleEventListener listener_;
};

int main() {
  std::unordered_map<std::string, std::string> param_map{
      {verifone_sdk::PsdkDeviceInformation::DEVICE_ADDRESS_KEY, "192.168.1.10"},
      {verifone_sdk::PsdkDeviceInformation::DEVICE_CONNECTION_TYPE_KEY, "tcpip"}};

  int last_status;

  auto psdk = verifone_sdk::PaymentSdkInterface::create(
      verifone_sdk::CreatePlatformContextLinux(std::nullopt));
  auto listener =
      std::make_shared<Listener>([&](const std::shared_ptr<verifone_sdk::Status>& status) {
        last_status = status->getStatus();
      });
  psdk->initializeFromValues(listener, param_map);
  if (last_status == verifone_sdk::StatusCode::SUCCESS) {
    auto transaction_manager = psdk->getTransactionManager();
    return 0;
  }
  return 1;
}
  1. In the same directory create an example CMakeLists.txt file with following content (replacing placeholders <> with full paths):

cmake_minimum_required(VERSION 3.5)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Note that PSDK is built using C++03 ABI, hence disabling C++11 ABI
set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} -D_GLIBCXX_USE_CXX11_ABI=0)

add_executable(PSDK_Test main.cpp)

target_include_directories(PSDK_Test PRIVATE "<PSDK_DIR>/include")
target_link_libraries(PSDK_Test "<PSDK_DIR>/lib/libPaymentSdk.so")
  1. Generate make files and compile executable by running the following in the PROJ_DIR:

cmake .
cmake --build .
  1. Run the produced executable from the PROJ_DIR. You should see a couple of log messages informing about PSDK initialization, this indicates successfull linking:

./PSDK_Test

Java Initial Setup Guide (Gradle)

  1. Requires a minimum OpenJDK version of 1.8 and an existing Java project.

  2. In the project directory, add a “libs” folder.

  3. Copy PaymentSdk-x.x.x-java.jar into the “libs” folder.

  4. Update build.gradle to add “implementation files(‘libs/PaymentSdk-x.x.x-java.jar’)” under “dependencies”.

PSDK Entry Points

Create the PaymentSdk object to begin the process. Once created, it must be initialized. Initialization can fail for a few reasons, such as the Verifone terminal could not be found, but when first starting out the primary reason is that a Verifone terminal has not yet been paired, and must be selected. To do this, use the Payment SDK’s method to display configuration, which provides a pre-built setup wizard for the user to find and pair a Verifone terminal. Once this is complete, initialization can be performed and then transactions and other operations can be performed.

Note

If a Verifone terminal is already paired, calling Display Configuration will simply display useful information about the terminal, such as connection type, serial number, application version, etc. It’s recommended to link this method somewhere in the app settings or info, so that the user can easily look at this view for support. It’s also possible to use the SDK’s getDeviceInformation() method to get these details and render them into a completely custom settings/information view.