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

Commerce Web Services (CWS) provides an HTTP API in the form of a web server that runs on the same workstation to which the payment terminal (card reader) and printer are connected.

## Request and response model

CWS uses a request-response model based on the concept of **Polling**. Elavon recommends a polling rate of **750ms** or higher.

When you send a request, a response returns confirming that CWS received the request and is processing it. From that point on, CWS polls periodically to ask for the status of your request.

For example, when running a `startPaymentTransaction` request, CWS polls with `getPaymentTransactionStatus`. While polling, you may receive updated progress status messages for long-running processes.

Response messages contain a `completed` parameters that reads as *false*  until CWS finishes processing the request. Once the `completed` parameter is set to *true*,  stop polling and read the transaction request results.

## Endpoint

Services are requested via HTTP POST with request and response payload in JSON format to <https://localhost:9790/rest/command>.

## Request and response structures

The core properties that define a CWS transaction request are:

- `method` - indicates the service to be performed
- `targetType` - indicates the type of request
- `requestId` - the unique identifier for tracking the request
- `parameters` - `method`-dependent properties detailing the specifics of the request

The core properties that define a CWS transaction response are:

- `completed` - indicates whether CWS has finished processing the transaction
- `chanId` - used to obtain status, and continue or cancel the current transaction
- `eventQueue` - lists the events the occurred and its corresponding timestamps

### Callbacks

Commerce SDK uses callbacks in a response to ask for additional information.

When you receive a callback, the `completed` flag is *false*, and there is a `requiredInformation` property detailing the request for more information.

:::::notice{note}

 The current request stops until you respond with a continue or cancel message.
:::::


## Installation

The CWS installer is a Windows desktop application bundle that includes the following components:

- Commerce SDK
- Commerce Web Services
- Card reader drivers
- Printer drivers
- System tray-accessible application (for CWS health monitoring)

**In this section:**

