Local Integration with iOS

Overview

This document serves as a complete reference guide for individuals seeking to utilize the Pine Labs iOS PoSlib SDK. Its primary focus is to assist in the acceptance of payments, processing of transactions, and the seamless return of payment results to the invoking payment terminal application.

The Billing System can be integrated into the iOS platform in a single way namely Off-Device Integration.

In Off-Device integration approaches, the Merchant Billing application should use the PoSLib to communicate with the PineLabs Payment Application via PoSBridge.

The following sections provide detailed insights into Off-Device Integration processes.

Off-Device Integration

In this approach, the Merchant Billing application, running on iOS devices such as tablets or mobile phones, communicates with the Pine Labs Payment application by integrating the iOS PoSlib. The iOS PoSlib facilitates communication with the pinelabs Payment application via PoSBridge.

The Merchant Billing application needs to integrate PoSlib to communicate with the PoSBridge application through PoSLib APIs. The message exchange between PoSLib and PoSBridge can occur over IP.

The Billing System communicates with PoSBridge application via PoSLib APIs. Message exchange between PoSLib and PoSBridge can happen over IP. The Billing System running on the PineLabs Payment Terminal has the capability to perform transactions via app-to-app communication.

The following sequence diagram describes the transaction flow:

Merchant Billing Application shall be integrated with PoSLib to perform transactions with Payment application

1. Merchant Billing Application calls scan & connect IP via PoSLib APIs.
2. PoSLib will send device discovery request to connect with PoSBridge.
3. PoSBridge will respond with the device connected status.
4. Merchant Billing Application will fetch transaction details.
5. Merchant Billing Application sends the transaction request to PoSLib by calling 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 PineLabs Payment Application.
8. PineLabs Payment Application will process the transaction request and sends the payment request to payment controller for authorization.
9. Payment controller sends the payment authorization response to PineLabs payment Application.
10. PineLabs Payment Application will process the payment authorization response and sends 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 Merchant Billing Application.

Supported Features

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

PoSLib framework Integration

This section describes the pre-requisites and steps to integrate POSLib framework with the Merchant Billing Application.

Pre-requisites

• Ensure you have latest version PoSLib.
  
• Ensure you have latest version of XCode (14.x) installed in your system.

Steps to integrate PoSLib

Step 1: Add generated PosLib.xcframework into the Billing Application for debug and release inside Archives -> Binaries -> extracted file -> PosLib.xcframework.

Step 2: Import iOS PoSLib Framework into frameworks folder which is generated in Archives -> Binaries -> PosLib-Bitcode-Debug -> PosLib.xcframework.
Add PosLib.xcframework from framework folder as an embedded content in Billing application project settings (as shown below).

Step 3: Add Local Network Usage Description, Bonjour Services, Bluetooth Always Usage Description and Supported external accessory protocols to info.plist of the Billing Application.

API Integration

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

Note: The sample code snippets provided in this document are currently supported only in Swift. These code snippets might have to be customized if you want to test them on Objective-C.

PosLibServicesImpl

This API shall be used to Initialize the PoSlib. This shall be the first API to be called.

Code snippet for posLibInitialize:

Initialize PoSLib using the following code:

              

                
Swift
              Copy Code
              
              
              

    override func viewDidLoad() {
      super.viewDidLoad()
      
      // Create an instance of PosLibServicesImpl
      posLibServices = PosLibServicesImpl()
      
      // Set the text of the "lblVersion" label to display the application version
      self.lblVersion.text = "Version: \(posLibServices!.getPosLibVersion())"
  }

scanOnlinePOSDevice

This API will discover/Scan the PinLabs payment terminals on the same network where PoSBridge is running on it and list them.

Code snippet for scanOnlinePOSDevice:

            

              
Swift
            Copy Code
          
          
 @IBAction func scanTCPIPDevices(_ sender: UIButton) {
  
	if (networkIP != nil) {
 	 // Initiate the scanning process for online POS devices
  	posLibServices!.scanOnlinePOSDevice(transactionListener: self)
	}
	else {
	//Invalid Conditions	
	}
}
  

ConfigData Details

This class will have the details of the device which will be used during discovery/scan over IP.

Code snippet for ConfigData Details

            

              
Swift
            Copy Code
          
          
@objc public class ConfigData: NSObject {
         var cashierID: String = ""
         var cashierName: String = ""
         var connectionFallback: Bool = false
         var connectionPriority: String = ""
         var connectionTimeout: Int = 0
         var connectionRetries: Int = 0
         var tcpIP: String = ""
         var tcpPort: Int
         var btDeviceName: String = ""
         var btDeviceSSID: String = ""
         var networkIpTest: Bool = false;
     }

setConfiguration

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

Code snippet for setConfiguration:

            

              
Swift
            Copy Code
          
          
func saveConfigurations() {
        let configData = ConfigData(cashierID: self.settingsItem.cashierID,
                   cashierName: self.settingsItem.cashierName,
                   connectionFallback: self.settingsItem.poslibLogsRequired,
                   connectionPriority: self.settingsItem.connectionPriority,
                   connectionTimeout: self.settingsItem.connectionTimeout,
                   connectionRetries: self.settingsItem.connectionRetries,
                   tcpIP: self.settingsItem.tcpIP,
                   tcpPort: "\(self.settingsItem.tcpPort)",
                   btDeviceName: self.settingsItem.btDeviceName,
                   btDeviceSSID: self.settingsItem.btDeviceSSID)

        posLibServices!.setConfiguration(configData: configData)
    }

getConfiguration

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

Code snippet for getConfiguration:

            

              
Swift
            Copy Code
          
          
@IBAction func testTCPIPConnection(_ sender: UIButton) {
  if (UserDefaults.standard.bool(forKey: "networkStatus") {
     	let configData = posLibServices!.getConfiguration()
   }
  else {
      //showing alert to enable network to getConfig details and other conditions as well
  }
}

comTest

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

Code snippet for comTest:

            

              
Swift
            Copy Code
          
          
 @IBAction func testTCPIPConnection(_ sender: UIButton) {
   if (networkIP != nil || (UserDefaults.standard.bool(forKey: "networkStatus”))) {
       posLibServices?.comTest(tcpIp: configData.getTcpIP(), tcpPort: "\(configData.getTcpPort())", transactionListener: self)
   }
   else {
	// Checking Other conditions
   }
}

doTransaction

This API will be used to perform transaction with iOS Payment Application.

Code snippet for doTransaction:

            

              
Swift
            Copy Code
          
          
@IBAction func processTransactionAction(_ sender: UIButton) {
var msgType: Int // take required message type for txn to proceed
let txnTypeValue = Constant.transactionValuesList[self.selectedTransaction]
let csvString = PosHelper.shared.getCSVStringForTxn((txnTypeValue)!, Constant.TXN_NUM, self.amountTextField.text!)
let requestBody = PosHelper.shared.getPaymentPacket(csvString)
if (requestBody != "") {
  posLibServices!.doTransaction(paymentRequest: requestBody, transactionType: msgType, transactionListener: self)
 }
 else {
  /*ERROR CONDITIONS*/
 }
}
Note : Please refer Transaction type in API's section for more information click here