Local Integration with Windows OS

Overview

This document serves as a complete reference guide for individuals seeking to utilize the Pine Labs Windows PoSLib library and PoS Controller for integration with the billing system. Its primary focus is to assist in the acceptance of payments, processing of transactions, and the seamless return of payment results to the invoking application.

The billing system can be integrated Windows platform in two different ways:

• Direct Integration with PoSLib (Library)
• Integration with PoS Controller

In both type of integration, the Merchant Billing application communicates with the Pine Labs Android Payment application through PoSBridge. Therefore, the merchant should ensure that PoSBridge is running on the Android payment terminal before initiating any transactions from the billing application.

The following sections provide detailed insights into both direct integration with PoSLib and Integration with PoS Controller.

PoSLib Integration

In this approach, the merchant billing application, running on Windows OS, communicates with the Pine Labs payment application by integrating the java/dotNet PoSLib. PoSLib facilitates communication with the Pine Labs Android payment application via PoSBridge.

The merchant billing application needs to integrate PoSLib to communicate with the PoS Bridge through PoSLib APIs. The message exchange between PoSLib and PoS Bridge can occur over IP and COM (USB/Serial).

• Merchant billing applications built on Java should integrate the Java PoSLib provided.
• Merchant billing applications built on dotNet should integrate the dotNet PoSLib provided.

The following sequence diagram describes the transaction flow:

The merchant billing application should be integrated with the respective PoSLib to perform transactions with the Android payment application.

1. Merchant Billing Application calls scan and connect IP and COM devices via PoSLib APIs.
2. PoSLib will send a device discovery request to connect with PosBridge.
3. PoSBridge will respond with the connected device status.
4. The merchant billing application will fetch transaction details.
5. The merchant billing application sends the transaction request to PoSLib by calling the doTransaction API.
6. PoSLib will process the doTransaction and forward the transaction request to PoSBridge.
7. PoSBridge will process the doTransaction request and forward the transaction request to the Pine Labs payment application.
8. The Pine Labs payment application will process the transaction request and send the payment request to the Pine Labs Payment Processing Engine for authorization.
9. The Pine Labs Payment Processing Engine sends the payment authorization response to the Pine Labs payment application.
10. Pine Labs payment application will process the payment authorization response and send the doTransaction response to PoSBridge.
11. PoSBridge will process the doTransaction response and forward the doTransaction response to PoSLib.
12. PoSLib will process the doTransaction response and forward the doTransaction response to the merchant billing application.

Supported Features

The following features (APIs) are supported by Windows PoSLib:

Steps to Integrate PoSLib

JAVA PoSLib:

• Step 1: Download the PoSLib from here and extract.
• Step 2: Copy the JAR file into the PoSLibjar folder of the project on your local drive.
• Step 3: Launch STS, and go to Project => Build Path => Configure the build path.
• Step 4:  Click “Add External JARs”.
• Step 5: Select all the .jar files from the extracted from the package.
• Step 6: Click “Apply and Close.”

DotNet PoSLib:

• Step 1: Download the PoS Lib from here and extract.
• Step 2: Copy the PoSLibs.ECRLibrary.dll file into the PoSLib folder of the project on your local drive.
• Step 3: Go to Project => Solution Explorer => Right Click on dependencies => Click on Add Project Reference
• Step 4:  Reference Manager => Click Browse
• Step 5: Select PoSLibs.ECRLibrary.dll file from PoSLib folder => Click Add
  
  

Steps to Integrate PoSLib with Billing System

• Step 1: Download PoSLib from here and Extract
• Step 2: Copy the extracted .aar file into libs folder in your project.
• Step 3: Launch Android Studio.
• Step 4: In build.gradle file under dependency include .aar file like below

• 

API Integration

The following section describes the APIs exposed by PoSLib, details of the API, and integration sample code snippets.

Same API specification for both Dotnet and java.

scanOnlinePoSDevice

This API will auto-discover the Android payments terminals on the same network where PoSBridge is running on it and list them.

