Elavon downloads and stores cookies on your device when you visit our website. We use these cookies to better understand and improve your browsing experience by identifying most visited pages, personalising content, and measuring site performance.

Essential cookies enable core functionality such as page navigation and access to secure areas. The website cannot function properly without these cookies; they can only be disabled by changing your browser preferences.

These are cookies that support site functionality that is visible or advantageous to you or your experience of the site, they enable websites to remember choices and provide a more personalized experience.   Functional cookies help to provide services that you request, such as language preference or layout.

Performance cookies help us to improve our website by collecting and reporting information on its usage (for example, which of our pages are most frequently visited).

These cookies and similar technologies gather information about your browsing habits. They remember that you've visited a website and share this information with other organisations, such as advertisers and platforms on which we advertise. They do this in order to provide you with ads that are more relevant to you and your interests. Although these cookies and similar technologies can track your visits to other websites, they don't usually know who you are. Without these cookies, online advertisements you encounter will be less relevant to you and your interests.

Cookie Settings

U.S. Bank Europe DAC. Registered in Ireland – Number 418442..  Registered Office: Block F1, Cherrywood Business Park, Dublin 18, D18 W2X7, Ireland.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is regulated by the Central Bank of Ireland.
 
U.S. Bank Europe DAC. Registered in Ireland with Companies Registration Office. The liability of the member is limited. United Kingdom branch registered in England and Wales under the number BR022122.
U.S. Bank Europe DAC, trading as Elavon Merchant Services, is a credit institution authorised and regulated by the Central Bank of Ireland.  Authorised by the Prudential Regulation Authority.  Subject to regulation by the Financial Conduct Authority and limited regulation by the Prudential Regulation Authority.  Details about the extent of our regulation by the Prudential Regulation Authority are available from us on request.

Most popular solutions

Additional solutions

Fusebox integration & options

Optional platform features

Documentation

North America

Europe

Regions

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].

