Device Connection Criteria

Before attempting to connect to devices such as card readers and printers, the integrator has the option to set the specific connection criteria to use during the device search. This will ensure that Commerce SDK will only attempt to search for the devices specified by the integrator, which will result in a faster connection to the device. The connection criteria are also used for specifying the details of a connection over an IP channel, such as the IP address, port, and encryption type.

Setting the connection configuration is only required if IP connection parameters need to be specified. If not set, Commerce SDK will search for all other supported devices by default.

Note that this method is only used to setup the connection configuration that will be used for future device searches. For an example of performing an actual device search that will use the connection configuration set by this method, see [doclink id=“card-reader-connection”]Card Reader Connection[/doclink].

note

All data transferred over IP has a TLS (formerly known as SSL) encryption scheme where the card reader acts as a server and Commerce SDK is the client.

Timings: CSDK Find Devices vs CSDK 4.1

PinpadSample AppConnection TypeFind Devices1st SALEFind DevicesConnect4.1 1st SALE4.1 Find/Connect
DefaultDefined ValuesDefaultDefined Values
Link 2500C♯/CWSUSB3.59 secs2.33 secs2.39 secs (OnDemandApp-CardReaderSearch)2.05 secs (OnDemandApp-CardReaderSearch)3.39 secs6.26 secs (OnDemandApp-CardReaderSearch)
Link 2500C♯/CWSWi-Fi17.39 secs16.89 secs17.23 secs (OnDemandApp-CardReaderSearch)15.64 secs (OnDemandApp-CardReaderSearch)17.00 secs2.60 secs (OnDemandApp-CardReaderSearch)
Link 2500AndroidWI-FI24 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen)17 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen)18 seconds (including time to select the device after initial find/connect to when it’s initialized) 18 sec13 seconds (including time to select the device after initial find/connect to when it’s initialized) 9 sec19 sec16 sec
Link 2500iOSWI-FI5 seconds5 seconds6 seconds4 seconds10 seconds8 seconds
Link 2500IOSBT6-7 seconds5 seconds5 seconds (including time to select the device after initial find/connect to when it’s initialized)5 seconds (including time to select the device after initial find/connect to when it’s initialized)12 secs (from starting SALE on sample app to Insert, Swipe or Tap screen)9 seconds
ICMPAndroidBT20 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen)8 seconds19 seconds (including time to select the device after initial find/connect to when it’s initialized)7 seconds (including time to select the device after initial find/connect to when it’s initialized)16 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen)9 seconds
ICMPIOSBT6 sec5 seconds6 seconds6 seconds12 secs (from starting SALE on sample app to Insert, Swipe or Tap screen)11 sec
ICMPC♯/CWSUSB4.74 secs2.23 secs5.92 secs (OnDemandApp-CardReaderSearch)2.46 secs (OnDemandApp-CardReaderSearch)4.42 secs7.54 secs (OnDemandApp-CardReaderSearch)
ROAMAndroidAudio21 sec13 sec22 seconds10 seconds33 seconds32 seconds
ROAMIOSBT42.75sec4.65 sec2.71 sec2.952.81sec
ISC250C♯/CWSUSB5.78 secs2.99 secs2.59 secs (OnDemandApp-CardReaderSearch)2.52 secs (OnDemandApp-CardReaderSearch)5.47 secs3.13 secs (OnDemandApp-CardReaderSearch)
ISC250C♯/CWSIP18.75 secs11.49 secs18.62 secs (OnDemandApp-CardReaderSearch)20.61 secs (OnDemanApp-CardReaderSearch)25.19 secs18.15 secs (OnDemandApp-CardReaderSearch)
iSC250iOSIP6 seconds5 seconds5-6 seconds5 seconds11 seconds11 seconds
IPP320C♯/CWSUSB4.93 secs2.64 secs2.52 secs (OnDemandApp-CardReaderSearch)2.44 secs (OnDemandApp-CardReaderSearch)4.27 secs2.25 secs (OnDemandApp-CardReaderSearch)
IPP320C♯/CWSIP21.30 secs17.29 secs6.59 secs (OnDemandApp-CardReaderSearch)2.51 secs (OnDemandApp-CardReaderSearch)22.03 secs16.07 secs (OnDemandApp-CardReaderSearch)

note

For C♯/CWS: CWS was stopped/restarted before every test run. Connection times reflect first transaction connection times.

Prerequisites for IP Configuration

  1. Configure the card reader to accept plain data transfer over IP.
  2. Establish IP-based communication channel between application and card reader.
  3. Enable SSL on the card reader (refer to the Client Certificate for IP Communication section of the appropriate integration method).

Code Samples

CWS

Request