Code snippet for scanOnlinePoSDevice:

                    

                      
Java
                    Copy Code
                    
                    
                    
 
      public class Device {
      
        private String deviceIp;
        private String devicePort;
        private String devId;
        private String slNo;
        private boolean isCom;
        private String comPortNumber;
        private String comDevId;
        private String comslno;
      }
      ScanDeviceListener scanDeviceListener = new ScanDeviceListener() {
            
        @Override
        public void onSuccess(List list) {
        // Retrieve the device list here
            
        }
        
        @Override
        public void onFailure(String errorMsg, int errorCode) {
        // Handle error here
              
        }
      };
      PosLib.getInstance().scanOnlinePOSDevice(scanDeviceListener);

                  

                    
DotNet
                  Copy Code
                  
                  
                  
 
      public class ScanLisnter : IScanDeviceListener
        {
                  public void onFailure(string errorMsg, int errorCode)
           {
           Console.WriteLine("Error Message");
           }
      
           public void onSuccess(List list)
           {
               if (list != null)
               {
                   serialdevice = list;
               }
           }
       }
      
      ScanLisnter deviceslisnter = new ScanLisnter();
      ConnectionService obj = new ConnectionService();
      obj.scanOnlinePOSDevice(deviceslisnter);	

scanSerialDevice

This API will be used to auto-discover PoS devices through COM.

Code snippet for scanSerialDevice:

                    

                      
Java
                    Copy Code
                    
                    
                    

      public class Device {
      
        private String deviceIp;
        private String devicePort;
        private String devId;
        private String slNo;
        private boolean isCom;
        private String comPortNumber;
        private String comDevId;
        private String comslno;
      }
      ScanDeviceListener scanDeviceListener = new ScanDeviceListener() {
            
          @Override
          public void onSuccess(List list) {
            // Retrieve the device list here
              
          }
            
          @Override
          public void onFailure(String errorMsg, int errorCode) {
            // Handle error here
              
          }
      };
      PosLib.getInstance().scanSerialDevice(scanDeviceListener); 

                  

                    
DotNet
                  Copy Code
                  
                  
                  

      public class ScanLisnter : IScanDeviceListener
           {
               public void onFailure(string errorMsg, int errorCode)
               {
                   Console.WriteLine("Error Message");
               }
      
               public void onSuccess(List list)
               {
                   if (list != null)
                   {
                       serialdevice = list;
                   }
               }
           }
      
          ScanLisnter deviceslisnter = new ScanLisnter();
          ConnectionService obj = new ConnectionService();
          obj.ScanSerialDevice(deviceslisnter);
      
        

setConfiguration

This API should be used to set PoS Library configurations related to connectivity, priority settings, and logging options.

Code snippet for setConfiguration:

                    

                      
Java
                    Copy Code
                    
                    
              
 
      public class ConfigData {
        private String tcpIP;
        private String tcpPort;
        private String devId;
        private String slNo;
        private String comPortNumber;
        private String comslno;
        private String comDevId;
        private int retryCount;
        private int connectionTimeOut;
        private boolean isConnectivityFallBackAllowed;
        private int priority1;// 1=TCPIP , 2=COM
        private int priority2;// 1=TCPIP , 2=COM
        private String logPath;
        private boolean isLogsEnabled;
        private int logLevel;
        private int dayToRetainLogs;
        private String cashierId;
        private String cashierName;
      }
      
      ConfigData configData = new ConfigData();
      configData.setComPortNumber("");
        configData.setConnectionTimeOut(30);
        configData.setConnectivityFallBackAllowed(false);
        configData.setPriority1(1);
        configData.setPriority2(2);
        configData.setTcpIP("");
        configData.setTcpPort("");
        configData.setRetryCount(2);
        configData.setDayToRetainLogs(2);
        configData.setLogPath("433a");
        configData.setLogsEnabled(false);
        configData.setLogLevel(1);
        configData.setDevId("");
        configData.setSlNo("");
        configData.setComslno("");
        configData.setCashierId("");
        configData.setCashierName("");
      configData.setComDevId(" ");
      PosLib.getInstance().setConfiguration(configData);

                  

                    
