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¶
Place PaymentSDK-xxxxx.aar file in the project at specific location(e.g. Project/app/libs).
Go to File->Project Structure->Dependencies, select Modules(app), select ‘+’, choose Jar dependency, provide file path and choose configuration as implementation.
Go to ‘File->Project Structure->Modules->app->DefaultConfig->Min SDK Version’, Set minSdkVersion to 22 and above.
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¶
In Xcode IDE, Drag “PaymentSdk.xcframework” into the project. It opens “Choose options for adding these files:”.
At “Destination:”, put tick mark at “Copy items if needed”.
At “Added folders:”, select “Create folder references”.
At “Add to targets:”, select project.
Click on main project file, under “TARGETS” select project.
Go to “General” tab.
Click on small triangle at “Frameworks, Libraries and Embedded Content”.
Select “PaymentSdk.xcframework”.
Under “Embed”, select “Embed & Sign”.
Update project’s Info.plist.
Add these privacy usage descriptions.
NSBluetoothAlwaysUsageDescription
NSBluetoothPeripheralUsageDescription
NSCameraUsageDescription
Add Supported external accessory protocols “UISupportedExternalAccessoryProtocols” if you are using Blutooth.
com.verifone.pmr.xpi
com.verifone.pmr.debug
com.verifone.pmr.control
com.verifone.pmr.barcode
com.verifone.pmr.zontalk
Windows Initial Setup Guide¶
Visual Studio Project Setup¶
Open Visual Studio installer. Click “Modify” on the Visual Studio tile.
Select “Modify” on the Visual Studio tile.
In the “Workloads” tab, select the “Universal Windows Platform development” tile.
In the “Individual Components” tab, select the compatible version of “Windows SDK” checkbox.
Select “Modify”.
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.
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.
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)”.
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¶
Open an existing solution or create a new UWP project.
Tools → NuGet Package Manager → Manage NuGet Packages for Solution.
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.
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¶
Open Visual Studio installer and install .Net Framework 4.6.
Open DotNetReferenceApp.sln with Visual Studio.
Inside Solution Explorer, in project DotNetReferenceApp.sln, right click “References”, then add VerifoneSdk dll.
Deploy on local machine with green start menu.
Linux Initial Setup Guide¶
CMake project setup¶
Install C++17 compatible compiler toolchain. Refer to your distribution documentation for more information.
Install CMake. See https://cmake.org for additional information.
Unzip PaymentSDK. We will refer to the created directory as PSDK_DIR.
Create a directory for your project. We will refer to this directory as PROJ_DIR.
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;
}
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")
Generate make files and compile executable by running the following in the PROJ_DIR:
cmake .
cmake --build .
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)¶
Requires a minimum OpenJDK version of 1.8 and an existing Java project.
In the project directory, add a “libs” folder.
Copy PaymentSdk-x.x.x-java.jar into the “libs” folder.
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.