:::::notice{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

| Pinpad | Sample app | Connection type | Find devices | 1st SALE | Find devices | Connect | 4.1 1st SALE | 4.1 Find/Connect |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| | | | *Default* | *Defined values* | *Default* | *Defined values* | | |
| Link/2500 | C♯/CWS | USB | 3.59 secs | 2.33 secs | 2.39 secs (OnDemandApp-CardReaderSearch) | 2.05 secs (OnDemandApp-CardReaderSearch) | 3.39 secs | 6.26 secs (OnDemandApp-CardReaderSearch) |
| Link/2500 | C♯/CWS | Wi-Fi | 17.39 secs | 16.89 secs | 17.23 secs (OnDemandApp-CardReaderSearch) | 15.64 secs (OnDemandApp-CardReaderSearch) | 17.00 secs | 2.60 secs (OnDemandApp-CardReaderSearch) |
| Link/2500 | Android | WI-FI | 24 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 sec | 13 seconds (including time to select the device after initial find/connect to when it's initialized) 9 sec | **19 sec** | 16 sec |
| Link/2500 | iOS | WI-FI | 5 seconds | **5 seconds** | 6 seconds | 4 seconds | **10 seconds** | 8 seconds |
| Link/2500 | IOS | BT | 6-7 seconds | **5 seconds** | 5 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 |
| iCMP | Android | BT | 20 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) | **8 seconds** | 19 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 |
| iCMP | IOS | BT | 6 sec | **5 seconds** | 6 seconds | 6 seconds | **12 secs** (from starting SALE on sample app to Insert, Swipe or Tap screen) | 11 sec |
| iCMP | C♯/CWS | USB | 4.74 secs | 2.23 secs | 5.92 secs (OnDemandApp-CardReaderSearch) | 2.46 secs (OnDemandApp-CardReaderSearch) | 4.42 secs | 7.54 secs (OnDemandApp-CardReaderSearch) |
| ROAM | Android | Audio | 21 sec | **13 sec** | 22 seconds | 10 seconds | **33 seconds** | 32 seconds |
| ROAM | IOS | BT | 4 | **2.75sec** | 4.65 sec | 2.71 sec | **2.95** | 2.81sec |
| iSC250 | C♯/CWS | USB | 5.78 secs | 2.99 secs | 2.59 secs (OnDemandApp-CardReaderSearch) | 2.52 secs (OnDemandApp-CardReaderSearch) | 5.47 secs | 3.13 secs (OnDemandApp-CardReaderSearch) |
| iSC250 | C♯/CWS | IP | 18.75 secs | 11.49 secs | 18.62 secs (OnDemandApp-CardReaderSearch) | 20.61 secs (OnDemanApp-CardReaderSearch) | 25.19 secs | 18.15 secs (OnDemandApp-CardReaderSearch) |
| iSC250 | iOS | IP | 6 seconds | **5 seconds** | 5-6 seconds | 5 seconds | **11 seconds** | 11 seconds |
| iPP320 | C♯/CWS | USB | 4.93 secs | 2.64 secs | 2.52 secs (OnDemandApp-CardReaderSearch) | 2.44 secs (OnDemandApp-CardReaderSearch) | 4.27 secs | 2.25 secs (OnDemandApp-CardReaderSearch) |
| iPP320 | C♯/CWS | IP | 21.30 secs | 17.29 secs | 6.59 secs (OnDemandApp-CardReaderSearch) | 2.51 secs (OnDemandApp-CardReaderSearch) | 22.03 secs | 16.07 secs (OnDemandApp-CardReaderSearch) |

:::::notice{note}

For C&sharp;&sol;CWS: CWS was stopped&sol;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

| Property | Description |
| --- | --- |
| 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:<ul><li>INGENICO_RBA_UPP</li><li>ROAM_RUA</li><li>MAGTEK</li><li>STAR</li><li>EPSON</li><li>RDM</li></ul> |
| connectionTypes array required | Connection types Valid values:<ul><li>USB</li><li>BT</li><li>IP</li><li>AUDIO</li></ul> |
| deviceTypes array required | Device types Valid values:<ul><li>CARD_READER</li><li>PRINTER CHECK_READER</li></ul> |
| 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 optional | Encryption scheme Indicates whether or not the IP channel is TLS-enabled. Set to *TLS_12* to encrypt the data. |
| csdkServerMode boolean optional | CSDK server mode Allowed values:<ul><li>True</li><li>False</li></ul> |
| terminalManagementSystem JSONObject required | Terminal Management System where values allow them to be used when connecting to a card reader prior to calling `openPaymentGateway`. |
| bmsUsername string required | The API username used when sending request to Bridge Maintenance System. |
| bmsPassword string required | The API password used when sending request to Bridge Maintenance System. |
| paymentGatewayEnvironment string required | Payment gateway environment Valid values:<ul><li>PROD</li><li>DEMO</li></ul> |
| proxyInfo JSONObject optional | Details for connecting through a network proxy. |
| address string required | Address IP address |
| port string required | Port number |
| user string optional | Username |
| password string optional | Password |


#### Response

| Property | Description |
| --- | --- |
| 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:<ul><li>true</li><li>false</li></ul> |
| error string | If an error occurred. |

#### Example

##### Request

```json
{
 "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"
 }
 }
 "terminalManagementSystem" : {
 "bmsUsername" : "******",
 "bmsPassword" : "******",
 "paymentGatewayEnvironment" : "DEMO",
 "proxyInfo" : {
 "address" : "******",
 "port" : "******",
 "user" : "******",
 "password" : "******"
 }
 }
 }
}
```

##### Response

```json
{
 "requestId" : "1253881538",
 "statusDetails" : "REQUEST_ACCEPTED",
 "data" : {
 "completed" : true
 }
}
```

#### getDeviceConnectionConfiguration

There is additional request/response for getDeviceConnectionConfiguration:

##### Request

| Property | Description |
| --- | --- |
| method string required | `getDeviceConnectionConfiguration` |
| requestId string required | Transaction request ID |
| targetType string required | `api` |

##### Response

| Property | Description |
| --- | --- |
| 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

```json
{
 "method" : "getDeviceConnectionConfiguration",
 "requestId" : "1253881538",
 "targetType" : "api",
}
```

##### Response

```json
{
 "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

```java
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.

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

:::::notice{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

```objc
// 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.

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

### C\# 

```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);

```