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

Integrations

Physical Connections

Key

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

---

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.

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.

---

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;
}

6. 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")

7. Generate make files and compile executable by running the following in the PROJ_DIR:

cmake .
cmake --build .

8. 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.