Commerce Web Services

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.

In this topic:

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 open_in_newhttps://localhost:9790/rest/commandLink opens new window.

Request and Response Structures

The core properties that define a CWS transaction request are:

• method - This indicates the service to be performed.
• targetType - This indicates the type of request.
• requestId - This is the unique identifier for tracking the request.
• parameters - These are 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.

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

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

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.

Post Installation Verification

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

Example Request

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

Response

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

Response

Request

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

Response

{
  "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.

cardReader

This table describes the methods of the cardReader target type.

printer

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

api

This table describes the methods of the api target type.