DotNet
                  Copy Code
                  
                  
            
 
      public class ConfigData
          {
          public ConfigData()
              {
                  tcpIp = string.Empty;
                  connectionMode = string.Empty;
                  CashierID = string.Empty;
                  CashierName = string.Empty;
                  comfullName = string.Empty;
                  comserialNumber = string.Empty;
                  tcpIpaddress = string.Empty;
                  retry = string.Empty;
                  connectionTimeOut = string.Empty;
                  retainDay=string.Empty;
                  tcpIpPort = string.Empty;
                  logtype = string.Empty;
                  tcpIpDeviceId = string.Empty;
                  tcpIpSerialNumber = string.Empty;
                  comDeviceId = string.Empty;
                  LogPath = string.Empty;
                  loglevel = string.Empty;
              }
              public int commPortNumber { get; set; }
              public string tcpIp { get; set; }
              public int tcpPort { get; set; }
              public string connectionMode { get; set; }
              public string[] communicationPriorityList { get; set; } = Array.Empty();
              public bool isConnectivityFallBackAllowed { get; set; }
              public string CashierID { get; set; }
              public string CashierName { get; set; }
              public string retry { get; set; }
              public string connectionTimeOut { get; set; }
              public string comfullName { get; set; }
              public string comserialNumber { get; set; }
              public string tcpIpaddress { get; set; }
              public string tcpIpPort { get; set; }
              public string tcpIpDeviceId { get; set; }
              public string tcpIpSerialNumber { get; set; }
              public string comDeviceId { get; set; }
              public string LogPath { get; set; }
              public string loglevel { get; set; }
              public bool isAppidle { get; set; }
              public string retainDay { get; set; }
              public string logtype { get; set; }
      
          }
      
           ConnectionService _con=new ConnectionService();
           ConfigData configdata=new ConfigData
           configdata.tcpIp = tcp;
           configdata.tcpPort =tcpPort;  
          _con.setConfiguration(configdata);

getConfiguration

This API should be used to retrieve PoS Library configurations related to connectivity, priority settings, and logging options.

Code snippet for getConfiguration:

                    

                      
Java
                    Copy Code
                    
                    
                    
 
      public class ConfigData {
        private String tcpIP;
        private String tcpPort;
        private String devId;
        private String slNo;
        private String comPortNumber;
        private String comslno;
        private String comDevId;
        private int retryCount;
        private int connectionTimeOut;
        private boolean isConnectivityFallBackAllowed;
        private int priority1;// 1=TCPIP , 2=COM
        private int priority2;// 1=TCPIP , 2=COM
        private String logPath;
        private boolean isLogsEnabled;
        private int logLevel;
        private int dayToRetainLogs;
        private String cashierId;
        private String cashierName;
      }
      
      ConfigData configData = new ConfigData();
      int result = PosLib.getInstance().getConfiguration(configData);
          

                  

                    
DotNet
                  Copy Code
                  
                  
                  
 
      public class ConfigData
         {
             public ConfigData()
             {
                 tcpIp = string.Empty;
                 connectionMode = string.Empty;
                 CashierID = string.Empty;
                 CashierName = string.Empty;
                 comfullName = string.Empty;
                 comserialNumber = string.Empty;
                 tcpIpaddress = string.Empty;
                 retry = string.Empty;
                 connectionTimeOut = string.Empty;
                 retainDay=string.Empty;
                 tcpIpPort = string.Empty;
                 logtype = string.Empty;
                 tcpIpDeviceId = string.Empty;
                 tcpIpSerialNumber = string.Empty;
                 comDeviceId = string.Empty;
                 LogPath = string.Empty;
                 loglevel = string.Empty;
             }
             public int commPortNumber { get; set; }
             public string tcpIp { get; set; }
             public int tcpPort { get; set; }
             public string connectionMode { get; set; }
             public string[] communicationPriorityList { get; set; } = Array.Empty();
             public bool isConnectivityFallBackAllowed { get; set; }
             public string CashierID { get; set; }
             public string CashierName { get; set; }
             public string retry { get; set; }
             public string connectionTimeOut { get; set; }
             public string comfullName { get; set; }
             public string comserialNumber { get; set; }
             public string tcpIpaddress { get; set; }
             public string tcpIpPort { get; set; }
             public string tcpIpDeviceId { get; set; }
             public string tcpIpSerialNumber { get; set; }
             public string comDeviceId { get; set; }
             public string LogPath { get; set; }
             public string loglevel { get; set; }
             public bool isAppidle { get; set; }
             public string retainDay { get; set; }
             public string logtype { get; set; }
      
          }
        ConnectionService _con=new ConnectionService();
        ConfigData configdata=new ConfigData
        configdata = _con.GetConfigData()!;
      

