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 https://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.

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

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.

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.

Post Installation Verification

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

note

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

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

MethodDescription
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:
  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE

Response

MethodDescription
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:
  • true
  • false
logLevel
string
The log level that was set.

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.

MethodDescription
openPaymentGatewayThis method sends your Converge credentials to CWS.
Refer to the Installation - Send Converge Credentials section for more information.
startPaymentTransactionThis 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
cancelPaymentTransactionThis method integrates a payment cancellation transaction into your application.
This method is applicable to Cancel Transaction.
searchPaymentTransactionThis method integrates a lookup of previous transactions into your application.
This method is applicable to Transaction Lookup.
linkedRefundThis method integrates a linked refund to a cardholder’s payment card into your application.
This method is applicable to the Linked Refund transaction type.
printReceiptThis method integrates receipt printing into your application for a previous transaction or a historical transaction when the transactionId is present.
emailReceiptThis method integrates email sending into your application for a previous transaction or a historical transaction when the transactionId is present.
fileReceiptThis 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.
getPaymentTransactionStatusThis method integrates polling of status for the currently running transaction into your application.
continuePaymentTransactionThis 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.

MethodDescription
startCardReaderConfigurationThis method sets the IP connection criteria for the card reader.
getCommandStatusOnCardReaderThis is the polling method for all cardReader methods.
startCardReadersSearchThis method locates devices when starting your first transaction.
getCardReadersSearchStatusThis method retrieves the device search status.
startCardReadOnCardReaderThis 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.
startPinEntryOnCardReaderThis method directs the card reader to request for a PIN entry.
startResetOnCardReaderThis method returns the pinpad to the original welcome screen prior to an authorization.
setDailyRebootTimeOnCardReaderThis method reboots a PCI V4 pinpad after 24 hours of continuous running time.
startDeviceStatusOnCardReaderThis method retrieves the connection status, battery charging status and battery charge level of the pinpad device.
startRebootOnCardReaderThis method triggers the reboot of the card reader.
startAmountConfirmationOnCardReaderThis method triggers the card reader to prompt the customer to confirm or cancel the displayed amount.
startSignatureCaptureOnCardReaderThis 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.

MethodDescription
startPrintReceiptOnPrinterThis method controls the content printed on the receipt.
continuePrintReceiptOnPrinterThis method continues the printing of the receipt if startPrintReceiptOnPrinter requires more information.
cancelPrintReceiptOnPrinterThis method cancels the printing of the receipt.
getPrintReceiptStatusOnPrinterThis method polls the receipt print status.

api

This table describes the methods of the api target type.

MethodDescription
getApiInfoThis method retrieves the names and version numbers of various Commerce SDK modules.
setPreferencesThis method configures custom card reader and printer settings.
getVersionInfoThis method returns the name and version numbers of various Commerce SDK modules currently in use.
getEnvironmentInfoThis method returns details about the modules in use and runtime environment information about the platform.
getCardReaderInfoThis method retrieves information about the connected card reader.
getPrinterInfoThis method returns the printer name and online status.
overrideDefaultTerminalLanguageThis method overrides the language used on an RBA or UPP pinpad during a transaction.
overrideDebitNetworkPreferencesThis method overrides the US debit network preference used on an RBA or UPP pinpad during a transaction.
overrideCvmOptionsThis method overrides CVM options such as signature for card transactions.
setDeviceConnectionConfigurationThis method sets the connection configuration to specify which types of devices to search for.
getDeviceConnectionConfigurationThis method returns the current connection configuration.
setTransactionLaneNumberThis method specifies the lane number where transactions are performed.
setLogLevelThis method sets the CWS log level.
getLogLevelThis method returns the current log level.