PropertyDescription
method
string | required
setDeviceConnectionConfiguration
requestId
string | required
Transaction Request ID
targetType
string | required
api
parameters
JSONObject | required
All relevant parameters for card reader configuration.
connectionCriteria
JSONObject | required
Device Connection Criteria Holds the device connection parameters.
providerTypes
array | required
Device Provider Types
Valid values:
- INGENICO_RBA_UPP
- ROAM_RUA
- MAGTEK
- STAR
- EPSON
- RDM
connectionTypes
array | required
Connection Types
Valid values:
- USB
- BT
- IP
- AUDIO
deviceTypes
array | required
Device Types
Valid values:
- CARD_READER<BR> - PRINTER CHECK_READER
inetAddress
JSONObject | optional
INET Address
Specifies the host, port, and encryption scheme of the INET address.
Important: Required if connectionTypes contains IP.
host
string | required
Host
IP Address
port
int | required
Port Number
encryptionScheme
string | required
Encryption Scheme
Indicates whether or not the IP channel is TLS-enabled.
Set to TLS_12 to encrypt the data.

Response

PropertyDescription
requestId
string
Transaction Request ID As specified in the request.
statusDetails
string
Request Status
data
JSONObject
Object holding various responses.
completed
boolean
Request Result
Device configuration result.
Valid values:
- true
- false
error
string
If an error occurred.

Example

Request
{
  "method" : "setDeviceConnectionConfiguration",
  "requestId" : "1253881538",
  "targetType" : "api",
  "parameters" : {
    "connectionCriteria" : {
      "providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
      "connectionTypes" : ["USB", "IP"],
      "deviceTypes" : ["CARD_READER", "PRINTER"],
      "inetAddress" : {
        "host" : "192.168.1.137",
        "port" : 12000,
        "encryptionScheme" : "NONE"/"TLS_12"
      }
    }
  }
}
Response
{
  "requestId" : "1253881538",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "completed" : true
  }
}

getDeviceConnectionConfiguration

There is additional request/response for getDeviceConnectionConfiguration:

Request
PropertyDescription
method
string | required
getDeviceConnectionConfiguration
requestId
string | required
Transaction Request ID
targetType
string | required
api
Response
PropertyDescription
requestId
string
Transaction Request ID
As specified in the request.
statusDetails
string
Request Status
data
JSONObject
Object holding various responses.
completed
boolean
Request Result
Get Connection Configuration result.
connectionCriteria
JSONObject
Object holding the current connection criteria.
providerTypes
array
Array of Provider Types
connectionTypes
array
Array of Connection Types
deviceTypes
array
Array of Device Types
inetAddress
JSONObject
INET Address
Specifies the host, port, and encryption scheme of the INET address.
host
string
Host
IP Address
port
int
Port Number
encryptionScheme
string
Encryption Scheme
Indicates whether or not the IP channel is TLS-enabled.
Request
{
  "method" : "getDeviceConnectionConfiguration",
  "requestId" : "1253881539",
  "targetType" : "api"
}
Response
{
  "requestId" : "1253881539",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "completed" : true
    "connectionCriteria" : {
      "providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
      "connectionTypes" : ["USB", "IP"],
      "deviceTypes" : ["CARD_READER", "PRINTER"],
      "inetAddress" : {
        "host" : "192.168.1.137",
        "port" : 12000,
        "encryptionScheme" : "TLS_12"
      }
    }
  }
}

Java

Set Up

  1. Retrieve an instance of ECLConnectionConfiguration.

    The call to getInstance() returns a reference to a global singleton object, so you cannot have multiple ECLConnectionConfiguration at the same time.

  2. Create an ECLConnectionCriteria and set it.

  3. You can get the currently set ECLConnectionCriteria at any time.

Code Sample

ECLConnectionConfiguration config = ECLConnectionConfiguration.getInstance();
EnumSet<ECLDeviceProviderType> providerTypes = EnumSet.of(ECLDeviceProviderType.INGENICO_RBA_UPP, ECLDeviceProviderType.ROAM_RUA, ECLDeviceProviderType.STAR);
EnumSet<ECLConnectionType> connectionTypes = EnumSet.of(ECLConnectionType.AUDIO, ECLConnectionType.BT, ECLConnectionType.IP);
EnumSet<ECLDeviceType> deviceTypes = EnumSet.of(ECLDeviceType.CARD_READER, ECLDeviceType.PRINTER);
ECLConnectionCriteria.Builder criteriaBuilder = new ECLConnectionCriteria.Builder();
ECLConnectionCriteria criteria = criteriaBuilder
    .setEnabledDeviceProviderTypes(providerTypes)
    .setEnabledConnectionTypes(connectionTypes)
    .setEnabledDeviceTypes(deviceTypes)
    .setInetAddress(new ECLInetAddress(ip, port, ECLEncryptionScheme.TLS_12))
    .setConnectionParameters(connectionParameters)
    .setClientKeystoreDate(keystoreDateYYYYMMDD)
    .build();

try
{
     config.setConnectionCriteria(criteria);
}
catch (ECLCommerceException ece)
{
     showError("Connection Configuration Exception", "Error trying to set connection criteria: %s", ece.getCode().name());
}