testTCP

This API will verify connectivity between the merchant billing system and the Android payment terminal in IP connectivity mode.

Code snippet for testTCP:

                  

                    
Java
                  Copy Code
                  
                  
                  
  
        boolean result = PosLib.getInstance().testTcp(ip, port);
        

                

                  
DotNet
                Copy Code
                
                
                
  
      boolean isOnlineDevice = obj.testTCP(tcpip.Text, int.Parse(tcpport.Text), comListener);
      

testSerialCom

This API will verify connectivity between the merchant billing system and the Android payment terminal in COM connectivity mode.

Code snippet for testSerialCom:

                  

                    
Java
                  Copy Code
                  
                  
          
boolean result = PosLib.getInstance().testSerialCom(comPort);

                

                  
DotNet
                Copy Code
                
                
        
isOnlineDevice = obj.testSerialCom(int.Parse(intvalue), comListener);

checkComStatus

Code snippet for checkComStatus:

                  

                    
Java
                  Copy Code
                  
                  
                  
 ComEventListener comEventListener = new ComEventListener() {
         
         @Override
         public void onEvent(int eventId) {
           switch (eventId) {
           case 1000:
           // TCP Connected and Payment app is UP
           // Status: Active
           break;
         
           case 1001:
           // TCP Disconnected
           // Status: Inactive
           break;
         
           case 1003:
           // TCP error
           // Status: Inactive
           break;
           case 3000:
           // TCP Connected and Payment app is down
           // Status: Inactive
           break;
           case 2000:
           // com Connected and Payment app is UP
           // Status: Active
           break;
           case 2001:
           // com Disconnected
           // Status: Inactive
           break;
           case 2003:
           // com error
           // Status: Inactive
         
           break;
           case 3001:
           // com Connected Payment app is down
           // Status: Inative
           break;
           default:
           // Unknown Event ID
           break;
           }
         
         }
         };
         PosLibManager.getInstance().checkComStatus(comEventListener);

                

                  
DotNet
                Copy Code
                
                
                
public string checkComStatus()
            {
                Log.Debug("Entering checkComStatus() method");
    
                if (configdata.isAppidle)
                {
                    if (testSerialCom(configdata.commPortNumber, comListener) && comListener.successcodemsg== PosLibConstant.COMERRORCODESUCESS)
                    { 
                        Log.Information("in comEventListener on onEvent : " + comListener.successcodemsg);
                        Log.Information("in comEventListener COM : Connected ");
                        CheckPaymentHealthCheckRequest comhealthcheckrequest = new CheckPaymentHealthCheckRequest();
                        string requestbody = comhealthcheckrequest.CheckCompHealthRequest();
                        bool status = CheckBothConnection(configdata.commPortNumber, requestbody);
                        if (status)
                        {
                            return PosLibConstant.COMHEALTHACTIVE;
                        }
                        else
                        {
                            return PosLibConstant.COMHEALTHINACTIVE;
                        }
                    }
                    else
                    {
                        Log.Information("in comEventListener on onEvent : " + comListener.errorcodemsg);
                        Log.Information("in comEventListener COM : DisConnected ");
                        return PosLibConstant.COMHEALTHINACTIVE;
                    }
                }
                else
                {
                    return PosLibConstant.COMHEALTHINACTIVE;
                }
            }
        ConnectionService obj = new ConnectionService();
        string checkstatus = obj.checkComStatus();

checkTcpComStatus

