Card Reader Connection

Commerce SDK automatically handles locating and connecting to your card reader when you begin your first transaction in the Transactional API.

To use any of the on-demand methods, however, you must first manually connect the reader.

Connecting to the reader requires you to:

1. Create a Commerce SDK account to get an account interface.
2. Use your account interface to access the card reader interface.
3. Initiate a device search through the card reader interface.
4. Once search locates the reader, set it as the Active  device. All on-demand functions will run off on this device.

Card Reader Updates

At connection time, Commerce SDK automatically performs a device update if the operating system or configuration is out of date. After the update, you will receive a connectedAndInitialized callback and you will be able to begin using the on-demand functions on the card reader.

If you would like to have more control over when the device update occurs, you can instruct Commerce SDK to prevent updates to the device until you are ready. This option is documented in the code examples below. Please note that if you choose to prevent an update from taking place, you will be unable to use any functions on the device until it has been successfully updated.

If you are using the CWS or C# interfaces, you need to do one extra step to prevent updates from occuring. In the cws-config.properties file, you need to add updateCardReaderIfNecessary=false to prevent CWS from updating the first device it connects to when the process starts. After CWS has started, the updateIfNecessary value you pass in to the API methods below will override the value set in the properties file when you are ready to connect and update.

Code Samples

CWS

// Each of the three items in the parameters section below are optional
// timeout is a millisecond value that represents the amount of time CSDK should search for devices before it gives up
// updateIfNecessary controls whether or not an update is allowed to occur as part of a device connection
// connect boolean lets you specify whether or not you want CSDK to connect to the first device it finds (this is the default behavior)
{
  "method" : "startCardReadersSearch",
  "requestId" : "1",
  "targetType" : "cardReader",
  "version" : "1.0",
  "parameters" : {
    "timeout" : 9000,
    "updateIfNecessary":true,
    "connect":true
  }
}

// you will immediately receive back a response that looks like this
{
    "requestId": "1",
    "statusDetails": "REQUEST_ACCEPTED",
    "data": {
        "cardReadersSearch": {
            "timeout": 9000,
            "commandId": "1",
            "connect": true,
            "updateIfNecessary": true,
            "completed": false,
            "error": null,
            "cardReaders": []
        }
    }
}

// From this point on, while Commerce SDK is searching for a device for you, you will poll CWS by sending it status requests like this.
// The commandId should match the commandId you received from the last response.
{
  "method" : "getCardReadersSearchStatus",
  "requestId" : "2",
  "targetType" : "cardReader",
  "version" : "1.0",
  "parameters" : {
    "commandId" : "1"
  }
}

// You will immediately receive a response that contains the most current results of the search process.
// You can see that the search is finished because the completed flag is true.  If it was not true, you will need to continue polling cws until it is true.  
// One card reader was found in this case.  You should also check the error value to see if anything went wrong during the process.
{
    "requestId": "2",
    "statusDetails": "COMMAND_STATUS",
    "data": {
        "cardReadersSearch": {
            "timeout": 9000,
            "commandId": "1",
            "connect": true,
            "updateIfNecessary": true,
            "completed": true,
            "error": null,
            "cardReaders": [
                "iPP320"
            ]
        }
    }
}

Java

Simplified Connection Flow

Refer to the desktop sample application source code for more information.

On Android platform upon Commerce SDK trying to search device over an SSL-based IP channel, the certificate file and certificate key streams need to be reset prior to the search. This can be done in the callback method uponSearchingDevices on interface ECLFindDevicesListener as demonstrated in the sample code below.

// get a hold of the cardreaders interface
ECLDevicesInterface<ECLCardReaderInterface> cardReadersInterface = eclAccountInterface.getCardReaders();
// kick off a device search and setup a listener to receive callbacks from the search
cardReadersInterface.findDevices(new ECLFindDevicesListener() {
       @Override
       public void uponSearchingDevices(EnumSet<ECLConnectionType> connectionTypes)
       {
           if (connectionTypes.contains(ECLConnectionType.IP))
           {
               try
               {
                     Flavor.initializeCertificateFiles();
               }
               catch (IOException e)
               {
                     displayMessageInProgressView("failed to initialize certficate files", false);
                     return;
               }
           }
       }

       public void devicesSearchDone(List<ECLFindDevicesSearchResult> deviceSearchResults)
       {
              ...
              if (deviceSearchResults.size() > 0) {
                   ECLFindDevicesSearchResult result = deviceSearchResults.get(0);
                   // set this card reader as the active device
                   cardReaderInterface =
                        cardReadersInterface.selectDevice(result.getName(), result.getConnectionTypes());
                    ...
                   // add connection listener to receive disconnect callbacks
                   cardReaderInterface.addConnectionListener( new CardReaderListenerAdapter(...));
                   ....
                  // connect and initialize the device.  if an update is necessary, perform the update.
                  // if the parameter is set to false, the device will not be updated even if one was necessary.  In this case, if an update was needed, 
                  // you would receive a ECLCardReaderNeedsUpdate in your cardreaderconnectionorinitializationerror callback and the card reader would be disconnected.
                  // when you are ready for the card reader to be updated, you'd call connectAndInitialize again this time passing a parameter of "true"
                   cardReaderInterface.connectAndInitialize(true);
              }
        }

Objective-C

Simplified Flow

Refer to the sample application source code for more information.

// get a hold of card readers implementation of the devices protocol from the account
id<ECLDevicesProtocol> devices = [_account cardReaders];

// kick off a device search
[devices findDevices:self forceToDisconnect:true timeoutInSeconds:30];

// in this case we made the current class receive the findDevices callbacks (note the reference to "self" above)
...

// the implementation of one of the findDevices callbacks
+ (void)devicesSearchDone:(id<ECLDevicesProtocol>)devices searchResults:(NSArray<ECLFindDevicesSearchResult *> *)deviceSearchResults {
    ...
    if ([searchResults count] > 0) {
        // make this device the "active" device
        ECLFindDevicesSearchResult *reader = deviceSearchResults[0];
        id<ECLDeviceProtocol> selectedDevice = [devices selectDevice:reader.name withConnectionTypes:reader.connectionTypes];
        id<ECLCardReaderProtocol> selectedCardReader = (id<ECLCardReaderProtocol>)selectedDevice;

        // register this class to receive connection related callbacks
        [selectedCardReader addConnectionDelegate:self];

        // connect and initialize the device. if an update is necessary, perform the update.
        // if the parameter is set to NO, the device will not be updated even if one was necessary. In this case, if an update was needed,
        // you would receive a ECLCardReaderNeedsUpdate in your cardreaderconnectionorinitializationerror callback and the card reader would be disconnected.
        // when you are ready for the card reader to be updated, you'd call connectAndInitialize again this time passing a parameter of "YES"
        [selectedCardReader connectAndInitialize:YES];
        ...

C#

Device Search or Connection

Refer to the sample application source code for more information.

// start a card reader search and return a search results object which contains the list of attached card readers.  If only one device was found, it will be connected and initialized automatically.  
ReaderSearchResults rsr = m_CWS.ReaderSearch(null);