> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/psdk-latest/reference-material/code-labs/getting-started.md). # Getting Started {% columns %} {% column width="41.66666666666667%" %} :clock: 9 minutes reading time\ :calendar: Last updated: 10th October, 2025 {% endcolumn %} {% column width="24.999999999999986%" %} {% endcolumn %} {% column %} ✅ Device State ✅ Transaction Flow ✅ State Management ✅ Setup Guides {% endcolumn %} {% endcolumns %} {% stepper %} {% step %} ### Payment Device State PSDK maintains the last known connection state between POS and terminal state in PaymentDeviceState. This can be queried using the API `PaymentSdk.getDeviceInformation()`. The following table indicates possible device states and the follow-up actions that POS can take. | Index | PaymentDeviceState | Possible Actions from POS | | ----- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | 1 | NOT\_CONNECTED | POS should call `PaymentSdk.initialize(...)` | | 2 | CONNECTING | POS needs to wait for the callback to see the result of Initialize request. | | 3 | CONNECTED | POS can request regular operation API like login, Startsession, etc. | | 4 | DISCONNECTING | PSDK is in the process of teardown, POS needs to wait for the callback to see the result of TearDown request. | | 5 | CONNECTION\_LOST | Connection lost and cannot be recovered. `PaymentSDK.TearDown(...)` call required | | 6 | MAINTENANCE\_IN\_PROGRESS | To use the terminal, POS needs to wait till it receives the `END_MAINTENANCE` notification event. | #### PSDK State Transitions The table below itemizes the available actions and subsequent transition states for each action. | Index | Actions | Allowed State | TransactionManager Transient State | TransactionManager Final State (Success/Failure) | | ----- | ------------------------ | --------------- | ---------------------------------- | ------------------------------------------------ | | 1 | Initialize | NOT\_LOGGED\_IN | UNKNOWN | NA | | 2 | Login | NOT\_LOGGED\_IN | LOGGING\_IN | LOGGED\_IN | | 3 | StartSession | LOGGED\_IN | SESSION\_OPENING | SESSION\_OPEN | | 4 | HandleLineItem | SESSION\_OPEN | AWAITING\_TERMINAL | No state change | | 5 | FinalizeBasket | SESSION\_OPEN | AWAITING\_TERMINAL | No state change | | 6 | RequestCardData | SESSION\_OPEN | AWAITING\_TERMINAL | No state change | | 7 | PerformStoredValueAction | SESSION\_OPEN | AWAITING\_TERMINAL | No state change | | 8 | PerformPayment | SESSION\_OPEN | PAYMENT\_PROCESSING | No state change | | 9 | HandleResponse | LOGGED\_IN | SESSION\_OPEN | PAYMENT\_PROCESSING | | 10 | EndSession | LOGGED\_IN | SESSION\_OPEN | NA | | 11 | Reconcile | LOGGED\_IN | SESSION\_OPEN | AWAITING\_TERMINAL | | 12 | QueryTransactions | LOGGED\_IN | SESSION\_OPEN | AWAITING\_TERMINAL | | 13 | ReprintReceipt | LOGGED\_IN | SESSION\_OPEN | NA | | 14 | Logout | LOGGED\_IN | SESSION\_OPEN | NA | | 15 | PresentContent | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 16 | RequestInput | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 17 | DeviceManagementCommand | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 18 | GetState | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 19 | Abort | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 20 | Print | NOT\_LOGGED\_IN | SESSION\_OPEN | NA | | 21 | Encryption | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 22 | DeviceVitals | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | | 23 | Pin | LOGGED\_IN | SESSION\_OPEN | NA | | 24 | Teardown | NOT\_LOGGED\_IN | LOGGED\_IN | SESSION\_OPEN | Logging in (TransactionManager.login(...)) informs the POI that a cashier is present, and enables the POI to download/configure itself based on the cashier ID. Starting a session (TransactionManager.startSession(...)) reserves the POI for use by the POS, enabling an order to be built and payments to be processed. There should only be one “order” per session, where an order is an optional collection of basket items and a set of payments/refunds/voids, all associated with a single Invoice ID. It is acceptable to manage a single order across multiple sessions, but it’s not recommended to handle multiple orders within a single session. Starting a payment or performing some other payment-related action will move it to the payment processing state. {% endstep %} {% step %} ### Transaction Flow The following diagram illustrates the PSDK transaction flow:
{% endstep %} {% step %} ### State Management There are 3 states in particular: 1. **TransactionManager.STATE\_LOGGED\_IN** 2. **TransactionManager.STATE\_SESSION\_OPEN** 3. **TransactionManager.STATE\_PAYMENT\_PROCESSING** Some commands will only work in a specific state, though commands that work in an earlier state will also work in a later state (except for **TransactionManager.STATE\_PAYMENT\_PROCESSING**). For example, `ReportManager.queryTransactions(query)` will work once logged in, as well as during a session and the transitions between, but will not work while a payment is in progress, because the POI is completely dedicated to handling the payment during that state. The current state can be synchronously retrieved using `TransactionManager.getState()`. **Logging in** (`TransactionManager.login(...)`) informs the POI that a cashier is present, and enables the POI to download/configure itself based on the cashier ID. **Starting a session** (`TransactionManager.startSession(...)`) reserves the POI for use by the POS, enabling an order to be built and payments to be processed. There should only be one "order" per session, where an order is an optional collection of basket items and a set of payments/refunds/voids, all associated with a single Invoice ID. It is acceptable to manage a single order across multiple sessions, but it's not recommended to handle multiple orders within a single session. Starting a payment or performing some other payment-related action will move it to the payment processing state. {% hint style="info" %} **Note:** There are some actions that can be performed without a session active but after login, primarily actions on the ReportManager. Other actions, related to setting parameters such as TransactionManager.setDeviceParams(Map) or TransactionManager.getDeviceInformation() can be performed even before login. {% endhint %} {% endstep %} {% step %} ### Android Initial Setup Guide **Adding PaymentSDK Library to the Android Project** 1. Place `PaymentSDK-xxxxx.aar` file in the project at a specific location (e.g., `Project/app/libs`). 2. Go to `File` -> `Project Structure` -> `Dependencies`, select `Modules(app)`, select '+', choose `Jar dependency`, provide the file path, and choose configuration as `implementation`. 3. Go to `File` -> `Project Structure` -> `Modules` -> `app` -> `DefaultConfig` -> `Min SDK Version`, set `minSdkVersion` to 24 and above. 4. AndroidX and other configuration options are required to use any Activities or Fragments provided by the PSDK. 5. If the reference apps are being compiled on newer versions of Mac (M1 or M2), make sure to enable Rosetta on the machines. 6. The `targetSdkVersion` must be 26 or greater. 7. `android.useAndroidX=true` and `android.enableJetifier=true` must be set in the project's `gradle.properties` file. 8. The module's gradle file must have data binding enabled, and the compile options compatibility must support 1.8 or greater. {% code overflow="wrap" lineNumbers="true" %} ```java android { dataBinding { enabled = true } compileOptions { sourceCompatibility 1.8 targetCompatibility 1.8 } } Add the following dependencies to the application's build.gradle. The versions can be updated as needed. implementation 'androidx.appcompat:appcompat:1.1.0' implementation 'androidx.constraintlayout:constraintlayout:1.1.3' implementation 'androidx.recyclerview:recyclerview:VERSION' Make sure to replace VERSION with the desired version number for the recyclerview dependency. ``` {% endcode %} {% endstep %} {% step %} ### 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”. {% endstep %} {% step %} ### Windows Dot NET Initial Setup Guide **Visual Studio Project Setup** 1. Open Visual Studio installer, and then install .Net Framework 4.6. 2. Open DotNetReferenceApp.sln in the Visual Studio. 3. Inside Solution Explorer, in project DotNetReferenceApp.sln, right click “References”, and then add VerifoneSdk dll. 4. Deploy on local machine with green start menu. {% endstep %} {% step %} ### 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:". 2. At "Destination:", put a tick mark at "Copy items if needed". 3. At "Added folders:", select "Create folder references". 4. At "Add to targets:", select the project. 5. Click on the main project file, under "TARGETS" select the project. 6. Go to the "General" tab. 7. Click on the small triangle at "Frameworks, Libraries and Embedded Content". 8. Select "PaymentSdk.xcframework". 9. Under "Embed", select "Embed & Sign". 10. Update the project's Info.plist. **Add these privacy usage descriptions.** * NSBluetoothAlwaysUsageDescription * NSBluetoothPeripheralUsageDescription * NSCameraUsageDescription **Add Supported external accessory protocols "UISupportedExternalAccessoryProtocols" if you are using Bluetooth.** * com.verifone.pmr.xpi * com.verifone.pmr.debug * com.verifone.pmr.control * com.verifone.pmr.barcode * com.verifone.pmr.zontalk {% endstep %} {% step %} ### Windows Initial Setup Guide **Visual Studio Project Setup** 1. Open the Visual Studio installer. 2. Click "Modify" on the Visual Studio tile. 3. Select "Modify" on the Visual Studio tile. 4. In the "Workloads" tab, select the "Universal Windows Platform development" tile. 5. In the "Individual Components" tab, select the compatible version of the "Windows SDK" checkbox. 6. Click "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). 7. To enable logging in Visual Studio to show PSDK logs, follow these steps: 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)." 8. To enable network access for inbound and outbound, open `Package.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. Navigate to `Tools` -> `NuGet Package Manager` -> `Manage NuGet Packages for Solution`. 3. In Package source, there will be a settings button; click it 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 will show up once the package source is added correctly. {% endstep %} {% step %} ### Linux Initial Setup Guide **CMake project setup** 1. Install a C++17 compatible compiler toolchain. Refer to your distribution documentation for more information. 2. Install CMake. See [CMake Official Website](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 the following content: ```cpp #include #include #include #include #include "CommerceListener2.hpp" #include "CommerceEvent.hpp" #include "NativePlatformContext.hpp" #include "PaymentSdkInterface.hpp" #include "PlatformContextInterface.hpp" #include "PsdkDeviceInformation.hpp" #include "ScannerDataEvent.hpp" #include "ScannerStateEvent.hpp" #include "Status.hpp" #include "StatusCode.hpp" #include "TransactionEvent.hpp" #include "AmountAdjustedEvent.hpp" #include "BasketAdjustedEvent.hpp" #include "BasketEvent.hpp" #include "CardInformationReceivedEvent.hpp" #include "DeviceManagementEvent.hpp" #include "LoyaltyReceivedEvent.hpp" #include "PaymentCompletedEvent.hpp" #include "ReceiptDeliveryMethodEvent.hpp" #include "ScannerDataEvent.hpp" #include "StoredValuedCardEvent.hpp" #include "UserInputEvent.hpp" #include "ReconciliationEvent.hpp" #include "ReconciliationsListEvent.hpp" #include "TransactionQueryEvent.hpp" #include "HostAuthorizationEvent.hpp" #include "HostFinalizeTransactionEvent.hpp" #include "NotificationEvent.hpp" #include "PrintEvent.hpp" #include "DeviceVitalsInformationEvent.hpp" #include "PinEvent.hpp" // Converts a listener class to using lambdas class Listener : public verifone_sdk::CommerceListener2 { public: typedef std::function HandleEventListener; Listener(HandleEventListener listener) : listener_(listener) {} ~Listener() override = default; void handleCommerceEvent(const std::shared_ptr &event) override { listener_(event->getStatus()); }; void handleTransactionEvent(const std::shared_ptr & event) override { listener_(event->getStatus()); } // ... // (The rest of the functions) // ... private: HandleEventListener listener_; }; int main() { std::unordered_map 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::CreateNativePlatformContext(std::nullopt)); auto listener = std::make_shared([&last_status](const int &status) { last_status = status; }); 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 the following content (replacing placeholders \, \ with full paths and the appropriate library name): ```cmake 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 "/include") target_link_libraries(PSDK_Test "/lib/") ``` Generate make files and compile the executable by running the following commands in the PROJ\_DIR: ```sh 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 a successful linking: ```sh ./PSDK_Test ``` {% endstep %} {% endstepper %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verifone.com/psdk-latest/reference-material/code-labs/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.