Code snippet for checkTCP/IPStatus:

             

               
DotNet
             Copy Code
             
             
             
 public string checkTcpComStatus()
                {
                    if (string.IsNullOrWhiteSpace(configdata.tcpIpPort) || string.IsNullOrWhiteSpace(configdata.tcpIp))
                    {
                        return PosLibConstant.TCPIPHEALTHINACTIVE;
                    }
                    if (!testTCP(configdata.tcpIp, configdata.tcpPort, comListener))
                    {
                        LogInformation("TCPIP : Disconnected", comListener.errorcodemsg);
                        return PosLibConstant.TCPIPHEALTHINACTIVE;
                    }
                    LogInformation("TCPIP : Connected", comListener.successcodemsg);
                    if (string.IsNullOrWhiteSpace(configdata.tcpIp) || !configdata.isAppidle || string.IsNullOrWhiteSpace(configdata.tcpIpPort))
                    {
                        return PosLibConstant.TCPIPHEALTHINACTIVE;
                    }
                    CheckPaymentHealthCheckRequest healthCheckRequest = new CheckPaymentHealthCheckRequest();
                    string requestBody = healthCheckRequest.CheckTcpIpHealthRequest();
                    bool isTerminalReachable = IsHostReachable(configdata.tcpIpaddress, int.Parse(configdata.tcpIpPort), requestBody);
                    return isTerminalReachable ? PosLibConstant.TCPIPHEALTHACTIVE : PosLibConstant.TCPIPHEALTHINACTIVE;
                }
                ConnectionService obj = new ConnectionService();
                string checkstatus = obj.checkTcpComStatus();

doTransaction

This API will be used to perform transactions with the Android Payment Application.

Code snippet for doTransaction:

                  

                    
Java
                  Copy Code
                  
                  
                  
  
        String transactionRequest = null; //Required only for TxnType 6 (Payment Transaction)		
        transactionRequest = "4001,TX12345678,10000,,,,,,"; //sale transaction request	
        transactionRequest = "5101,TX12345678,10000,,,,,,"; //Bank EMI transaction request
        transactionRequest = "5002,TX12345678,10000,,,,,,"; //Brand EMI transaction request
        transactionRequest = "5120,TX12345678,10000,,,,,,"; //UPI transaction request
            
        int TxnType; //payment transaction type
        TxnType = 6; //Payment transaction
        TxnType = 9; //get last transaction
            
        TransactionListener transactionListener = new TransactionListener() {
              
          @Override
          public void onSuccess(String paymentResponse) {
          // success
        //Convert the payment response from CSV hex string format to byte array format and parse the CSV response.
                
          }
              
          @Override
          public void onNext(String action) {
          // listner for onNext action
                
          }
              
          @Override
          public void onFailure(String errorMsg, int errorCode) {
          // failure
          //Handle error message and error code here
              
          }
        };
        PosLib.getInstance().doTransaction(transactionRequest, transactionListener);
  

                

                  
DotNet
                Copy Code
                
                
                
  
    public class TransactionDrive : ITransactionListener
        {
            public void OnFailure(string errorMsg, int errorCode)
            {
                MessageBox.Show(errorMsg, errorCode.ToString());
            }
            public void OnNext(string action)
            {
                throw new NotImplementedException();
            }
            public void OnSuccess(string paymentResponse)
            {
                resp = paymentResponse;
            }
        }
       TransactionService trxobj = new TransactionService();
       trxobj.DoTransaction(afterreplace, int.Parse(transactionType), transactionDrive);

PoS Controller Integration

In this approach, the Merchant Billing application running on Windows OS, communicates with the Pine Labs payment application by integrating the PoS Controller. The Pos Controller facilitates communication with the Pine Labs Android payment application via the PoSBridge.

PoS Controller is software that offers a user-friendly interface for integrators. It allows them to scan and set up various communication modes (IP and COM), manage logging, and configure other communication settings.

• The PoS Controller is integrated with PoSLib and supports all the PoSLib features with a rich UI experience.
• All the required configurations related to connectivity and logging can be made on the PoS controller.
• The desktop merchant billing application can establish a connection with the PoS Controller through the localhost on port 8082.
• The web-based billing application can establish connection with the PoS Controller through the http://localhost:8080/web/doTransaction API.

1. Set the connectivity configuration in PoS Controller.
2. PoS Controller sends a device discovery request to connect with PoSBridge.
3. PoSBridge responds with the device-connected status.
4. PoS Controller connects to the devices.
5. The merchant billing application fetches transaction details and sends the transaction request to PoS Controller via local host communication.
6. PoS Controller processes the doTransaction and forwards the transaction request to PoSBridge.
7. PoSBridge processes the doTransaction request and forwards the transaction request to the Pine Labs payment application
8. The Pine Labs payment application processes the transaction request and sends the payment request to the Pine Labs payment Processing Engine for authorization.
9. The Pine Labs payment processing engine sends the payment authorization response to the Pine Labs Payment Application.
10. Pine Labs Payment Application processes the payment authorization response and sends the doTransaction response to PoSBridge.
11. PoSBridge processes the doTransaction response and forwards the response to PoS Controller.
12. PoS Controller processes the doTransaction response and forwards the response to the merchant billing application.