- [Windows operating systems](#windows-operating-systems)
- [Install CWS](#install-cws)
 - [Parameterized silent install](#parameterized-silent-install)
- [Post installation verification](#post-installation-verification)
- [Configure CWS log level](#configure-cws-log-level)

::section-heading-list{max-level=3} 


### Windows operating systems

You can only install CWS on Windows 7, 8, 8.1, 10, and 11.

### Install CWS

To install CWS, complete the following steps:

1. Connect your card reader and terminal to the computer.
2. Close all open applications and browsers.
3. Double-click `CommerceWebServicesSetup.exe`. The Commerce Web Service installation wizard appears.
4. On the *Welcome to CommerceWebServices Setup*  wizard page, click **Next**.
5. On the *Choose Install Location*  wizard page, select the **Destination Folder** then click **Install**.
6. On the *Installation Complete*  wizard page, click **Next**.
7. On the *Completing CommerceWebServices Setup*  wizard page, click **Finish**.
8. After 30 to 45 seconds, find the **ConvergeConnect** icon from the system tray.
9. Right-click the icon and click **Show...** to open the **ConvergeConnect** Status window.
10. Confirm that:
 - **Service** and **CWS** show *Running*.
 - **Port** shows *9790*.
 - The values of **Reader** and **Printer** match the hardware you connected in Step 1.

:::::notice{note}

 - CWS and ConvergeConnect start automatically when the computer boots up.
 - In such instances, run the CWS application or service as an administrator. The service will not run otherwise.
 - If outbound requests must go through a proxy on your network, make sure to select the **Bypass proxy server for local addresses** option from the Windows system proxy settings. You may also need to access the Advanced settings and add an Exception for  *localhost*.
:::::

#### Parameterized silent install

Customers should be able to run a silent install from the command line and only install the printers and checkreaders that they want. 

| Desire | Command | Result |
| --- | --- | --- |
| Install CWS with all printers and checkreaders | `cws.exe /S ` | CWS is installed along with all printers and checkreaders. |
| Install CWS but skip printer installs | `cws.exe /S -SKIP-PRINTER=all` | CWS is installed. Star & Epson printers are not installed. Checkreader is installed. |
| Install CWS but skip Epson printer install | `cws.exe /S -SKIP-PRINTER=epson` | CWS is installed. Star printer is installed. Checkreader is installed. |
| Install CWS but skip Star printer install | `cws.exe /S -SKIP-PRINTER=star` | CWS is installed. Epson printer is installed. Checkreader is installed. |
| Install CWS but skip checkreader install | `cws.exe /S -SKIP-CHECKREADER=all` | CWS is installed. Checkreader is not installed. All printers are installed. |
| Install CWS but skip printer and checkreader installs | `cws.exe /S -SKIP-PRINTER=all -SKIP-CHECKREADER=all` | CWS is installed. Printers are not installed. Checkreader is not installed. |
| Install CWS but skip Ingenico driver install | `cws.exe /S -SKIP-INGENICO=all` | CWS is installed. Ingenico drivers were not installed or updated if already existing on the machine. |
| Install CWS but skip reboot | `cws.exe /S -SKIP-REBOOT=1` | In some cases CWS a reboot is required for CWS to be fully installed. The customer is expected to trigger the reboot. To know whether a reboot is required look in the following:<ul><li>log for "A reboot is required in order to finish installing the product."</li><li>registry HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\RunOnce for after-reboot.exe</li></ul> |



### Post installation verification

To verify that CWS is working properly, send a `getEnvironmentInfo` request with a header for Content-Type of application/json.

:::::notice{note}

 You can use curl or a browser plugin like HttpRequester or Postman.
:::::


#### Example request

```json
{
 "method" : "getEnvironmentInfo",
 "requestId" : "d002edbd-010a-4c51-8407-f14b80c49bf4",
 "targetType" : "api",
 "version" : "1.0"
}
```

#### Response

```json
{
 "requestId": "d002edbd-010a-4c51-8407-f14b80c49bf4",
 "statusDetails": "REQUEST_ACCEPTED",
 "data": {
 "cwsInfo": {
 "name": "commerce-web-services",
 "version": "..."
 },
 "conconInfo": {
 "name": "converge-connect",
 "version": "..."
 },
 "comsdkInfo": {
 "componentVersions": [
 {
 "name": "commerce-core",
 "version": "..."
 },
 {
 "name": "commerce-converge",
 "version": "..."
 },
 {
 "name": "commerce-desktop-converge",
 "version": "..."
 },
 {
 "name": "ingenico-rba",
 "version": "..."
 },
 {
 "name": "ingenico-rba-wrapper",
 "version": "..."
 },
 {
 "name": "RBA",
 "version": "..."
 },
 {
 "name": "StarMicronics Printer",
 "version": "..."
 }
 ],
 "runtimeInformation": [
 {
 "name": "os.arch",
 "value": "..."
 },
 {
 "name": "os.name",
 "value": "..."
 },
 {
 "name": "os.version",
 "value": "..."
 },
 {
 "name": "java.version",
 "value": "..."
 },
 {
 "name": "java.vendor",
 "value": "..."
 }
 ]
 },
 "completed": true
 }
}
```

### Configure CWS log level
Starting with CommerceSDK release 4.6.0, you have the option to configure the CWS log level to output DEBUG and TRACE logging. Note that this feature should **not** be turned on by default. You should only configure the log level to DEBUG or TRACE when you need to diagnose a problem and send CWS logs to product support.

Below you will find the specific API method for setting the CWS log level. Note that the log level can also be configured via the openPaymentGateway method by passing "logLevel" as one of the parameters.

#### Request

| Method | Description |
| ---- | ---- |
| method string required | setLogLevel |
| requestId string required | Request ID |
| targetType string required | `api` |
| parameters JSONObject required | All relevant parameters for CWS log level. |
| logLevel string required | CWS log level Valid values:<ul><li>ERROR</li><li>WARN</li><li>INFO</li><li>DEBUG</li><li>TRACE</li></ul> |


#### Response

| Method | Description |
| ---- | ---- |
| requestId string | Request ID As specified in the request. |
| statusDetails string | Request status |
| data JSONObject | Object holding various responses. |
| completed boolean | Request result Valid values:<ul><li>true</li><li>false</li></ul> |
| logLevel string | The log level that was set. |

#### Request

```json
{
 "method" : "setLogLevel",
 "requestId" : "1253881538",
 "targetType" : "api",
 "parameters" : {
 "logLevel" : "DEBUG"
 }
}
```

#### Response

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

## Target types and methods

The main target types (`targetType`) that CWS provides are as follows:

- `paymentGatewayConverge` - This type of request post transactions to Converge.
- `cardReader` - This type of request changes card reader settings or runs card reader tasks.
- `printer` - This type of request prints receipts through the connected printer.
- `api` - This type of request retrieves device and/or environment information or overrides default debit network and language settings.

### paymentGatewayConverge

This table describes the methods of the `paymentGatewayConverge` target type.

| Method | Description |
| ---- | ---- |
| openPaymentGateway | This method sends your Converge credentials to CWS. Refer to the Installation - Send Converge Credentials section for more information. |
| startPaymentTransaction | This method integrates a payment transaction into your application. This method is applicable to these transaction types: Sale, Auth only, Convert auth to Sale, Auth only reversal, Void, and Stand alone refund |
| cancelPaymentTransaction | This method integrates a payment cancellation transaction into your application. This method is applicable to Cancel transaction. |
| searchPaymentTransaction | This method integrates a lookup of previous transactions into your application. This method is applicable to Transaction lookup. |
| linkedRefund | This method integrates a linked refund to a cardholder's payment card into your application. This method is applicable to the Linked refund transaction type. |
| printReceipt | This method integrates receipt printing into your application for a previous transaction or a historical transaction when the `transactionId` is present. |
| emailReceipt | This method integrates email sending into your application for a previous transaction or a historical transaction when the `transactionId` is present. |
| fileReceipt | This method integrates receipt saving into your application for a previous transaction or a historical transaction when the `transactionId` is present. CWS saves the receipt in the `logs` folder. |
| getPaymentTransactionStatus | This method integrates polling of status for the currently running transaction into your application. |
| continuePaymentTransaction | This method integrates the continuance of transaction processing into your application. This method is applicable to Continue transaction. |

### cardReader

This table describes the methods of the `cardReader` target type.

| Method | Description |
| ---- | ---- |
| startCardReaderConfiguration | This method sets the IP connection criteria for the card reader. |
| getCommandStatusOnCardReader | This is the polling method for all `cardReader` methods. |
| startCardReadersSearch | This method locates devices when starting your first transaction. |
| getCardReadersSearchStatus | This method retrieves the device search status. |
| startCardReadOnCardReader | This method perform an encrypted card read from a magnetic stripe card and returns the encrypted card data without the need for a Sale or Authorization transaction. |
| startPinEntryOnCardReader | This method directs the card reader to request for a PIN entry. |
| startResetOnCardReader | This method returns the pinpad to the original welcome screen prior to an authorization. |
| setDailyRebootTimeOnCardReader | This method reboots a PCI V4 pinpad after 24 hours of continuous running time. |
| startDeviceStatusOnCardReader | This method retrieves the connection status, battery charging status and battery charge level of the pinpad device. |
| startRebootOnCardReader | This method triggers the reboot of the card reader. |
| startAmountConfirmationOnCardReader | This method triggers the card reader to prompt the customer to confirm or cancel the displayed amount. |
| startSignatureCaptureOnCardReader | This method triggers the card reader to prompt the customer to submit a signature. |

### printer

This table describes the methods of the `printer` target type. Use these methods to print custom content on the receipt.

| Method | Description |
| ---- | ---- |
| startPrintReceiptOnPrinter | This method controls the content printed on the receipt. |
| continuePrintReceiptOnPrinter | This method continues the printing of the receipt if `startPrintReceiptOnPrinter` requires more information. |
| cancelPrintReceiptOnPrinter | This method cancels the printing of the receipt. |
| getPrintReceiptStatusOnPrinter | This method polls the receipt print status. |

### api

This table describes the methods of the `api` target type.

| Method | Description |
| ---- | ---- |
| getApiInfo | This method retrieves the names and version numbers of various Commerce SDK modules. |
| setPreferences | This method configures custom card reader and printer settings. |
| getVersionInfo | This method returns the name and version numbers of various Commerce SDK modules currently in use. |
| getEnvironmentInfo | This method returns details about the modules in use and runtime environment information about the platform. |
| getCardReaderInfo | This method retrieves information about the connected card reader. |
| getPrinterInfo | This method returns the printer name and online status. |
| overrideDefaultTerminalLanguage | This method overrides the language used on an RBA or UPP pinpad during a transaction. |
| overrideDebitNetworkPreferences | This method overrides the US debit network preference used on an RBA or UPP pinpad during a transaction. |
| overrideCvmOptions | This method overrides CVM options such as signature for card transactions. |
| setDeviceConnectionConfiguration | This method sets the connection configuration to specify which types of devices to search for. |
| getDeviceConnectionConfiguration | This method returns the current connection configuration. |
| setTransactionLaneNumber | This method specifies the lane number where transactions are performed. |
| setLogLevel | This method sets the CWS log level. |
| getLogLevel | This method returns the current log level. |