//get
ECLConnectionCriteria currentCriteria = config.getConnectionCriteria();

Reset Connection Configuration

You can reset the connection configuration to the default, which will search for all supported devices.

try
{
     config.setConnectionCriteria(null);
}
catch (ECLCommerceException ece)
{
     //should not get this when setting to null
}

note

Do not reset the connection configuration while a device search is in progress.

Objective-C (iOS)

Set Up

  1. Use ECLConnectionConfiguration:sharedInstance to retrieve the global ECLConnectionConfiguration instance. The call to ECLConnectionConfiguration:sharedInstance returns a reference to a global singleton object, so you cannot have multiple ECLConnectionConfiguration at the same time.
  2. Create an ECLConnectionCriteria object and set it.
  3. You can get the currently set ECLConnectionCriteria at any time, using ECLConnectionConfiguration:getConnectionCriteria:.

Code Sample

// Get ECLConnectionConfiguration global instance...
ECLConnectionConfiguration *connectionConfiguration = [ECLConnectionConfiguration sharedInstance];

// Define what device providers, connection types, and device types you wish to search for...
NSSet <NSNumber *> *enabledDeviceProviderTypes = [NSSet setWithArray:@[@(ECLDeviceProviderType_INGENICO_RBA_UPP),@(ECLDeviceProviderType_ROAM_RUA),@(ECLDeviceProviderType_STAR)]];
NSSet <NSNumber *> *enabledConnectionTypes = [NSSet setWithArray:@[@(ECLConnectionType_AUDIO),@(ECLConnectionType_BT),@(ECLConnectionType_IP)]];
NSSet <NSNumber *> *enabledDeviceTypes = [NSSet setWithArray:@[@(ECLDeviceType_CARD_READER),@(ECLDeviceType_PRINTER)]];
ECLConnectionCriteria *criteria = [ECLConnectionCriteria makeWithBuilder:^(ECLConnectionCriteriaBuilder *builder) {
    builder.enabledDeviceProviderTypes = enabledDeviceProviderTypes;
    builder.enabledConnectionTypes = enabledConnectionTypes;
    builder.enabledDeviceTypes = enabledDeviceTypes;
    builder.inetAddress = [[ECLInetAddress alloc] initWithHostAndClientCertificateInfo:@"192.168.1.1"
        port:@(12000)
        encryptionScheme:ECLEncryptionScheme_TLS_12
        validClientPFXFilePath:certificateKeystorePath
        validClientPfxFilePasscode:certificateKeystorePassword
        validClientPfxFileDate:certificateKeystoreDate
        expiredClientPFXFilePath:expiredCertificateKeystorePath
        validPfxFilePasscode:expiredCertificateKeystorePasscode
    ];
}];

// Set the new search criteria for the global ECLConnectionConfiguration instance...
ECLError *error = [connectionConfiguration setConnectionCriteria:criteria];
if (error == nil)
{
    // No error? Then, the connection criteria has been successfully set!
}
else
{
    // If an error is returned, please see documentation for each possible ECLConnectionConfiguration:setConnectionCriteria: error (e.g. ECLConnectionCriteriaEmptyDeviceProviderTypes).
}

Reset Connection Configuration

You can reset the connection configuration to the default, just like in Java, which will search for all supported devices.

// Since the criteria is set to the default, ECLConnectionConfiguration:setConnectionCriteria: will always return nil.
ECLError *error = [connectionConfiguration setConnectionCriteria:nil];

C#

private void MySetDeviceConfigComplete(SetDeviceConfigResults crc)
{
     String statusDetails = crc.StatusDetails;
     if ((null != statusDetails) && (0 < statusDetails.Length))
         Log("Status Details: " + statusDetails);

     String error = crc.Error;
     if ((null != error) && (0 < error.Length))
         Log("Error: " + error);
     else
         Log("No error");
}

DeviceConnectionCriteria connCriteria = new DeviceConnectionCriteria();
connCriteria.providerTypes = new string[] { DeviceProviderType.INGENICO_RBA_UPP, DeviceProviderType.STAR };
connCriteria.connectionTypes = new string[] { ConnectionType.USB, ConnectionType.IP };
connCriteria.deviceTypes = new string[] { DeviceType.CARD_READER, DeviceType.PRINTER };
connCriteria.inetAddress = new InetAddress("121.121.12.12", 12000, EncryptionScheme.TLS_12);

DeviceConfigArgs args = new DeviceConfigArgs();
args.connectionCriteria = connCriteria;
m_CWS.StartSetDeviceConfig(args, MyNotifyCWSEvent, MySetDeviceConfigComplete);


// Get
private void MyGetDeviceConfigComplete(GetDeviceConfigResults crc)
{
     DeviceConnectionCriteria connCriteria = crc.GetConnectionCriteria;
}

m_CWS.StartGetDeviceConfig(MyNotifyCWSEvent, MyGetDeviceConfigComplete);