Steps to integrate PoS Controller

1. Make sure all the communication parameters and other required configurations are configured the in PoS Controller application.
2. The billing application should establish a connection with the PoS Controller through the localhost on port 8082.
3. Once the connection is established, the billing application will build the CSV request (as defined in the API section) and send the request to PoS Controller.
4. PoS controller will communicate with the Android payment application based on the communication priorities selected and returns the result to the billing application.

1. Make sure all the communication parameters and other required configurations are configured in the PoS Controller application.
2. The web billing application should establish a connection with the PoS Controller through the through the http://localhost:8080/web/doTransaction API.
3. Once the connection is established, the billing application will build the CSV request (as defined in the API section) and send the request to PosController .
4. PoS controller will communicate with the Android payment application based on the communication priorites selected and returns the result to the billing application .

Steps to install PoS Controller

Step 1: Ensure that your computer meets the minimum system requirements for the software.
Windows 7, 10, and 11

Step 2: Download the PoS Controller software installation package from here.

Step 3: Double-click the downloaded PoS Controller installer file to begin the installation process.

Step 4: Review and accept the software's licence agreement, and complete the installation process by clicking the "Next" button.

Step 5: Once the installation is complete, click the "Finish" button to complete the installation setup.

Step 6: After installation, PoS Controller software will be opened, and a Boot Up Splash screen followed by the Login screen will be displayed. Enter appropriate details in the cashier ID and cashier name fields.

Step 7: Click on the "Save" button to save the cashier's details.

Step 8: Click on the "Setting" button on the home screen to navigate to setting screen.

Step 9: On the Settings screen, configure the settings for fields 2 to 9 as needed.

Step 10: Click on the "Scan for Devices" button to scan for all the available online and COM/Serial devices.
Note: Online devices are those where the PoSBridge is currently operational and connected to the same network as the billing system. COM/Serial devices are those where the PoSBridge is currently operational and connected to the same billing system via COM/Serial cable.

Step 11: Once the devices are scanned, the PoS Controller will list all the available devices (both com/serial and online) in the "Available Devices" panel.

Step 12: Under the "Available Devices" panel, all the available devices are listed with the respective device details (Device ID, Mode, Serial No). User has to select the device based on the details by clicking the select button.
Note:

• "Device ID": Payment terminal device ID
• "Mode": If mode is TCP/IP, it means the device is available to connect over TCP/IP. If mode is COM, it means the device is available to connect over COM/Serial.
• "Serial No": Payment terminal serial number.

Step 13: After selecting the devices under the available devices, the selected devices will be displayed under the respective TCP/IP and COM panes.

Step 14: The user can use the "Connect" button to check the connectivity status of TCP/IP or COM.

Step 15: Click on the "Save Settings" button to save all the configured options.
Note: If the user does not save the configuration, then all the configured values will not be saved in Pos Controller.

Supported Features

Device Discovery

• PoS Controller will auto discover the payment teminals automatically and provide user with the ablity to select the required device to connect.
• The user does not need to enter any of the connectivity details for IP and COM connectivity.
• COM Discovery: The device serial and COM port will be discovered and available to connect.
• IP/Wi-Fi Discovery is performed using the UDP protocol and provides device serial number, IP, and Port details.
• If more than one payment device is available, PoSLib will provide a list of devices to choose from.

Connectivity Features

PoSLib provides the following features for connectivity retention and configuration:

Priority Setting and Auto fallback

• The billing application can set the priority for the available connectivity options
• Auto fallback feature is supported. It can be enabled or disabled based on the requirements. If it is enabled, the device will fallback to a second-priority connection if there is an issue with the primary connection.

Connection Retention & Retry

• The billing application can configure retry counts and connection timeouts
• PoSLib retains the connection data, and applications can directly connect using the saved data.

Logging

PoSLib supports logging options to capture transaction exchanges between billing application and PoSLib.

For Setup and installtion instructions for Android components, please refer to the Terminal Setup section.