Getting Started

Initialize Payment SDK and Get Transaction Manager

The first step is to create and initialize the Payment SDK, after which an instance of the TransactionManager can be acquired. The Payment SDK may be initialized in server mode, in which it listens for a connection from the payment device, or client mode, in which it connects to a specified payment device. In client client/server description, no context passed to getDeviceInformation() mode, the Payment SDK may be connecting to a payment device under three scenarios: the first connection, in which the address information of the target device must be specified, a subsequent connection, in which the previous connection information is persisted, or a changed target address, in which the persisted connection information must be wiped out, and replaced with the new connection information. Each of these scenarios is depicted below in the code samples. These code samples are organized to easily perform the initialization from the background, but this can be done in a variety of ways, and should be consistent with the existing design instead of doing this exact code.

Client Mode Initialization

Server Mode Initialization

Device setup via Bluetooth

To connect via Bluetooth or Bluetooth PAN using tethering, the Bluetooth Device Setup functionality will allow pairing with a new device and will prompt the user with messages if necessary bluetooth settings are not enabled.

Connecting to a New Device

In the situation in which a previously connected device is being replaced, if the logical ID of the new device as assigned by VHQ is different than the original logical ID, or if the original device did not have a logical ID, then the old device information must be wiped out of persistent storage and initialized with a configuration which contains the new information. The code sample below assumes a client mode initialization.


TransactionManager.getTransactionManager() is no longer available. Please see Migration from PSDK 2.x to 3.x.

Create a Commerce Listener

A listener must be created so that the Paymentsdk Initialize and Teardown status are available for the POS. It also processes various events derived from CommerceEvent. There must be at least one valid listener while a session is open, the last listener cannot be removed during this state. The listener must be passed to PaymentSdk.initialize(...), PaymentSdk.initializeFromValues(...) and PaymentSdk.initializeFromFile(...)

Create the CommerceListenerAdapter. The POS can override handle methods that it is interested in. The event type can be determined by calling the CommerceEvent.getType() method.


Login / Logout

After initialization is complete, the transaction manager can be retrieved. Once the transaction manager is obtained and bound, it’s time to login. The login and logout calls should match the presence of the cashier at the station, when the cashier logs in to the device, call TransactionManager.loginWithCredentials(), if the cashier logs out or is logged out automatically, call TransactionManager.logout(). If there is no authentication mechanism for the cashier, then login should be called when the device wakes, and logout when the device sleeps.

Start a Session

After login, it is necessary to start a session for the transaction. An instance of the CommerceListenerAdapter which was passed in the PaymentSdk.initialize() method acts as the listener for events passed back from TransactionManager. Building on the example above, after login is completed we can start the session. Once we have a session open, items can be added to the POI display and payments can be processed.